@aws-blocks/bb-agent 0.1.2 → 0.1.3

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,6 +6,8 @@ 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

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.1.3";
 //# 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.1.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-agent",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -8,6 +8,7 @@
     "dist",
     "MODELS.md",
     "README.md",
+    "DESIGN.md",
     "src",
     "LICENSE"
   ],
@@ -33,11 +34,11 @@
     "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/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.1",
     "@aws-sdk/client-bedrock": "^3.700.0",
     "@strands-agents/sdk": "~1.3.0",

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.1.3';