@aws-blocks/bb-agent 0.1.2 → 0.3.0

package/DESIGN.md

@@ -0,0 +1,66 @@
+# Agent — Design
+
+Design document for the Agent Building Block. For usage, see [README.md](./README.md).
+
+**Package:** `@aws-blocks/bb-agent`
+**Type:** Composite (uses DistributedTable, Realtime, AsyncJob, FileBucket internally)
+**AWS Services:** Bedrock, DynamoDB, S3, SQS, AppSync Events
+**Agent Framework:** [Strands Agents SDK](https://strandsagents.com/)
+
+## Architecture
+
+The Agent BB is a composite Building Block — it creates and manages 4 internal BBs:
+
+| Internal BB | Purpose | Created when |
+|-------------|---------|-------------|
+| **FileBucket** | Session persistence (Strands SessionManager) | Always |
+| **DistributedTable** | Frontend message history | `inferenceOnly: false` |
+| **Realtime** | Streaming chunks to caller | Always |
+| **AsyncJob** | Async agent execution (avoids 29s API Gateway timeout) | Always |
+
+```
+stream() → AsyncJob.submit() → returns { channelId } immediately
+                ↓
+         AsyncJob consumer
+                ↓
+         runAgent() → Strands agent loop → publishes chunks to Realtime
+                                         → persists messages to DistributedTable
+                                         → SessionManager saves state to FileBucket
+```
+
+## Session Persistence
+
+Two storage backends, same FileBucket BB:
+- **AWS:** Strands' native `S3Storage` → FileBucket-provisioned S3 bucket
+- **Local:** Custom `FileBucketSnapshotStorage` → FileBucket mock (mirrors S3Storage key layout exactly)
+
+## Infrastructure (CDK)
+
+The CDK class mirrors the runtime's BB creation:
+- **Bedrock IAM:** `InvokeModel` + `InvokeModelWithResponseStream` on all foundation models and inference profiles
+- **FileBucket:** `${id}-sessions` — session snapshot storage
+- **DistributedTable:** `${id}-messages` — conversation history (only when `inferenceOnly: false`)
+- **Realtime:** `${id}-rt` — streaming namespace `chunks`
+- **AsyncJob:** `${id}-job` — job payload: `{ message, conversationId?, channelId }`
+
+> **Note:** Internal Building Blocks are created on the parent scope (not `this`) to ensure correct nested-scope resolution on AWS.
+
+## Model Providers
+
+All providers are Strands model implementations, mapped from Blocks's `ModelConfig` via `model-factory.ts`:
+
+| Provider | Strands Class | Use Case |
+|----------|--------------|----------|
+| `canned` | `CannedProvider` (custom) | Local dev — keyword-based responses with tool call support |
+| `bedrock` | `BedrockModel` | AWS — Amazon Bedrock models |
+| `openai-api` | `OpenAIModel` | Any OpenAI-compatible endpoint (OpenAI, Ollama, vLLM) |
+
+## CannedProvider
+
+Custom Strands model provider for local development. No network, no API keys, no costs.
+
+- Returns instant keyword-based responses (e.g., prompt contains "weather" → weather response, otherwise a default canned response)
+- Streams word by word, matching the same `ModelStreamEvent` protocol as Bedrock/OpenAI
+- Triggers tool calls when the prompt mentions a tool name — splits camelCase names into words (e.g., "weather" matches `getWeather`) and emits Strands `toolUse` events
+- After Strands executes the tool and sends the result back, returns a fixed acknowledgment (`"I called the tool and got a result."`)
+- Token usage reports zeros (no real model call)

package/README.md

@@ -6,16 +6,17 @@ AI agent with streaming, tool calling, and conversation persistence. Powered by
 
 **Requires:** `zod` ^4.0.0 as a peer dependency. Tool parameters use Zod schemas for validation. If you see `ZodType missing properties` errors, check your zod version.
 
+> Design & mock parity details: [DESIGN.md](./DESIGN.md)
+
 ## Quick Start
 
 ```typescript
 import { Scope } from '@aws-blocks/core';
-import { Agent, BedrockModels } from '@aws-blocks/bb-agent';
+import { Agent } from '@aws-blocks/bb-agent';
 
 const scope = new Scope('my-app');
 
 const agent = new Agent(scope, 'support-agent', {
-  model: { deployed: BedrockModels.DEFAULT },
   systemPrompt: 'You are a helpful support agent.',
 });
 
@@ -28,7 +29,7 @@ const result = await agent.stream('Until when are you open tomorrow?', { convers
 const done = await result.complete();
 console.log(done.text); // "We're open until 6pm tomorrow."
 ```
-See [Tools](#tools) for adding capabilities, [Model Configuration](#model-configuration) for provider setup, and [Local Development](#local-development) for running without AWS Bedrock.
+Uses [`BedrockModels.BALANCED`](#bedrock-presets) (Claude Sonnet 4.6) by default. See [Model Configuration](#model-configuration) for other presets, [Tools](#tools) for adding capabilities, and [Local Development](#local-development) for running without AWS Bedrock.
 
 ## API
 
@@ -47,7 +48,7 @@ const agent = new Agent(scope, id, config)
 | `getPendingInterrupts(conversationId)` | `Promise<Array<...>>` | Get unanswered interrupts (for reload support). |
 | `getChannel(channelId)` | `Promise<RealtimeChannel>` | Get a Realtime channel for subscribing to chunks. |
 
-`stream()` submits the message to AsyncJob and returns immediately — no API Gateway timeout risk. The agent runs asynchronously and publishes chunks to Realtime.
+`stream()` submits the message to AsyncJob and returns immediately — no API Gateway timeout risk. The agent runs asynchronously and publishes chunks to Realtime. The channel ID is resolved as `options.channelId || options.conversationId || crypto.randomUUID()` — empty strings are treated as unset and fall through to the next value.
 
 **Important: Subscribe before sending.** The agent starts emitting chunks immediately after `stream()` is called. If you subscribe to the channel after calling `stream()`, early chunks may be dropped. Always subscribe first, await `established`, then send:
 
@@ -138,7 +139,7 @@ The `useChat` hook only surfaces `user`, `assistant`, and `approval` messages to
 
 ### Model Configuration
 
-Only `deployed` is required. Local development works out of the box — the canned provider (keyword-based mock) is used automatically when no local model is specified.
+Model configuration is optional. When omitted, the agent defaults to `BedrockModels.BALANCED` (Claude Sonnet 4.6) for deployment. Local development works out of the box — the canned provider (keyword-based mock) is used automatically when no local model is specified.
 
 | Option | Type | Description |
 |--------|------|-------------|
@@ -190,14 +191,14 @@ model: {
 
 #### Bedrock Presets
 
-Pre-configured model presets for quick setup. Names are capability-based so the underlying model can be upgraded without breaking your code. These use cross-region inference profiles — work across all AWS regions:
+Pre-configured model presets for quick setup. Names are capability-based so the underlying model can be upgraded without breaking your code. These use [global inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) — requests may be routed to any supported AWS region for optimal throughput. If your workload has data residency requirements, specify a region-scoped inference profile explicitly instead of using a preset.
 
 ```typescript
 import { Agent, BedrockModels} from '@aws-blocks/bb-agent';
 
 const agent = new Agent(scope, 'agent', {
   model: {
-    deployed: BedrockModels.DEFAULT,
+    deployed: BedrockModels.BALANCED,
   },
   systemPrompt: '...',
 });
@@ -205,15 +206,15 @@ const agent = new Agent(scope, 'agent', {
 
 | Preset | Current Model | Notes |
 |--------|---------------|-------|
-| `BedrockModels.DEFAULT` | `us.anthropic.claude-opus-4-8-20250610-v1:0` | Highest capability. Recommended default. |
-| `BedrockModels.BALANCED` | `us.anthropic.claude-sonnet-4-20250514-v1:0` | Strong quality/cost balance. |
-| `BedrockModels.FAST` | `us.anthropic.claude-haiku-4-5-20251001-v1:0` | Fastest, lowest latency. |
-| `BedrockModels.BUDGET` | `us.amazon.nova-pro-v1:0` | Low cost per token with acceptable quality. |
-| `BedrockModels.MICRO` | `us.amazon.nova-lite-v1:0` | Ultra-cheap for simple tasks. |
+| `BedrockModels.BALANCED` | `global.anthropic.claude-sonnet-4-6` | Great tool use, balanced cost. Recommended default for most workloads. |
+| `BedrockModels.SMART` | `global.anthropic.claude-opus-4-8` | Highest capability for the hardest tasks. |
+| `BedrockModels.FAST` | `global.anthropic.claude-haiku-4-5-20251001-v1:0` | Lowest latency, still strong capabilities. |
+
+> **Migrating?** `DEFAULT` → `BALANCED` (or `SMART` for highest capability). `BUDGET`/`MICRO` → `FAST`. The old presets are still available but deprecated. Please consider upgrading!
 
 Override inference settings with spread:
 ```typescript
-model: { deployed: { ...BedrockModels.DEFAULT, inferenceConfig: { temperature: 0.9, maxTokens: 8192 } } }
+model: { deployed: { ...BedrockModels.BALANCED, inferenceConfig: { temperature: 0.9, maxTokens: 8192 } } }
 ```
 
 #### Ollama Presets
@@ -225,7 +226,7 @@ import { Agent, BedrockModels, OllamaModels} from '@aws-blocks/bb-agent';
 
 const agent = new Agent(scope, 'agent', {
   model: {
-    deployed: BedrockModels.DEFAULT, 
+    deployed: BedrockModels.BALANCED, 
     local: OllamaModels.SMALL,
   },
   systemPrompt: '...',
@@ -262,7 +263,7 @@ To see detailed health check logs, pass a logger with `info` level:
 import { Logger } from '@aws-blocks/bb-logger';
 
 const agent = new Agent(scope, 'agent', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: '...',
   logger: new Logger(scope, 'agent-log', { level: 'info' }),
 });
@@ -541,7 +542,7 @@ The Agent BB works without a frontend — for scripts, background jobs, or serve
 import { Agent, BedrockModels } from '@aws-blocks/bb-agent';
 
 const agent = new Agent(scope, 'summarizer', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'Summarize the input concisely.',
 });
 
@@ -560,7 +561,7 @@ import { Agent, BedrockModels, InterruptError } from '@aws-blocks/bb-agent';
 import { z } from 'zod';
 
 const refundBot = new Agent(scope, 'refunds', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'You process customer refund requests.',
   tools: (tool) => ({
     issueRefund: tool({
@@ -687,7 +688,7 @@ import { Agent, BedrockModels } from '@aws-blocks/bb-agent';
 const scope = new Scope('my-app');
 
 const agent = new Agent(scope, 'chat', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'You are a helpful assistant.',
 });
 
@@ -751,7 +752,7 @@ const scope = new Scope('my-app');
 const kb = new KnowledgeBase(scope, 'docs', { source: './knowledge' });
 
 const agent = new Agent(scope, 'support', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'You are a customer support agent. Look up orders and search documentation to help the user.',
   toolContextSchema: z.object({ userId: z.string() }),
   tools: (tool) => ({

package/dist/agent.aws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.aws.d.ts","sourceRoot":"","sources":["../src/agent.aws.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAElE,qBAAa,KAAK,CAAC,QAAQ,GAAG,kBAAkB,CAAE,SAAQ,SAAS,CAAC,QAAQ,CAAC;gBAChE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC;CAGzE"}
+{"version":3,"file":"agent.aws.d.ts","sourceRoot":"","sources":["../src/agent.aws.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGlE,qBAAa,KAAK,CAAC,QAAQ,GAAG,kBAAkB,CAAE,SAAQ,SAAS,CAAC,QAAQ,CAAC;gBAChE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC;CAGzE"}

package/dist/agent.aws.js

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 import { AgentBase } from './agent.js';
 import { S3Storage } from '@strands-agents/sdk/session/s3-storage';
+import { BedrockModels } from './models.js';
 export class Agent extends AgentBase {
     constructor(scope, id, config) {
-        super(scope, id, config, config.model.deployed, (bucket) => new S3Storage({ bucket: bucket.fullId }));
+        super(scope, id, config, config.model?.deployed ?? BedrockModels.BALANCED, (bucket) => new S3Storage({ bucket: bucket.fullId }));
     }
 }

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -377,7 +377,7 @@ export class AgentBase extends Scope {
      */
     async stream(message, options) {
         const conversationId = options?.conversationId;
-        const channelId = options?.channelId ?? conversationId ?? crypto.randomUUID();
+        const channelId = options?.channelId || conversationId || crypto.randomUUID();
         if (!options?.userId && !this.config.inferenceOnly)
             throw blocksAgentError(AgentErrors.PersistenceRequired, 'userId is required when persistence is enabled. Pass it via options.userId.');
         const userId = options?.userId ?? 'anonymous';
@@ -405,6 +405,7 @@ export class AgentBase extends Scope {
                     }
                 });
             }),
+            toJSON() { return { channelId, channel: null }; },
         };
     }
     /**

package/dist/agent.mock.js

@@ -5,7 +5,7 @@ import { FileBucketSnapshotStorage } from './file-bucket-snapshot-storage.js';
 export class Agent extends AgentBase {
     constructor(scope, id, config) {
         // Canned provider is appended as implicit last fallback for local dev
-        const local = config.model.local;
+        const local = config.model?.local;
         const candidates = local ? (Array.isArray(local) ? [...local, { provider: 'canned' }] : [local, { provider: 'canned' }]) : [{ provider: 'canned' }];
         super(scope, id, config, candidates, (bucket) => new FileBucketSnapshotStorage(bucket));
     }

package/dist/index.test.js

@@ -97,6 +97,34 @@ describe('needsApproval and interrupt mutual exclusivity', () => {
         assert.ok(result.channelId);
     });
 });
+// ── AgentStreamResult.toJSON() ───────────────────────────────────────────────
+describe('AgentStreamResult.toJSON()', () => {
+    test('serializes to { channelId, channel: null }', async () => {
+        const scope = new Scope('test-tojson');
+        const agent = new Agent(scope, 'tj', { systemPrompt: 'test', model: { deployed: { provider: 'canned' }, local: { provider: 'canned' } } });
+        const result = await agent.stream('hello', { userId: 'test-user' });
+        const serialized = JSON.parse(JSON.stringify(result));
+        assert.deepStrictEqual(serialized, { channelId: result.channelId, channel: null });
+        assert.strictEqual('complete' in serialized, false);
+    });
+});
+// ── stream() empty channelId fallback ────────────────────────────────────────
+describe('stream() empty channelId fallback', () => {
+    test('empty channelId is treated as unset', async () => {
+        const scope = new Scope('test-empty-ch');
+        const agent = new Agent(scope, 'ec', { systemPrompt: 'test', model: { deployed: { provider: 'canned' }, local: { provider: 'canned' } } });
+        const result = await agent.stream('hello', { userId: 'test-user', channelId: '' });
+        assert.notStrictEqual(result.channelId, '');
+        assert.ok(result.channelId.length > 0);
+    });
+    test('empty conversationId is treated as unset', async () => {
+        const scope = new Scope('test-empty-conv');
+        const agent = new Agent(scope, 'ev', { systemPrompt: 'test', model: { deployed: { provider: 'canned' }, local: { provider: 'canned' } } });
+        const result = await agent.stream('hello', { userId: 'test-user', conversationId: '' });
+        assert.notStrictEqual(result.channelId, '');
+        assert.ok(result.channelId.length > 0);
+    });
+});
 // ── tool factory enforcement (compile-time) ──────────────────────────────────
 describe('tool factory enforcement', () => {
     // Regression: AgentConfig.tools is a callback `(tool) => Record<string, AgentTool>`.
@@ -839,10 +867,17 @@ describe('checkModelHealth', () => {
     });
 });
 // ── Model Presets ─────────────────────────────────────────────────────────────
+describe('default model', () => {
+    test('agent can be created without model config', () => {
+        const s = new Scope('test-default-model');
+        const agent = new Agent(s, 'no-model', { systemPrompt: 'test' });
+        assert.ok(agent);
+    });
+});
 describe('BedrockModels presets', () => {
-    test('DEFAULT resolves to a bedrock provider', async () => {
-        assert.strictEqual(BedrockModels.DEFAULT.provider, 'bedrock');
-        assert.ok(BedrockModels.DEFAULT.modelId);
+    test('BALANCED resolves to a bedrock provider', async () => {
+        assert.strictEqual(BedrockModels.BALANCED.provider, 'bedrock');
+        assert.ok(BedrockModels.BALANCED.modelId);
     });
     test('all presets have provider bedrock and a modelId', () => {
         for (const [name, config] of Object.entries(BedrockModels)) {
@@ -850,8 +885,8 @@ describe('BedrockModels presets', () => {
             assert.ok(config.modelId, `${name} should have a modelId`);
         }
     });
-    test('DEFAULT flows through createStrandsModel to BedrockModel', async () => {
-        const model = await createStrandsModel(BedrockModels.DEFAULT);
+    test('BALANCED flows through createStrandsModel to BedrockModel', async () => {
+        const model = await createStrandsModel(BedrockModels.BALANCED);
         assert.ok(model, 'should create a model instance');
     });
 });

package/dist/models.d.ts

@@ -1,32 +1,42 @@
 /**
- * Pre-configured Bedrock model presets using cross-region inference profiles.
+ * Pre-configured Bedrock model presets using global inference profiles.
  * Names are capability-based so the underlying model can be upgraded without breaking user code.
+ *
+ * **Note:** Global inference profiles route requests to any supported AWS region for
+ * optimal throughput. If your workload has data residency requirements, specify a
+ * region-scoped inference profile explicitly.
+ * @see https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html
  */
 export declare const BedrockModels: {
-    /** Highest capability and best performance. Recommended default. Currently: Claude Opus 4.8. */
-    readonly DEFAULT: {
+    /** Great tool use, balanced cost — good middle tier for most workloads. Currently: Claude Sonnet 4.6. */
+    readonly BALANCED: {
         readonly provider: "bedrock";
-        readonly modelId: "us.anthropic.claude-opus-4-8-20250610-v1:0";
+        readonly modelId: "global.anthropic.claude-sonnet-4-6";
     };
-    /** Strong quality/cost balance. Currently: Claude Sonnet 4. */
-    readonly BALANCED: {
+    /** Highest capability for the hardest tasks. Currently: Claude Opus 4.8. */
+    readonly SMART: {
         readonly provider: "bedrock";
-        readonly modelId: "us.anthropic.claude-sonnet-4-20250514-v1:0";
+        readonly modelId: "global.anthropic.claude-opus-4-8";
     };
-    /** Fastest and lowest latency. Currently: Claude Haiku 4.5. */
+    /** Lowest latency, still strong capabilities. Currently: Claude Haiku 4.5. */
     readonly FAST: {
         readonly provider: "bedrock";
-        readonly modelId: "us.anthropic.claude-haiku-4-5-20251001-v1:0";
+        readonly modelId: "global.anthropic.claude-haiku-4-5-20251001-v1:0";
+    };
+    /** @deprecated Use `BedrockModels.BALANCED` instead. */
+    readonly DEFAULT: {
+        readonly provider: "bedrock";
+        readonly modelId: "global.anthropic.claude-sonnet-4-6";
     };
-    /** Low cost per token with acceptable quality. Currently: Amazon Nova Pro. */
+    /** @deprecated Use `BedrockModels.FAST` instead. */
     readonly BUDGET: {
         readonly provider: "bedrock";
-        readonly modelId: "us.amazon.nova-pro-v1:0";
+        readonly modelId: "global.anthropic.claude-haiku-4-5-20251001-v1:0";
     };
-    /** Ultra-cheap for simple tasks. Currently: Amazon Nova Lite. */
+    /** @deprecated Use `BedrockModels.FAST` instead. */
     readonly MICRO: {
         readonly provider: "bedrock";
-        readonly modelId: "us.amazon.nova-lite-v1:0";
+        readonly modelId: "global.anthropic.claude-haiku-4-5-20251001-v1:0";
     };
 };
 /**

package/dist/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,eAAO,MAAM,aAAa;IACzB,gGAAgG;;;;;IAKhG,+DAA+D;;;;;IAK/D,+DAA+D;;;;;IAK/D,8EAA8E;;;;;IAK9E,iEAAiE;;;;;CAKlB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY;IACxB,kGAAkG;;;;;;;IAOlG,gGAAgG;;;;;;;IAOhG,+FAA+F;;;;;;;IAO/F,4FAA4F;;;;;;;IAO5F,iFAAiF;;;;;;;CAOlC,CAAC"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;IACzB,yGAAyG;;;;;IAKzG,4EAA4E;;;;;IAK5E,8EAA8E;;;;;IAM9E,wDAAwD;;;;;IAKxD,oDAAoD;;;;;IAKpD,oDAAoD;;;;;CAKL,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY;IACxB,kGAAkG;;;;;;;IAOlG,gGAAgG;;;;;;;IAOhG,+FAA+F;;;;;;;IAQ/F,4FAA4F;;;;;;;IAO5F,iFAAiF;;;;;;;CAOlC,CAAC"}

package/dist/models.js

@@ -1,34 +1,47 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+const BALANCED_MODEL_ID = 'global.anthropic.claude-sonnet-4-6';
+const SMART_MODEL_ID = 'global.anthropic.claude-opus-4-8';
+const FAST_MODEL_ID = 'global.anthropic.claude-haiku-4-5-20251001-v1:0';
 /**
- * Pre-configured Bedrock model presets using cross-region inference profiles.
+ * Pre-configured Bedrock model presets using global inference profiles.
  * Names are capability-based so the underlying model can be upgraded without breaking user code.
+ *
+ * **Note:** Global inference profiles route requests to any supported AWS region for
+ * optimal throughput. If your workload has data residency requirements, specify a
+ * region-scoped inference profile explicitly.
+ * @see https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html
  */
 export const BedrockModels = {
-    /** Highest capability and best performance. Recommended default. Currently: Claude Opus 4.8. */
-    DEFAULT: {
+    /** Great tool use, balanced cost — good middle tier for most workloads. Currently: Claude Sonnet 4.6. */
+    BALANCED: {
         provider: 'bedrock',
-        modelId: 'us.anthropic.claude-opus-4-8-20250610-v1:0',
+        modelId: BALANCED_MODEL_ID,
     },
-    /** Strong quality/cost balance. Currently: Claude Sonnet 4. */
-    BALANCED: {
+    /** Highest capability for the hardest tasks. Currently: Claude Opus 4.8. */
+    SMART: {
         provider: 'bedrock',
-        modelId: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+        modelId: SMART_MODEL_ID,
     },
-    /** Fastest and lowest latency. Currently: Claude Haiku 4.5. */
+    /** Lowest latency, still strong capabilities. Currently: Claude Haiku 4.5. */
     FAST: {
         provider: 'bedrock',
-        modelId: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+        modelId: FAST_MODEL_ID,
+    },
+    /** @deprecated Use `BedrockModels.BALANCED` instead. */
+    DEFAULT: {
+        provider: 'bedrock',
+        modelId: BALANCED_MODEL_ID,
     },
-    /** Low cost per token with acceptable quality. Currently: Amazon Nova Pro. */
+    /** @deprecated Use `BedrockModels.FAST` instead. */
     BUDGET: {
         provider: 'bedrock',
-        modelId: 'us.amazon.nova-pro-v1:0',
+        modelId: FAST_MODEL_ID,
     },
-    /** Ultra-cheap for simple tasks. Currently: Amazon Nova Lite. */
+    /** @deprecated Use `BedrockModels.FAST` instead. */
     MICRO: {
         provider: 'bedrock',
-        modelId: 'us.amazon.nova-lite-v1:0',
+        modelId: FAST_MODEL_ID,
     },
 };
 /**
@@ -61,6 +74,7 @@ export const OllamaModels = {
         apiKey: 'ollama',
     },
     /** Strong reasoning at moderate size. Currently: DeepSeek R1 14B (~9 GB, needs 16 GB VRAM). */
+    // TODO: DeepSeek R1 is strong at reasoning but weak at tool calling — swap to a more tool-capable model.
     MEDIUM: {
         provider: 'openai-api',
         modelId: 'deepseek-r1:14b',

package/dist/types.d.ts

@@ -41,9 +41,9 @@ export interface AgentConfig<TContext = DefaultToolContext> {
      * The agent does inference + tools only — no conversation history.
      */
     inferenceOnly?: boolean;
-    model: {
-        /** Model(s) for AWS deployment. Tries candidates in order; throws if all fail. */
-        deployed: ModelConfig | ModelConfig[];
+    model?: {
+        /** Model(s) for AWS deployment. Tries candidates in order; throws if all fail. Defaults to BedrockModels.BALANCED. */
+        deployed?: ModelConfig | ModelConfig[];
         /** Model(s) for local development. Tries candidates in order; canned is implicit last fallback. */
         local?: ModelConfig | ModelConfig[];
     };
@@ -235,7 +235,7 @@ export interface ToolCallRecord {
 }
 export interface StreamOptions<TContext = DefaultToolContext> {
     conversationId?: string;
-    /** Channel ID for Realtime delivery. Defaults to conversationId or a random UUID. */
+    /** Channel ID for Realtime delivery. Defaults to conversationId or a random UUID. Empty strings are treated as unset. */
     channelId?: string;
     /** User ID for conversation scoping. Defaults to 'anonymous'. */
     userId?: string;
@@ -247,14 +247,33 @@ export interface StreamOptions<TContext = DefaultToolContext> {
      */
     context?: TContext;
 }
-/** Returned by stream(). Provides the channelId and server-side convenience methods. */
+/**
+ * Returned by stream(). Provides the channelId and server-side convenience methods.
+ *
+ * Safe to return directly from API methods — `toJSON()` serializes to
+ * `{ channelId, channel: null }`. Only `channelId` is meaningful client-side;
+ * `channel` is explicitly `null` to signal the live handle is server-side only,
+ * and the `complete()` helper is dropped (functions don't serialize).
+ */
 export interface AgentStreamResult {
     /** Realtime channel ID where chunks are published. */
     channelId: string;
-    /** Realtime channel handle — subscribe to streaming chunks or return to client as Transferable. */
+    /**
+     * Realtime channel handle (server-side only). Nulled by `toJSON()` — clients subscribe from `channelId` instead.
+     *
+     * @remarks
+     * Unlike `RealtimeChannel.toJSON()` which produces a hydratable descriptor, this is nulled
+     * because it's a `Promise` that can't round-trip. Clients reconstruct a subscribe-only
+     * channel from `channelId` via the `useChat` `subscribe` callback.
+     */
     channel: Promise<RealtimeChannel<AgentStreamChunk>>;
     /** Wait for the complete response (server-side). Resolves when the done chunk arrives. */
     complete: () => Promise<AgentStreamChunk>;
+    /** Only `{ channelId, channel: null }` is serialized when this object crosses the RPC boundary. */
+    toJSON(): {
+        channelId: string;
+        channel: null;
+    };
 }
 export interface AgentStreamChunk {
     type: 'text-delta' | 'tool-call' | 'tool-result' | 'done' | 'error' | 'interrupt';

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "Agent";
-export declare const BB_VERSION = "0.1.2";
+export declare const BB_VERSION = "0.3.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'Agent';
-export const BB_VERSION = '0.1.2';
+export const BB_VERSION = '0.3.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-agent",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -8,6 +8,7 @@
     "dist",
     "MODELS.md",
     "README.md",
+    "DESIGN.md",
     "src",
     "LICENSE"
   ],
@@ -33,12 +34,12 @@
     "test": "node --test dist/index.test.js"
   },
   "dependencies": {
-    "@aws-blocks/bb-async-job": "^0.1.1",
-    "@aws-blocks/bb-distributed-table": "^0.1.1",
-    "@aws-blocks/bb-file-bucket": "^0.1.1",
-    "@aws-blocks/bb-logger": "^0.1.1",
-    "@aws-blocks/bb-realtime": "^0.1.1",
-    "@aws-blocks/core": "^0.1.1",
+    "@aws-blocks/bb-async-job": "^0.1.2",
+    "@aws-blocks/bb-distributed-table": "^0.1.3",
+    "@aws-blocks/bb-file-bucket": "^0.1.2",
+    "@aws-blocks/bb-logger": "^0.1.2",
+    "@aws-blocks/bb-realtime": "^0.1.2",
+    "@aws-blocks/core": "^0.1.10",
     "@aws-sdk/client-bedrock": "^3.700.0",
     "@strands-agents/sdk": "~1.3.0",
     "openai": "^6.7.0",

package/src/agent.aws.ts

@@ -5,9 +5,10 @@ import type { ScopeParent } from '@aws-blocks/core';
 import { AgentBase } from './agent.js';
 import { S3Storage } from '@strands-agents/sdk/session/s3-storage';
 import type { AgentConfig, DefaultToolContext } from './types.js';
+import { BedrockModels } from './models.js';
 
 export class Agent<TContext = DefaultToolContext> extends AgentBase<TContext> {
 	constructor(scope: ScopeParent, id: string, config: AgentConfig<TContext>) {
-		super(scope, id, config, config.model.deployed, (bucket) => new S3Storage({ bucket: bucket.fullId }));
+		super(scope, id, config, config.model?.deployed ?? BedrockModels.BALANCED, (bucket) => new S3Storage({ bucket: bucket.fullId }));
 	}
 }

package/src/agent.mock.ts

@@ -9,7 +9,7 @@ import type { AgentConfig, DefaultToolContext } from './types.js';
 export class Agent<TContext = DefaultToolContext> extends AgentBase<TContext> {
 	constructor(scope: ScopeParent, id: string, config: AgentConfig<TContext>) {
 		// Canned provider is appended as implicit last fallback for local dev
-		const local = config.model.local;
+		const local = config.model?.local;
 		const candidates = local ? (Array.isArray(local) ? [...local, { provider: 'canned' as const }] : [local, { provider: 'canned' as const }]) : [{ provider: 'canned' as const }];
 		super(scope, id, config, candidates, (bucket) => new FileBucketSnapshotStorage(bucket));
 	}

package/src/agent.ts

@@ -403,7 +403,7 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 	 */
 	async stream(message: string, options?: StreamOptions<TContext>): Promise<AgentStreamResult> {
 		const conversationId = options?.conversationId;
-		const channelId = options?.channelId ?? conversationId ?? crypto.randomUUID();
+		const channelId = options?.channelId || conversationId || crypto.randomUUID();
 		if (!options?.userId && !this.config.inferenceOnly) throw blocksAgentError(AgentErrors.PersistenceRequired, 'userId is required when persistence is enabled. Pass it via options.userId.');
 		const userId = options?.userId ?? 'anonymous';
 		const context = this.resolveContext(options?.context);
@@ -428,6 +428,7 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 					}
 				});
 			}),
+			toJSON() { return { channelId, channel: null }; },
 		};
 	}
 

package/src/index.test.ts

@@ -115,6 +115,39 @@ describe('needsApproval and interrupt mutual exclusivity', () => {
 	});
 });
 
+// ── AgentStreamResult.toJSON() ───────────────────────────────────────────────
+
+describe('AgentStreamResult.toJSON()', () => {
+	test('serializes to { channelId, channel: null }', async () => {
+		const scope = new Scope('test-tojson');
+		const agent = new Agent(scope, 'tj', { systemPrompt: 'test', model: { deployed: { provider: 'canned' }, local: { provider: 'canned' } } });
+		const result = await agent.stream('hello', { userId: 'test-user' });
+		const serialized = JSON.parse(JSON.stringify(result));
+		assert.deepStrictEqual(serialized, { channelId: result.channelId, channel: null });
+		assert.strictEqual('complete' in serialized, false);
+	});
+});
+
+// ── stream() empty channelId fallback ────────────────────────────────────────
+
+describe('stream() empty channelId fallback', () => {
+	test('empty channelId is treated as unset', async () => {
+		const scope = new Scope('test-empty-ch');
+		const agent = new Agent(scope, 'ec', { systemPrompt: 'test', model: { deployed: { provider: 'canned' }, local: { provider: 'canned' } } });
+		const result = await agent.stream('hello', { userId: 'test-user', channelId: '' });
+		assert.notStrictEqual(result.channelId, '');
+		assert.ok(result.channelId.length > 0);
+	});
+
+	test('empty conversationId is treated as unset', async () => {
+		const scope = new Scope('test-empty-conv');
+		const agent = new Agent(scope, 'ev', { systemPrompt: 'test', model: { deployed: { provider: 'canned' }, local: { provider: 'canned' } } });
+		const result = await agent.stream('hello', { userId: 'test-user', conversationId: '' });
+		assert.notStrictEqual(result.channelId, '');
+		assert.ok(result.channelId.length > 0);
+	});
+});
+
 // ── tool factory enforcement (compile-time) ──────────────────────────────────
 
 describe('tool factory enforcement', () => {
@@ -983,10 +1016,18 @@ describe('checkModelHealth', () => {
 
 // ── Model Presets ─────────────────────────────────────────────────────────────
 
+describe('default model', () => {
+	test('agent can be created without model config', () => {
+		const s = new Scope('test-default-model');
+		const agent = new Agent(s, 'no-model', { systemPrompt: 'test' });
+		assert.ok(agent);
+	});
+});
+
 describe('BedrockModels presets', () => {
-	test('DEFAULT resolves to a bedrock provider', async () => {
-		assert.strictEqual(BedrockModels.DEFAULT.provider, 'bedrock');
-		assert.ok(BedrockModels.DEFAULT.modelId);
+	test('BALANCED resolves to a bedrock provider', async () => {
+		assert.strictEqual(BedrockModels.BALANCED.provider, 'bedrock');
+		assert.ok(BedrockModels.BALANCED.modelId);
 	});
 
 	test('all presets have provider bedrock and a modelId', () => {
@@ -996,8 +1037,8 @@ describe('BedrockModels presets', () => {
 		}
 	});
 
-	test('DEFAULT flows through createStrandsModel to BedrockModel', async () => {
-		const model = await createStrandsModel(BedrockModels.DEFAULT);
+	test('BALANCED flows through createStrandsModel to BedrockModel', async () => {
+		const model = await createStrandsModel(BedrockModels.BALANCED);
 		assert.ok(model, 'should create a model instance');
 	});
 });

package/src/models.ts

@@ -3,35 +3,50 @@
 
 import type { ModelConfig } from './types.js';
 
+const BALANCED_MODEL_ID = 'global.anthropic.claude-sonnet-4-6';
+const SMART_MODEL_ID = 'global.anthropic.claude-opus-4-8';
+const FAST_MODEL_ID = 'global.anthropic.claude-haiku-4-5-20251001-v1:0';
+
 /**
- * Pre-configured Bedrock model presets using cross-region inference profiles.
+ * Pre-configured Bedrock model presets using global inference profiles.
  * Names are capability-based so the underlying model can be upgraded without breaking user code.
+ *
+ * **Note:** Global inference profiles route requests to any supported AWS region for
+ * optimal throughput. If your workload has data residency requirements, specify a
+ * region-scoped inference profile explicitly.
+ * @see https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html
  */
 export const BedrockModels = {
-	/** Highest capability and best performance. Recommended default. Currently: Claude Opus 4.8. */
-	DEFAULT: {
+	/** Great tool use, balanced cost — good middle tier for most workloads. Currently: Claude Sonnet 4.6. */
+	BALANCED: {
 		provider: 'bedrock',
-		modelId: 'us.anthropic.claude-opus-4-8-20250610-v1:0',
+		modelId: BALANCED_MODEL_ID,
 	},
-	/** Strong quality/cost balance. Currently: Claude Sonnet 4. */
-	BALANCED: {
+	/** Highest capability for the hardest tasks. Currently: Claude Opus 4.8. */
+	SMART: {
 		provider: 'bedrock',
-		modelId: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+		modelId: SMART_MODEL_ID,
 	},
-	/** Fastest and lowest latency. Currently: Claude Haiku 4.5. */
+	/** Lowest latency, still strong capabilities. Currently: Claude Haiku 4.5. */
 	FAST: {
 		provider: 'bedrock',
-		modelId: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+		modelId: FAST_MODEL_ID,
+	},
+
+	/** @deprecated Use `BedrockModels.BALANCED` instead. */
+	DEFAULT: {
+		provider: 'bedrock',
+		modelId: BALANCED_MODEL_ID,
 	},
-	/** Low cost per token with acceptable quality. Currently: Amazon Nova Pro. */
+	/** @deprecated Use `BedrockModels.FAST` instead. */
 	BUDGET: {
 		provider: 'bedrock',
-		modelId: 'us.amazon.nova-pro-v1:0',
+		modelId: FAST_MODEL_ID,
 	},
-	/** Ultra-cheap for simple tasks. Currently: Amazon Nova Lite. */
+	/** @deprecated Use `BedrockModels.FAST` instead. */
 	MICRO: {
 		provider: 'bedrock',
-		modelId: 'us.amazon.nova-lite-v1:0',
+		modelId: FAST_MODEL_ID,
 	},
 } as const satisfies Record<string, ModelConfig>;
 
@@ -65,6 +80,7 @@ export const OllamaModels = {
 		apiKey: 'ollama',
 	},
 	/** Strong reasoning at moderate size. Currently: DeepSeek R1 14B (~9 GB, needs 16 GB VRAM). */
+	// TODO: DeepSeek R1 is strong at reasoning but weak at tool calling — swap to a more tool-capable model.
 	MEDIUM: {
 		provider: 'openai-api',
 		modelId: 'deepseek-r1:14b',

package/src/types.ts

@@ -48,9 +48,9 @@ export interface AgentConfig<TContext = DefaultToolContext> {
 	 * The agent does inference + tools only — no conversation history.
 	 */
 	inferenceOnly?: boolean;
-	model: {
-		/** Model(s) for AWS deployment. Tries candidates in order; throws if all fail. */
-		deployed: ModelConfig | ModelConfig[];
+	model?: {
+		/** Model(s) for AWS deployment. Tries candidates in order; throws if all fail. Defaults to BedrockModels.BALANCED. */
+		deployed?: ModelConfig | ModelConfig[];
 		/** Model(s) for local development. Tries candidates in order; canned is implicit last fallback. */
 		local?: ModelConfig | ModelConfig[];
 	};
@@ -251,7 +251,7 @@ export interface ToolCallRecord {
 
 export interface StreamOptions<TContext = DefaultToolContext> {
 	conversationId?: string;
-	/** Channel ID for Realtime delivery. Defaults to conversationId or a random UUID. */
+	/** Channel ID for Realtime delivery. Defaults to conversationId or a random UUID. Empty strings are treated as unset. */
 	channelId?: string;
 	/** User ID for conversation scoping. Defaults to 'anonymous'. */
 	userId?: string;
@@ -264,14 +264,30 @@ export interface StreamOptions<TContext = DefaultToolContext> {
 	context?: TContext;
 }
 
-/** Returned by stream(). Provides the channelId and server-side convenience methods. */
+/**
+ * Returned by stream(). Provides the channelId and server-side convenience methods.
+ *
+ * Safe to return directly from API methods — `toJSON()` serializes to
+ * `{ channelId, channel: null }`. Only `channelId` is meaningful client-side;
+ * `channel` is explicitly `null` to signal the live handle is server-side only,
+ * and the `complete()` helper is dropped (functions don't serialize).
+ */
 export interface AgentStreamResult {
 	/** Realtime channel ID where chunks are published. */
 	channelId: string;
-	/** Realtime channel handle — subscribe to streaming chunks or return to client as Transferable. */
+	/**
+	 * Realtime channel handle (server-side only). Nulled by `toJSON()` — clients subscribe from `channelId` instead.
+	 *
+	 * @remarks
+	 * Unlike `RealtimeChannel.toJSON()` which produces a hydratable descriptor, this is nulled
+	 * because it's a `Promise` that can't round-trip. Clients reconstruct a subscribe-only
+	 * channel from `channelId` via the `useChat` `subscribe` callback.
+	 */
 	channel: Promise<RealtimeChannel<AgentStreamChunk>>;
 	/** Wait for the complete response (server-side). Resolves when the done chunk arrives. */
 	complete: () => Promise<AgentStreamChunk>;
+	/** Only `{ channelId, channel: null }` is serialized when this object crosses the RPC boundary. */
+	toJSON(): { channelId: string; channel: null };
 }
 
 export interface AgentStreamChunk {

package/src/version.ts

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'Agent';
-export const BB_VERSION = '0.1.2';
+export const BB_VERSION = '0.3.0';