@aws-blocks/bb-agent 0.3.4 → 0.4.0

package/DESIGN.md

@@ -3,47 +3,95 @@
 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
+**Type:** Composite (uses DistributedTable, Realtime, FileBucket internally) + an AgentCore Runtime
+**AWS Services:** Bedrock AgentCore Runtime, Bedrock, DynamoDB, S3, API Gateway (WebSocket)
 **Agent Framework:** [Strands Agents SDK](https://strandsagents.com/)
 
 ## Architecture
 
-The Agent BB is a composite Building Block — it creates and manages 4 internal BBs:
+The streaming agent loop runs on a **Bedrock AgentCore Runtime** (sessions up to 8h, warm,
+managed) — not the shared Blocks request handler — and streams chunks to the browser over the
+**Realtime** BB. The Agent BB composes these internal BBs plus the runtime:
 
-| Internal BB | Purpose | Created when |
+| Internal BB / resource | 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 |
+| **AgentCore Runtime** | Hosts the streaming loop (co-bundled backend + `serve()`) | Always (AWS) |
 
 ```
-stream() → AsyncJob.submit() → returns { channelId } immediately
+stream()/resume() → InvokeAgentRuntime (returns immediately)
                 ↓
-         AsyncJob consumer
+     AgentCore Runtime container (agentcore-entry.ts): starts the turn as a BACKGROUND
+     async task and returns an ack immediately
                 ↓
-         runAgent() → Strands agent loop → publishes chunks to Realtime
+         runAgent() → Strands agent loop → publishes chunks to Realtime (as the shared execution role)
                                          → persists messages to DistributedTable
                                          → SessionManager saves state to FileBucket
 ```
 
+The RPC handler (`stream`/`resume`) only kicks off the turn; it does not hold the connection —
+running the loop as a background task lets `InvokeAgentRuntime` return in seconds. The microVM then
+stays alive on AgentCore's own terms: AgentCore polls the container's health endpoint, and the SDK
+reports `HealthyBusy` while a background task is in flight, so AgentCore keeps the runtime running
+(up to the 8h max session) and returns it to `Healthy` — eligible for reclaim — once the task
+completes. The browser subscribes to the Realtime channel by `channelId` and receives chunks as the
+loop runs, so a turn is bounded by the AgentCore session (8h), not by the request handler's
+per-invocation limit or API Gateway's ~29s cap.
+
+**Compute model.** All AgentCore provisioning is kept self-contained in `AgentCoreRuntime`
+(`agentcore-runtime.cdk.ts`) — the co-bundle, the `Runtime`, the shared role's AgentCore trust +
+grants, the container env, and the handler's invoke permission — so it can later fold into a per-BB
+compute abstraction (should one land) without touching call sites.
+
 ## 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)
 
+## Runaway-protection caps
+
+`AgentConfig.maxLlmCalls` / `maxToolIterations` (default 20, `false` disables) bound runaway cost. They're enforced in `runAgent` by counting Strands' `BeforeModelCallEvent` / `BeforeToolCallEvent` hooks and calling `agent.cancel()` once a cap is exceeded; cancellation ends the stream normally (`stopReason: 'cancelled'`), which `runAgent` surfaces as an `error` chunk and then skips the final persist + `done`.
+
+**Scope is the whole logical turn, including across HITL resumes.** The counters are stored in the Strands agent's `appState` (keys `__bbAgentModelCallCount` / `__bbAgentToolCallCount`), which the `SessionManager` persists with the session snapshot — the same mechanism the `trusted:<tool>` flags use. A turn that pauses on an interrupt and continues via `resume()` therefore keeps counting on its existing budget. Locals in `runAgent` would reset on every resume, letting an auto-approving or trusted-tool resume loop re-enter itself indefinitely — exactly the runaway these caps exist to stop.
+
+**The reset is lazy, and it has to be.** The `SessionManager` restores the snapshot's `appState` *during* `stream()`, i.e. after `runAgent` has already set up its hooks — so zeroing the counters up front is silently overwritten by the previous turn's values and the budget leaks from turn to turn (a second message on the same conversation would start at the first turn's count and trip immediately). Instead, a fresh turn mints a `turnId` and the first cap hook to fire notices the stored `__bbAgentCapTurnId` is stale, zeroes the counters, and claims the turn; a resume mints no id, so it continues on the restored counts. Strands has no per-turn identifier to reuse here — `invocationState` is a caller-supplied bag, and a per-invocation id would change on every `resume()`, which is the opposite of what's needed.
+
+A tool call cancelled by the tool cap still gets an `AfterToolCallEvent` (Strands reports the cancellation as the call's result), so the `tool-call` row already written to the message table keeps its `tool-result` partner — no dangling `tool_use` is left for the next turn to replay. `runAgent` additionally writes an `assistant` row carrying the stop reason in `metadata.error`, so a reloaded conversation explains why it ended.
+
 ## 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`)
+The CDK class provisions:
+- **FileBucket:** `${id}-sn` — session snapshot storage
+- **DistributedTable:** `${id}-convos` / `${id}-messages` — conversation metadata + 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.
+- **AgentCore Runtime** (`${id}-runtime`, via `AgentCoreRuntime`) — the co-bundled backend + `serve()`
+  harness. It runs **as the shared Blocks execution role** (`Scope.executionRole` / `BlocksRole`) —
+  the same role the Lambda handler runs as — so it **inherits every Building Block's grants**, including
+  **Realtime publish** (`execute-api:ManageConnections` + the connections table, granted to the handler
+  by the `${id}-rt` Realtime child), other BBs an agent's *tools* touch (KVStore, tables, etc.), and
+  this agent's own session bucket (S3) and conversation/message tables (DynamoDB). `AgentCoreRuntime`
+  adds to that shared role only what's AgentCore-specific and not already carried:
+  - **Trust:** the `bedrock-agentcore.amazonaws.com` assume-role statement, so the runtime can assume
+    the shared role. Scoped by `aws:SourceAccount` + `aws:SourceArn` (AWS's recommended AgentCore trust
+    policy). Added here — not in core — so a Realtime-only app never trusts AgentCore.
+  - **Bedrock:** `InvokeModel` + `InvokeModelWithResponseStream` on all foundation models and inference profiles
+- **Handler grant:** the shared role is granted `bedrock-agentcore:InvokeAgentRuntime` (wildcard runtime
+  ARN, to avoid a role↔runtime dependency cycle) so the RPC handler can start the loop.
+
+The container gets four environment variables: `BB_AGENT_ID`, `BLOCKS_STACK_NAME`, and the config
+location `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`. `BB_AGENT_ID` + `BLOCKS_STACK_NAME` let the
+co-bundled backend re-derive its resource names in-process (session bucket, conversation/message
+tables) via the SDK-identifier registry — the same derivation the handler uses — so those names aren't
+injected. `BLOCKS_CONFIG_BUCKET`/`BLOCKS_CONFIG_KEY` point the container at the shared config blob
+(from core's `getConfigLocation()`); `loadConfigToProcessEnv()` loads the **same full app config the
+handler does**, which is how the loop gets `BLOCKS_RT_CALLBACK_URL` (registered by the Realtime BB) and
+every other `registerConfig()` value a tool's Building Block may read. IAM to read the blob is inherited
+from the shared execution role.
+
+> **Note:** The runtime (`agent.ts`) and CDK (`index.cdk.ts`) layers both create the internal BBs on the Agent scope (`this`) with the **same child ids** (`sn`, `convos`, `messages`, `rt`). Same id → same `fullId` → same derived physical name, so the deployed loop resolves the exact resources CDK provisioned.
 
 ## Model Providers
 
@@ -61,6 +109,7 @@ Custom Strands model provider for local development. No network, no API keys, no
 
 - 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
+- Triggers tool calls when the prompt mentions a tool name (or a `cannedTriggers` keyword) — splits camelCase names into words (e.g., "weather" matches `getWeather`) and emits Strands `toolUse` events. Matching is on word boundaries, not substrings, so "category" does not fire `getCat`.
+- Derives tool input from, in order of preference: the tool's `cannedExamples`, the schema `default` (from Zod `.default()`), the first `enum` value (for enum fields), then a generic placeholder by type (`'sample'` / `1` / `true` / `[]`)
 - 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

@@ -48,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. 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.
+`stream()` invokes the AgentCore Runtime (`InvokeAgentRuntime`) and returns immediately — no API Gateway timeout risk. The loop runs on the runtime (sessions up to 8h) and publishes chunks to Realtime as it goes. 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:
 
@@ -136,6 +136,8 @@ The `useChat` hook only surfaces `user`, `assistant`, and `approval` messages to
 | `inferenceOnly` | `boolean` | Skip persistence infra. Default: `false`. |
 | `conversation` | `ConversationManagerConfig` | How the agent trims message history (sliding-window or summarizing). |
 | `streamingMode` | `'token' \| 'block'` | How text chunks are published to the client. Default: `'block'`. |
+| `maxLlmCalls` | `number \| false` | Max model invocations per turn before the turn is stopped; `false` disables. Default: `20`. See [Limiting runaway cost](#limiting-runaway-cost). |
+| `maxToolIterations` | `number \| false` | Max tool calls per turn before the turn is stopped; `false` disables. Default: `20`. See [Limiting runaway cost](#limiting-runaway-cost). |
 
 ### Model Configuration
 
@@ -359,6 +361,38 @@ const agent = new Agent(scope, 'support', {
 });
 ```
 
+### Limiting runaway cost
+
+An agent runs a reason→act loop: each iteration is one **model call**, optionally followed by tool calls, and a model call that requests no tools ends the turn. A misbehaving agent — or a prompt that induces one — can loop this cycle far longer than intended; an unbounded loop can run up unexpected cost.
+
+> **These caps are a safety backstop, not a way to guide the agent.** The defaults exist only to stop a runaway from racking up cost — they are *not* tuned for your agent and should not be used to shape its behavior. An agent that legitimately needs more steps or tools will be cut off mid-task at the default. **Set these values deliberately for your own agent** based on how many steps and tool calls a healthy turn takes, so a normal turn always completes and only genuine runaways are stopped.
+
+Two per-turn safety caps bound this, and **both default to `20`**:
+
+- **`maxLlmCalls`** — the maximum number of model invocations in a single turn. This is the most direct spend guard (model calls are the billing unit), and because every tool round needs a model call it transitively bounds tool loops too.
+- **`maxToolIterations`** — the maximum number of tool calls in a single turn (parallel tool batches count each call).
+
+When either cap is hit, the turn is stopped and the client receives an `error` chunk (so `complete()` rejects) instead of `done`. The counts cover the whole turn, including across a [tool-approval interrupt](#tool-approval-human-in-the-loop): they are kept in the agent's session state, so a turn that pauses for approval and continues via `resume()` keeps its existing budget instead of starting a fresh one. Only a new message starts a new budget.
+
+```typescript
+const agent = new Agent(scope, 'support', {
+  systemPrompt: '...',
+  maxLlmCalls: 40,          // agent legitimately reasons over many steps
+  maxToolIterations: 60,    // ...and chains many tools per turn
+});
+
+// Or disable a cap entirely with `false`:
+const unbounded = new Agent(scope, 'batch', {
+  systemPrompt: '...',
+  maxLlmCalls: false,       // no per-turn model-call limit
+  maxToolIterations: false,
+});
+```
+
+Raise the caps for agents that legitimately take many steps so they aren't cut off mid-task, or set a cap to `false` to disable it — tuning these to your agent is part of delivering a good agentic experience, not just a cost lever. The caps bound call *count*, not tokens or wall-clock — for real cost protection, also configure a [billing alarm](https://docs.aws.amazon.com/cost-management/latest/userguide/monitor-charges.html) or a CloudWatch alarm on Bedrock spend.
+
+When sizing the caps for an agent that uses [tool approval](#tool-approval-human-in-the-loop), remember that approved and trusted tool calls both count: a `trustable` tool that's been trusted runs without interrupting, and a tool approved through `resume()` continues on the same budget, so a long approve-and-continue turn can still reach the cap.
+
 ## Tools
 
 Tools let the agent take actions during its reasoning — query a database, call an API, send an email. The model decides *when* to call a tool based on the user's message and the tool's description. You define the tool's schema and handler; the framework handles the rest.
@@ -640,9 +674,41 @@ The CannedProvider is a custom Strands model provider that requires no network o
 
 - Returns simple mock responses
 - Triggers tool calls when the prompt mentions a tool name (e.g., "get order" triggers `getOrderStatus`)
-- Generates valid tool inputs from Zod schemas using type-based placeholders
+- Generates valid tool inputs from Zod schemas, respecting schema `default` values (from `.default()`) before falling back to type-based placeholders (`'sample'`, `1`, `true`, `[]`)
 - Streams responses word by word, matching the same protocol as real providers
 
+#### Canned Hints — `cannedExamples` and `cannedTriggers`
+
+Two optional tool fields make the canned provider more useful for local prototyping. Both are **ignored by the real bedrock/openai providers**, so they're safe to leave on production tools:
+
+| Field | Type | Effect (canned provider only) |
+| --- | --- | --- |
+| `cannedExamples` | `Record<string, JSONValue>` | Realistic tool input, shallow-merged over the generated placeholder — your fields win, unspecified fields fall back to schema defaults / placeholders. The merge is one level deep: a nested-object example replaces that whole generated sub-object rather than deep-merging into it. |
+| `cannedTriggers` | `string[]` | Extra keyword phrases that make the provider select this tool, beyond its name and camelCase words. Single and multi-word phrases match on word boundaries (so `'log in'` won't fire on `"backlog in"`); internal whitespace is flexible. |
+
+Building on the [KnowledgeBase tool](#using-knowledgebase-with-the-agent) above: without hints the mock calls `searchDocs` with `{ query: 'sample' }`, which matches nothing in your documents, so local testing returns empty results. A `cannedExamples` query that actually appears in *your* docs makes the mock return real hits, and `cannedTriggers` lets natural phrasings fire the tool:
+
+```typescript
+tools: (tool) => ({
+  searchDocs: tool({
+    description: 'Search product documentation for relevant information',
+    parameters: z.object({
+      query: z.string().describe('The search query'),
+      maxResults: z.number().optional().describe('Max results to return (default: 5)'),
+    }),
+    handler: async ({ input }) => kb.retrieve(input.query, { maxResults: input.maxResults ?? 5 }),
+
+    // Canned provider hints (ignored by real models):
+    // Without this the mock would search for the literal 'sample' and match nothing —
+    // use a query that hits YOUR documents so local runs return meaningful results.
+    cannedExamples: { query: 'how do I reset my password' },
+    // The name already matches "search"/"docs"/"searchDocs"; these add phrasings that don't
+    // contain the name, so "help me find the manual" or "look up the guide" also fire the tool.
+    cannedTriggers: ['find', 'look up'],
+  }),
+}),
+```
+
 
 ## Client Hook — `useChat`
 
@@ -800,7 +866,8 @@ The Agent BB composes several internal Building Blocks automatically:
 | `FileBucket` | S3 | Session snapshot storage (Strands agent state between turns) |
 | `DistributedTable` × 2 | DynamoDB | Conversations table + messages table |
 | `Realtime` | API Gateway WebSocket | Streaming chunks to connected clients |
-| `AsyncJob` | SQS + Lambda | Runs the agent asynchronously (no API Gateway timeout) |
+
+The streaming loop itself runs on a **Bedrock AgentCore Runtime** (provisioned by `AgentCoreRuntime` — not a composed BB). It's invoked via `InvokeAgentRuntime`, runs the loop for the length of the session (up to 8h), and publishes chunks over the Realtime BB above.
 
 When `inferenceOnly: true`, the two DistributedTables are skipped (no conversation persistence).
 
@@ -809,9 +876,8 @@ When `inferenceOnly: true`, the two DistributedTables are skipped (no conversati
 - **Model:** Bedrock pay-per-token pricing. See [Bedrock pricing](https://aws.amazon.com/bedrock/pricing/).
 - **Persistence:** DynamoDB (DistributedTable) — PAY_PER_REQUEST, single-digit ms latency.
 - **Session storage:** S3 (FileBucket) — ~$0.023 per GB/month.
-- **Async execution:** SQS (AsyncJob) — $0.40 per million messages.
-- **Streaming:** AppSync Events (Realtime) — $1.00 per million connection minutes.
-- **No timeout limit:** Agent runs in AsyncJob consumer Lambda (up to 15 min), not behind API Gateway.
+- **Loop compute:** Bedrock AgentCore Runtime — consumption-based (vCPU + memory while a session is active). See [AgentCore Runtime pricing](https://aws.amazon.com/bedrock/agentcore/pricing/).
+- **Streaming:** API Gateway WebSocket (Realtime) — per-message + per-connection-minute pricing.
 
 ## Troubleshooting
 
@@ -827,4 +893,5 @@ When `inferenceOnly: true`, the two DistributedTables are skipped (no conversati
 - [Bedrock supported models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html)
 - [Cross-region inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html)
 - [Bedrock pricing](https://aws.amazon.com/bedrock/pricing/)
+- [Bedrock AgentCore Runtime pricing](https://aws.amazon.com/bedrock/agentcore/pricing/)
 - [Ollama model library](https://ollama.com/library)

package/dist/agent.aws.d.ts

@@ -2,7 +2,7 @@ import type { ScopeParent } from '@aws-blocks/core';
 import type { FileBucket } from '@aws-blocks/bb-file-bucket';
 import type { SnapshotStorage } from '@strands-agents/sdk';
 import type { S3StorageConfig } from '@strands-agents/sdk/session/s3-storage';
-import { AgentBase } from './agent.js';
+import { AgentBase, type AgentTurnPayload } from './agent.js';
 import type { AgentConfig, DefaultToolContext } from './types.js';
 /**
  * Builds the deployed Agent's snapshot storage, pinning S3Storage to the Lambda
@@ -12,6 +12,20 @@ import type { AgentConfig, DefaultToolContext } from './types.js';
  */
 export declare function createDeployedSnapshotStorage(bucket: FileBucket, S3StorageImpl?: new (config: S3StorageConfig) => SnapshotStorage): SnapshotStorage;
 export declare class Agent<TContext = DefaultToolContext> extends AgentBase<TContext> {
+    private _agentCore?;
     constructor(scope: ScopeParent, id: string, config: AgentConfig<TContext>);
+    /**
+     * Run the turn on the AgentCore Runtime that hosts this agent's loop.
+     *
+     * Returns as soon as the runtime has ACCEPTED the turn: `agentcore-entry` starts `runAgent()`
+     * as a background async task (which streams chunks to Realtime under the runtime's own role)
+     * and responds immediately, so this `InvokeAgentRuntime` call does NOT hold the connection for
+     * the turn's duration — the loop keeps running server-side for up to the 8h session lifetime.
+     * `runtimeSessionId` is keyed by conversationId so a conversation's turns/resumes reuse one
+     * warm microVM.
+     *
+     * @internal Internal compute seam; not customer API.
+     */
+    protected dispatchTurn(payload: AgentTurnPayload<TContext>): Promise<void>;
 }
 //# sourceMappingURL=agent.aws.d.ts.map

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,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGlE;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,GAAE,KAAK,MAAM,EAAE,eAAe,KAAK,eAA2B,GACzE,eAAe,CAEjB;AAED,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":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAalE;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,GAAE,KAAK,MAAM,EAAE,eAAe,KAAK,eAA2B,GACzE,eAAe,CAEjB;AAED,qBAAa,KAAK,CAAC,QAAQ,GAAG,kBAAkB,CAAE,SAAQ,SAAS,CAAC,QAAQ,CAAC;IAC5E,OAAO,CAAC,UAAU,CAAC,CAAyB;gBAEhC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC;IAIzE;;;;;;;;;;;OAWG;cACsB,YAAY,CAAC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CA4BzF"}

package/dist/agent.aws.js

@@ -1,8 +1,21 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { createHash } from 'node:crypto';
+import { getConfig } from '@aws-blocks/core';
+import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } from '@aws-sdk/client-bedrock-agentcore';
 import { S3Storage } from '@strands-agents/sdk/session/s3-storage';
 import { AgentBase } from './agent.js';
+import { AgentErrors, blocksAgentError } from './errors.js';
 import { BedrockModels } from './models.js';
+/**
+ * AgentCore requires a `runtimeSessionId` of at least 33 characters. Conversation/channel ids
+ * are UUIDs (36 chars) in the normal path and pass through unchanged; anything shorter is hashed
+ * to a stable 64-char hex id — stable per input, so a conversation keeps routing to one warm
+ * microVM across turns/resumes.
+ */
+function toRuntimeSessionId(base) {
+    return base.length >= 33 ? base : createHash('sha256').update(base).digest('hex');
+}
 /**
  * Builds the deployed Agent's snapshot storage, pinning S3Storage to the Lambda
  * execution region (`AWS_REGION`) so non-us-east-1 deploys use the correct regional
@@ -13,7 +26,43 @@ export function createDeployedSnapshotStorage(bucket, S3StorageImpl = S3Storage)
     return new S3StorageImpl({ bucket: bucket.fullId, region: process.env.AWS_REGION });
 }
 export class Agent extends AgentBase {
+    _agentCore;
     constructor(scope, id, config) {
         super(scope, id, config, config.model?.deployed ?? BedrockModels.BALANCED, createDeployedSnapshotStorage);
     }
+    /**
+     * Run the turn on the AgentCore Runtime that hosts this agent's loop.
+     *
+     * Returns as soon as the runtime has ACCEPTED the turn: `agentcore-entry` starts `runAgent()`
+     * as a background async task (which streams chunks to Realtime under the runtime's own role)
+     * and responds immediately, so this `InvokeAgentRuntime` call does NOT hold the connection for
+     * the turn's duration — the loop keeps running server-side for up to the 8h session lifetime.
+     * `runtimeSessionId` is keyed by conversationId so a conversation's turns/resumes reuse one
+     * warm microVM.
+     *
+     * @internal Internal compute seam; not customer API.
+     */
+    async dispatchTurn(payload) {
+        const runtimeArnKey = `BB_AGENT_${this.fullId}_RUNTIME_ARN`;
+        const runtimeArn = await getConfig(runtimeArnKey);
+        if (!runtimeArn) {
+            throw blocksAgentError(AgentErrors.StreamFailed, `AgentCore Runtime ARN not found (config key ${runtimeArnKey}). Ensure the app build produced the AgentCore asset and the stack deployed the Runtime.`);
+        }
+        this._agentCore ??= new BedrockAgentCoreClient({});
+        const body = {
+            prompt: payload.message,
+            channelId: payload.channelId,
+            conversationId: payload.conversationId,
+            userId: payload.userId,
+            interruptResponses: payload.interruptResponses,
+            context: payload.context,
+        };
+        await this._agentCore.send(new InvokeAgentRuntimeCommand({
+            agentRuntimeArn: runtimeArn,
+            runtimeSessionId: toRuntimeSessionId(payload.conversationId ?? payload.channelId),
+            contentType: 'application/json',
+            accept: 'application/json',
+            payload: new TextEncoder().encode(JSON.stringify(body)),
+        }));
+    }
 }

package/dist/agent.d.ts

@@ -4,15 +4,46 @@ import { FileBucket } from '@aws-blocks/bb-file-bucket';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
 import type { SnapshotStorage } from '@strands-agents/sdk';
 import type { AgentConfig, AgentStreamResult, StreamOptions, Message, Conversation, ModelConfig, InterruptResponse, DefaultToolContext } from './types.js';
+/**
+ * A single agent turn to dispatch (initial message or HITL resume). Passed to
+ * {@link AgentBase.dispatchTurn} — run in-process locally, or shipped to the AgentCore Runtime
+ * on AWS as the `InvokeAgentRuntime` payload.
+ *
+ * @internal Internal turn-dispatch seam — not part of the public API. Customers use
+ * `stream()` / `resume()`; this is the shape those hand to the compute layer.
+ */
+export interface AgentTurnPayload<TContext = DefaultToolContext> {
+    /** User prompt. Empty on resume (interruptResponses drive the turn instead). */
+    message: string;
+    /** Conversation to persist to / restore the session from (undefined for inferenceOnly). */
+    conversationId?: string;
+    /** Realtime channel the client subscribes to for this turn's chunks. */
+    channelId: string;
+    /** Conversation owner. */
+    userId: string;
+    /** HITL resume: approval responses to apply instead of a new prompt. */
+    interruptResponses?: Array<{
+        interruptId: string;
+        response: string;
+    }>;
+    /** Per-call tool context, forwarded to tool invocations. JSON-serializable. */
+    context?: TContext;
+}
+/** @internal Register a live Agent instance so the AgentCore entrypoint can find it by fullId. */
+export declare function registerAgentInstance(fullId: string, agent: AgentBase<any>): void;
+/** @internal Look up a registered Agent instance by fullId (used by the AgentCore entrypoint). */
+export declare function getAgentInstance(fullId: string): AgentBase<any> | undefined;
 /**
  * Base class for the Agent BB. Extended by agent.mock.ts (model.local) and agent.aws.ts (model.deployed).
  *
- * Creates up to 4 internal BBs depending on mode:
+ * Creates internal BBs depending on mode:
  * - FileBucket: session snapshot storage for Strands SessionManager (always)
  * - DistributedTable: frontend message history (when inferenceOnly = false)
- * - Realtime: streaming chunks to browser + AsyncJob result delivery (always)
- * - AsyncJob: runs Strands agent asynchronously (always)
- * - TODO logging
+ * - Realtime: streaming chunks to browser (always)
+ *
+ * The agent loop runs via {@link dispatchTurn}: in-process locally (mock), and on the
+ * AgentCore Runtime on AWS (the deployed subclass overrides dispatchTurn to invoke it). The
+ * AgentCore Runtime itself is provisioned by the CDK layer (index.cdk.ts → AgentCoreRuntime).
  */
 export declare class AgentBase<TContext = DefaultToolContext> extends Scope {
     /** Developer-facing agent configuration. */
@@ -25,8 +56,6 @@ export declare class AgentBase<TContext = DefaultToolContext> extends Scope {
     private messages?;
     /** Realtime pub/sub — streams chunks to browser. */
     private rt;
-    /** Internal async job — runs the Strands agent in a separate execution context. */
-    private job;
     /** Which model provider to use. */
     private modelConfig;
     /** Where to persist Strands agent state (snapshots). */
@@ -43,31 +72,70 @@ export declare class AgentBase<TContext = DefaultToolContext> extends Scope {
      * @param createSnapshotStorage - factory that receives the internal FileBucket and returns the appropriate SnapshotStorage
      */
     constructor(scope: ScopeParent, id: string, config: AgentConfig<TContext>, modelConfig: ModelConfig | ModelConfig[] | undefined, createSnapshotStorage: (bucket: FileBucket) => SnapshotStorage);
+    /**
+     * Run one agent turn (initial message or HITL resume) and publish its chunks to Realtime.
+     *
+     * This is the single execution entry the compute layer invokes: the AgentCore Runtime
+     * entrypoint (agentcore-entry.ts) calls it as a background async task on AWS, and locally
+     * {@link dispatchTurn} calls it in-process. Errors are caught and published as an `error`
+     * chunk (not re-thrown) so the client never hangs and a non-idempotent turn isn't retried.
+     *
+     * @param payload - the turn to run (see {@link AgentTurnPayload}).
+     * @internal Invoked by the compute layer (agentcore-entry / dispatchTurn), not customer API.
+     */
+    invokeTurn(payload: AgentTurnPayload<TContext>): Promise<void>;
+    /**
+     * Dispatch a turn to wherever the agent loop runs, returning promptly so `stream()`/`resume()`
+     * hand the client a `channelId` without waiting for the turn to finish.
+     *
+     * Base (local/mock): run the loop IN-PROCESS, fire-and-forget — chunks flow to the mock
+     * Realtime as the turn progresses. The deployed (AWS) subclass overrides this to invoke the
+     * AgentCore Runtime, which runs the loop as a background task and publishes to Realtime.
+     *
+     * @internal Internal compute seam (overridden by the AWS subclass); not customer API.
+     */
+    protected dispatchTurn(payload: AgentTurnPayload<TContext>): Promise<void>;
     /**
      * Executes the Strands agent, publishes chunks to Realtime, persists messages to DynamoDB.
      *
-     * Called by: AsyncJob consumer.
-     * NOT called directly — stream() submits to AsyncJob, which invokes this.
+     * Called by {@link invokeTurn} (wherever the loop runs — locally in-process, or inside the
+     * AgentCore Runtime container on AWS). Publishes each event to the Realtime `chunks` channel.
+     *
+     * Flow: invokeTurn() → runAgent() → Strands agent.stream() → publishes chunks to Realtime BB
      *
-     * Flow: AsyncJob handler → runAgent() → Strands agent.stream() → publishes chunks to Realtime BB
-     * TODO add comments for args
+     * @param message - the user message that starts the turn (ignored on the resume path)
+     * @param conversationId - conversation to load/persist history for; undefined means no persistence
+     * @param channelId - Realtime channel the stream chunks are published to
+     * @param userId - owner of the conversation, stored on every persisted message
+     * @param interruptResponses - approval responses when resuming a turn paused on a HITL interrupt
+     * @param context - per-call tool context, threaded to tool handlers via Strands invocationState
      */
     private runAgent;
     private createStrandsAgent;
     /**
      * Submit a message to the agent. Returns immediately with a channelId.
      *
-     * Flow: stream() → AsyncJob.submit() → returns { channelId }
-     * The AsyncJob consumer calls runAgent() separately.
-     * Chunks are published to Realtime on the returned channelId.
+     * Flow: stream() → dispatchTurn() → returns { channelId }
+     * dispatchTurn runs the loop where the compute lives (in-process locally; on the AgentCore
+     * Runtime on AWS) and publishes chunks to Realtime on the returned channelId.
      *
      * Subscribe to chunks via result.channel, or await result.complete() for the final response.
+     *
+     * Errors surface on two paths. Once the turn is dispatched, loop failures arrive as an `error`
+     * chunk on the channel (and reject `complete()`). A failure to *dispatch* the turn — e.g. on AWS
+     * when the AgentCore Runtime can't be invoked (unresolved runtime ARN, or an `InvokeAgentRuntime`
+     * error) — rejects this `stream()` call itself rather than reaching the channel. Always `await`
+     * `stream()` so a dispatch failure isn't lost.
      */
     stream(message: string, options?: StreamOptions<TContext>): Promise<AgentStreamResult>;
     /**
      * Resume an interrupted agent with user's responses.
-     * Submits a new AsyncJob that loads the session and continues from the interrupt point.
+     * Dispatches a new turn that loads the session and continues from the interrupt point.
      * Chunks are published to the same channelId — use the existing subscription or call complete() again to wait for the result.
+     *
+     * Like `stream()`, errors surface on two paths: loop failures arrive as an `error` chunk on the
+     * channel once the turn is dispatched, while a failure to *dispatch* (e.g. on AWS when the AgentCore
+     * Runtime can't be invoked) rejects this `resume()` call itself. Always `await` it.
      */
     resume(channelId: string, responses: Array<InterruptResponse>, options?: {
         conversationId?: string;

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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"}