@aws-blocks/bb-agent 0.3.4 → 0.4.0

package/dist/agentcore-entry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Serve a registered Agent on the AgentCore harness.
+ *
+ * The developer's backend must already have been imported in THIS process (so the Agent
+ * registered itself in the shared registry) — either by `main()` below (standalone launch
+ * via `BB_AGENT_BACKEND_MODULE`) or by the co-bundle (agentcore-bundle.ts) that imports the
+ * backend and this `serve` from the same bb-agent module instance. Co-bundling is required
+ * because the registry is a module singleton — a split would put the Agent in one map and
+ * the lookup in another.
+ *
+ * @param agentId - fullId of the target Agent (defaults to process.env.BB_AGENT_ID)
+ */
+export declare function serve(agentId?: string | undefined): void;
+/**
+ * Standalone launch: load config, import the developer backend by path, then serve.
+ * Used when the artifact runs this file directly with BB_AGENT_BACKEND_MODULE pointing at the
+ * backend. When an app co-bundles the backend with `serve` (agentcore-bundle.ts), it calls
+ * `serve()` directly instead and this `main()` is not the entry.
+ */
+export declare function main(): Promise<void>;
+//# sourceMappingURL=agentcore-entry.d.ts.map

package/dist/agentcore-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore-entry.d.ts","sourceRoot":"","sources":["../src/agentcore-entry.ts"],"names":[],"mappings":"AAkDA;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,qBAA0B,GAAG,IAAI,CAyC7D;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAc1C"}

package/dist/agentcore-entry.js

@@ -0,0 +1,120 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * AgentCore Runtime entrypoint for the Agent BB.
+ *
+ * Hosts the developer's real Agent — the same instance the Lambda handler would build — on
+ * the `BedrockAgentCoreApp` harness (implements the `/invocations` + `/ping` contract on port
+ * 8080), and runs the agent loop as a **background async task** that streams chunks to the
+ * browser over the Realtime BB (exactly as the loop does on Lambda today).
+ *
+ * Why background + Realtime (not the harness's SSE response): the browser never holds a
+ * connection to AgentCore — it subscribes to a Realtime channel by `channelId`. So the
+ * invocation must return immediately while the loop keeps running server-side. The harness
+ * keeps the microVM alive (up to the 8h session lifetime) while an async task is in flight —
+ * `/ping` reports `HealthyBusy` — via `addAsyncTask()`/`completeAsyncTask()`. `runAgent()`
+ * publishes every chunk to Realtime under the runtime's execution role.
+ *
+ * How the developer's agent definition reaches this process:
+ *   The `tools` callback in AgentConfig is a JS closure and can't be serialized across a
+ *   process boundary. So instead of shipping data, we ship code: this entrypoint imports
+ *   the SAME developer backend module the Lambda handler imports (co-bundled with
+ *   `--conditions=aws-runtime`, so `new Agent()` resolves to the AWS runtime class). That
+ *   construction registers the live Agent in the instance registry (see agent.ts); we look
+ *   it up by the `BB_AGENT_ID` the CDK Runtime construct set, and drive its loop.
+ *
+ * Launched by the CodeZip artifact as: ['main.js'] (the co-bundle from agentcore-bundle.ts).
+ */
+import { loadConfigToProcessEnv } from '@aws-blocks/core';
+import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
+import { z } from 'zod';
+import { getAgentInstance } from './agent.js';
+/** Request contract — mirrors the Lambda jobPayloadSchema, minus transport-only fields. */
+const requestSchema = z.object({
+    /** User prompt. Empty on resume (interruptResponses drive the turn instead). */
+    prompt: z.string().default(''),
+    /** Realtime channel the client subscribes to for this turn's chunks. */
+    channelId: z.string(),
+    /** Conversation to persist to / restore the session from. Falls back to the AgentCore session id. */
+    conversationId: z.string().optional(),
+    /** Owner of the conversation. Required when persistence is enabled (not inferenceOnly). */
+    userId: z.string().optional(),
+    /** HITL resume: approval responses to apply instead of a new prompt. */
+    interruptResponses: z.array(z.object({ interruptId: z.string(), response: z.string() })).optional(),
+    /** Per-call tool context, threaded through to tool handlers. Must be JSON-serializable. */
+    context: z.unknown().optional(),
+});
+/**
+ * Serve a registered Agent on the AgentCore harness.
+ *
+ * The developer's backend must already have been imported in THIS process (so the Agent
+ * registered itself in the shared registry) — either by `main()` below (standalone launch
+ * via `BB_AGENT_BACKEND_MODULE`) or by the co-bundle (agentcore-bundle.ts) that imports the
+ * backend and this `serve` from the same bb-agent module instance. Co-bundling is required
+ * because the registry is a module singleton — a split would put the Agent in one map and
+ * the lookup in another.
+ *
+ * @param agentId - fullId of the target Agent (defaults to process.env.BB_AGENT_ID)
+ */
+export function serve(agentId = process.env.BB_AGENT_ID) {
+    if (!agentId)
+        throw new Error('BB_AGENT_ID is required (fullId of the target Agent).');
+    const agent = getAgentInstance(agentId);
+    if (!agent) {
+        throw new Error(`No Agent registered with id '${agentId}'. Ensure the backend module constructs it at import time.`);
+    }
+    const app = new BedrockAgentCoreApp({
+        invocationHandler: {
+            requestSchema,
+            process: (request, context) => {
+                // AgentCore routes every invocation for a session to the same warm microVM.
+                // runtimeSessionId maps to the Agent BB's conversationId (session state key).
+                const conversationId = request.conversationId ?? context.sessionId;
+                // Run the turn as a background async task so this invocation returns immediately.
+                // The harness reports `/ping` = HealthyBusy while the task is in flight, keeping
+                // the microVM alive (up to the 8h session lifetime) until the loop completes.
+                // Chunks are delivered out-of-band via Realtime — this HTTP response is just an ack.
+                const taskId = app.addAsyncTask('agent-turn');
+                void agent
+                    .invokeTurn({
+                    message: request.prompt,
+                    conversationId,
+                    channelId: request.channelId,
+                    userId: request.userId ?? 'anonymous',
+                    interruptResponses: request.interruptResponses,
+                    context: request.context,
+                })
+                    .finally(() => app.completeAsyncTask(taskId));
+                // The client already has channelId (from the RPC that invoked us) and subscribes
+                // to Realtime; it does not consume this response body.
+                return { channelId: request.channelId, status: 'accepted' };
+            },
+        },
+    });
+    app.run();
+}
+/**
+ * Standalone launch: load config, import the developer backend by path, then serve.
+ * Used when the artifact runs this file directly with BB_AGENT_BACKEND_MODULE pointing at the
+ * backend. When an app co-bundles the backend with `serve` (agentcore-bundle.ts), it calls
+ * `serve()` directly instead and this `main()` is not the entry.
+ */
+export async function main() {
+    // Same cold-start contract as the Lambda handler: pull BB resource identifiers
+    // (table names, bucket names, Realtime callback URL) into process.env before importing
+    // the backend, so BB constructors can resolve them.
+    await loadConfigToProcessEnv();
+    const backendModule = process.env.BB_AGENT_BACKEND_MODULE;
+    if (!backendModule)
+        throw new Error('BB_AGENT_BACKEND_MODULE env var is required (path to the developer backend module).');
+    // Import the developer backend — constructing the real Agent, which registers itself.
+    await import(backendModule);
+    serve();
+}
+// Auto-run the standalone launch path ONLY when a backend module path is provided.
+// The co-bundle path (agentcore-bundle.ts) imports `serve` and invokes it directly after
+// importing the backend inline, and does NOT set BB_AGENT_BACKEND_MODULE — so `main()` must
+// not fire there (it would double-serve and throw on the missing env var).
+if (process.env.BB_AGENT_BACKEND_MODULE) {
+    void main();
+}

package/dist/agentcore-runtime.cdk.d.ts

@@ -0,0 +1,27 @@
+import { Runtime } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+/** References the agent loop needs, handed in by the Agent CDK constructor. */
+export interface AgentCoreRuntimeProps {
+    /** fullId of the owning Agent — the container looks the Agent up by this (`BB_AGENT_ID`). */
+    agentFullId: string;
+    /**
+     * Pre-built asset dir to use instead of co-bundling at synth. Set by unit tests and apps
+     * that pre-bundle; when omitted, the backend module is co-bundled from the BlocksStack.
+     */
+    agentcoreAssetPath?: string;
+}
+export declare class AgentCoreRuntime extends Scope {
+    /** The provisioned runtime, or undefined when no backend asset could be resolved (isolated tests). */
+    readonly runtime?: Runtime;
+    /** The runtime ARN (empty string when not provisioned). */
+    readonly runtimeArn: string;
+    constructor(scope: ScopeParent, id: string, props: AgentCoreRuntimeProps);
+    /**
+     * Co-bundle the app backend + `serve()` into an AgentCore code-asset dir. Returns undefined
+     * when the backend module path can't be discovered (isolated unit tests) — the caller then
+     * skips provisioning rather than failing synth.
+     */
+    private buildAsset;
+}
+//# sourceMappingURL=agentcore-runtime.cdk.d.ts.map

package/dist/agentcore-runtime.cdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore-runtime.cdk.d.ts","sourceRoot":"","sources":["../src/agentcore-runtime.cdk.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAqE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAE9H,OAAO,EAAqC,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACrC,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB;IAuIxE;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAWlB"}

package/dist/agentcore-runtime.cdk.js

@@ -0,0 +1,168 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Self-contained CDK provisioning for the Agent BB's AgentCore Runtime.
+ *
+ * This class owns EVERYTHING AgentCore-specific: the synth-time co-bundle of the app backend,
+ * the `Runtime` construct (via `fromCodeAsset` — Node 22 CodeZip, no Docker), the shared role's
+ * AgentCore trust + grants, the container env injection, and the grant that lets the app's RPC
+ * handler invoke the runtime. It is deliberately kept in one place, with no AgentCore details
+ * leaking into the `Agent` CDK constructor or into core, so it can later fold into a per-BB
+ * compute abstraction (should one land) without touching call sites — the Agent just constructs
+ * it and hands over references to the BBs the loop uses.
+ *
+ * The loop runs INSIDE this runtime AS the shared Blocks execution role (the same role the Lambda
+ * handler runs as), so it inherits every Building Block's grants — including the Realtime publish
+ * permissions already granted to the handler, so it streams chunks to the browser via the Realtime
+ * BB with no extra grant. The container loads the full app config (via the injected config-bucket
+ * location) exactly as the handler does, so it discovers the Realtime callback URL and every other
+ * registerConfig() value a tool's BB may need. This class adds to that shared role only what's
+ * AgentCore-specific: the `bedrock-agentcore` assume-role trust, Bedrock model access, and the
+ * handler's `InvokeAgentRuntime` permission. Inbound auth is IAM (SigV4): the RPC handler
+ * invokes with its own credentials; the browser never talks to the runtime directly.
+ */
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import * as cdk from 'aws-cdk-lib';
+import { AgentCoreRuntime as AgentCoreRuntimeVersion, AgentRuntimeArtifact, Runtime } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { Effect, PolicyStatement, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
+import { getConfigLocation, registerConfig, Scope } from '@aws-blocks/core/cdk';
+import { bundleAgentCoreAsset } from './agentcore-bundle.js';
+export class AgentCoreRuntime extends Scope {
+    /** The provisioned runtime, or undefined when no backend asset could be resolved (isolated tests). */
+    runtime;
+    /** The runtime ARN (empty string when not provisioned). */
+    runtimeArn;
+    constructor(scope, id, props) {
+        super(id, { parent: scope });
+        const assetPath = props.agentcoreAssetPath ?? this.buildAsset();
+        if (!assetPath) {
+            // No backend module discoverable (e.g. an isolated unit test that constructs the
+            // Agent without a BlocksStack) — skip provisioning rather than failing synth.
+            this.runtimeArn = '';
+            return;
+        }
+        const stack = cdk.Stack.of(this);
+        // Run the loop AS the shared Blocks execution role (`role: this.executionRole`) — the same
+        // role the Lambda handler runs as. Because every Building Block grants its runtime permissions
+        // to this role (a tool that uses KVStore/tables/etc. grants there too), the AgentCore
+        // container inherits them all automatically — no bespoke, under-granted role, and no need to
+        // mirror each BB's grants. One shared role that any compute can assume keeps this a drop-in
+        // for a future per-BB compute abstraction.
+        const role = this.executionRole;
+        // Add the agent's shared-role trust + grants ONCE per stack. Every agent instance would
+        // otherwise add the SAME trust / Bedrock / InvokeAgentRuntime statements to the ONE shared
+        // role; with several agents in an app that piles up duplicates and overflows the IAM inline-
+        // policy size limit (CDK then spills into `OverflowPolicy` managed policies and the role
+        // misbehaves). These are identical for every agent — Bedrock models and the runtime-ARN
+        // wildcard are stack-scoped — so doing it once covers every agent's container. (Realtime
+        // publish, the session bucket, and the conversation/message tables are already granted to the
+        // shared role by the Realtime BB's handler wiring and the Agent's FileBucket/DistributedTable
+        // children, so they're not repeated here — the loop inherits them by running as the role.)
+        const SHARED_GRANTS_KEY = Symbol.for('BLOCKS_AGENT_RUNTIME_SHARED_ROLE_GRANTS');
+        const stackAny = stack;
+        if (!stackAny[SHARED_GRANTS_KEY]) {
+            // The container publishes to Realtime AS this shared role, which already holds the publish
+            // grants (the Realtime BB grants postToConnection + the connections table to the handler on
+            // the same role) — so no Realtime IAM grant is needed here; it's inherited by running as the role.
+            // Trust: let the AgentCore Runtime assume this shared role (it runs AS the role). Added here
+            // rather than in core, so the role only trusts `bedrock-agentcore` when an Agent exists.
+            // Scope it to this account/region with aws:SourceAccount + aws:SourceArn — AWS's recommended
+            // AgentCore Runtime trust policy — so only AgentCore runtimes in THIS account can assume the
+            // role (tightens the confused-deputy surface) without breaking assumption. `assumeRolePolicy`
+            // exists only on the concrete `Role`; core always creates BlocksRole concretely, so narrow
+            // and fail loud if that ever changes.
+            if (!(role instanceof Role)) {
+                throw new Error('AgentCore Runtime requires the shared Blocks execution role to be a concrete iam.Role to add its assume-role trust');
+            }
+            role.assumeRolePolicy?.addStatements(new PolicyStatement({
+                effect: Effect.ALLOW,
+                principals: [new ServicePrincipal('bedrock-agentcore.amazonaws.com')],
+                actions: ['sts:AssumeRole'],
+                conditions: {
+                    StringEquals: { 'aws:SourceAccount': stack.account },
+                    ArnLike: { 'aws:SourceArn': `arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:*` },
+                },
+            }));
+            // Bedrock model access for the loop (no Building Block grants this, and the loop no longer
+            // runs on the handler).
+            role.addToPrincipalPolicy(new PolicyStatement({
+                actions: [
+                    'bedrock:InvokeModel',
+                    'bedrock:InvokeModelWithResponseStream',
+                    'bedrock:GetFoundationModel',
+                    'bedrock:ListFoundationModels',
+                    'bedrock:GetInferenceProfile',
+                ],
+                resources: [`arn:${stack.partition}:bedrock:*::foundation-model/*`, `arn:${stack.partition}:bedrock:*:*:inference-profile/*`],
+            }));
+            // Let the app's RPC handler (also the shared role) invoke the runtimes — stream()/resume()
+            // call InvokeAgentRuntime. Scope to a wildcard runtime ARN rather than a specific runtime's
+            // ARN: the runtime uses this same shared role as its executionRole, so referencing its ARN
+            // here would create a Role→Runtime→Role dependency cycle. (Same wildcard style as Bedrock.)
+            role.addToPrincipalPolicy(new PolicyStatement({
+                actions: ['bedrock-agentcore:InvokeAgentRuntime'],
+                resources: [
+                    `arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:runtime/*`,
+                    `arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:runtime/*/*`,
+                ],
+            }));
+            stackAny[SHARED_GRANTS_KEY] = true;
+        }
+        // Inject the config location so the container loads the FULL app config via
+        // loadConfigToProcessEnv() — the same config the Lambda handler loads. That's how it gets
+        // BLOCKS_RT_CALLBACK_URL (registered by the Realtime BB) plus any other config-backed BB value
+        // an agent's tools touch; without it the container runs with empty config and those BBs fail.
+        // Idempotent (one config bucket per stack); IAM to read it is inherited via the shared role.
+        const { bucketName: configBucketName, key: configKey } = getConfigLocation(this);
+        const runtime = new Runtime(this, 'AgentRuntime', {
+            agentRuntimeArtifact: AgentRuntimeArtifact.fromCodeAsset({
+                path: assetPath,
+                runtime: AgentCoreRuntimeVersion.NODE_22,
+                // Launch command, NOT a Lambda file.export handler. Single element = the .js file;
+                // the NODE_22 runtime invokes `node` itself. (A leading 'node' element is rejected.)
+                entrypoint: ['main.js'],
+            }),
+            executionRole: role,
+            // Inbound auth defaults to IAM (SigV4): the RPC handler invokes with its own creds.
+            // The browser never invokes the runtime directly (it subscribes to Realtime).
+            environmentVariables: {
+                // The Agent's fullId so the container's getAgentInstance(BB_AGENT_ID) matches the
+                // Agent the co-bundled backend registers at import.
+                BB_AGENT_ID: props.agentFullId,
+                // The namespace the container rebuilds fullId (and every derived resource name) from.
+                // MUST be the owning stack/backend's canonical root id — the SAME value the Lambda
+                // handler and the Lambda compute use (`backendStackName`) — not the raw CFN stack name.
+                // They coincide for a top-level BlocksStack, but for a BlocksBackend embedded in a
+                // customer stack the handler uses the backend fullId while cdk.Stack.of(this).stackName
+                // is the customer stack name; using the latter would make the container derive names from
+                // the wrong namespace and miss its own tables/bucket/config.
+                BLOCKS_STACK_NAME: this.backendStackName,
+                // Config location so the container's loadConfigToProcessEnv() loads the full app config
+                // (same as the handler) — this delivers BLOCKS_RT_CALLBACK_URL and every other
+                // registerConfig() value a tool's BB may read. IAM to read it is inherited (shared role).
+                BLOCKS_CONFIG_BUCKET: configBucketName,
+                BLOCKS_CONFIG_KEY: configKey,
+            },
+        });
+        this.runtime = runtime;
+        this.runtimeArn = runtime.agentRuntimeArn;
+        // Expose THIS agent's runtime ARN to the Lambda runtime path so stream() can resolve it at
+        // call time. Per-agent (each agent has its own runtime), so it stays outside the shared guard.
+        registerConfig(this, `BB_AGENT_${props.agentFullId}_RUNTIME_ARN`, runtime.agentRuntimeArn);
+    }
+    /**
+     * Co-bundle the app backend + `serve()` into an AgentCore code-asset dir. Returns undefined
+     * when the backend module path can't be discovered (isolated unit tests) — the caller then
+     * skips provisioning rather than failing synth.
+     */
+    buildAsset() {
+        const stack = globalThis.CURRENT_BLOCKS_STACK;
+        const backendModulePath = stack?.backendModulePath;
+        if (!backendModulePath)
+            return undefined;
+        const outDir = join(cdk.App.of(this)?.outdir ?? cdk.Stack.of(this).node.tryGetContext('cdk.out') ?? '.cdk-agentcore', `agentcore-${this.fullId}`);
+        mkdirSync(outDir, { recursive: true });
+        return bundleAgentCoreAsset(backendModulePath, outDir);
+    }
+}

package/dist/index.aws.d.ts

@@ -1,4 +1,5 @@
 export { Agent } from './agent.aws.js';
+export type { AgentTurnPayload } from './agent.js';
 export { AgentErrors, InterruptError } from './errors.js';
 export { BedrockModels, OllamaModels } from './models.js';
 export type { AgentConfig, AgentResult, AgentStreamChunk, AgentStreamResult, ToolDefinition, AgentTool, ToolFactory, ToolsConfig, ToolHandlerArgs, DefaultToolContext, InterruptResponse, ToolCallRecord, ModelConfig, StreamOptions, Message, Conversation, JSONValue, TokenUsage } from './types.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.cdk.d.ts

@@ -1,15 +1,21 @@
 import { Scope } from '@aws-blocks/core/cdk';
 import type { ScopeParent } from '@aws-blocks/core';
+import type { AgentConfig } from './types.js';
 export { AgentErrors } from './errors.js';
 export { BedrockModels, OllamaModels } from './models.js';
 export declare class Agent extends Scope {
     /**
      * CDK layer for the Agent BB.
-     * Mirrors the runtime's BB creation so CDK discovers and provisions all resources.
      *
-     * TODO: scope Bedrock IAM grant to specific modelId from config
-     * TODO: guardrails CDK provisioning
+     * Provisions the session FileBucket, the conversation + message DistributedTables, the
+     * Realtime BB used to stream chunks to the browser, and the AgentCore Runtime that hosts
+     * the streaming agent loop. All AgentCore-specific provisioning (co-bundle, runtime role
+     * and its grants, container env, and the handler's invoke permission) lives in the
+     * self-contained {@link AgentCoreRuntime} so it can later fold into a per-BB compute abstraction.
+     *
+     * The loop runs inside the AgentCore Runtime (not the shared handler Lambda), so the shared
+     * handler no longer needs Bedrock access — the runtime's own role gets it (see AgentCoreRuntime).
      */
-    constructor(scope: ScopeParent, id: string, config?: any);
+    constructor(scope: ScopeParent, id: string, config?: AgentConfig);
 }
 //# sourceMappingURL=index.cdk.d.ts.map

package/dist/index.cdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO1D,qBAAa,KAAM,SAAQ,KAAK;IAC/B;;;;;;OAMG;gBACS,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG;CAwCxD"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1D,qBAAa,KAAM,SAAQ,KAAK;IAC/B;;;;;;;;;;;OAWG;gBACS,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW;CAyChE"}

package/dist/index.cdk.js

@@ -1,42 +1,37 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
 import { Scope } from '@aws-blocks/core/cdk';
 import { DistributedTable } from '@aws-blocks/bb-distributed-table';
 import { Realtime } from '@aws-blocks/bb-realtime';
-import { AsyncJob } from '@aws-blocks/bb-async-job';
 import { FileBucket } from '@aws-blocks/bb-file-bucket';
+import { AgentCoreRuntime } from './agentcore-runtime.cdk.js';
 import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
-import { z } from 'zod';
 export { AgentErrors } from './errors.js';
 export { BedrockModels, OllamaModels } from './models.js';
-const jobPayloadSchema = z.object({
-    message: z.string(),
-    conversationId: z.string().optional(),
-});
 export class Agent extends Scope {
     /**
      * CDK layer for the Agent BB.
-     * Mirrors the runtime's BB creation so CDK discovers and provisions all resources.
      *
-     * TODO: scope Bedrock IAM grant to specific modelId from config
-     * TODO: guardrails CDK provisioning
+     * Provisions the session FileBucket, the conversation + message DistributedTables, the
+     * Realtime BB used to stream chunks to the browser, and the AgentCore Runtime that hosts
+     * the streaming agent loop. All AgentCore-specific provisioning (co-bundle, runtime role
+     * and its grants, container env, and the handler's invoke permission) lives in the
+     * self-contained {@link AgentCoreRuntime} so it can later fold into a per-BB compute abstraction.
+     *
+     * The loop runs inside the AgentCore Runtime (not the shared handler Lambda), so the shared
+     * handler no longer needs Bedrock access — the runtime's own role gets it (see AgentCoreRuntime).
      */
     constructor(scope, id, config) {
         super(id, { parent: scope });
-        this.handler.addToRolePolicy(new PolicyStatement({
-            actions: ['bedrock:InvokeModel', 'bedrock:InvokeModelWithResponseStream', 'bedrock:GetFoundationModel', 'bedrock:ListFoundationModels', 'bedrock:GetInferenceProfile'],
-            resources: [
-                'arn:aws:bedrock:*::foundation-model/*',
-                'arn:aws:bedrock:*:*:inference-profile/*',
-            ],
-        }));
-        // Propagate `removalPolicy` to the sessions bucket so customers can
-        // opt sandbox stacks into clean teardown. Without it, CDK's RETAIN
-        // default applies (production-safe) and `cdk destroy` will fail on
-        // a non-empty bucket — same pattern as FileBucket / KnowledgeBase.
-        // ID shortened to keep S3 bucket names within the 63-char limit
+        // Session-snapshot bucket. Provisioned here (and granted to the shared execution role that the
+        // AgentCore Runtime runs as); the deployed loop re-derives its name from this bucket's `fullId`
+        // in-process — the same `'sn'` id → same fullId → same physical bucket — so no name needs to be
+        // injected into the container. Propagate `removalPolicy` so customers can opt sandbox stacks into
+        // clean teardown (without it, CDK's RETAIN default applies). ID shortened to keep the S3 bucket
+        // name within the 63-char limit.
         new FileBucket(this, 'sn', { removalPolicy: config?.removalPolicy });
+        // Conversation metadata + message history. These grant read/write to the shared execution
+        // role, which the AgentCore Runtime then runs as — so the loop can persist history.
         if (!config?.inferenceOnly) {
             new DistributedTable(this, 'convos', {
                 schema: conversationSchema,
@@ -49,12 +44,18 @@ export class Agent extends Scope {
         }
         new Realtime(this, 'rt', {
             namespaces: {
-                chunks: { schema: agentStreamChunkSchema },
+                chunks: Realtime.namespace(agentStreamChunkSchema),
             },
         });
-        new AsyncJob(this, 'job', {
-            schema: jobPayloadSchema,
-            handler: async () => { },
+        // The agent loop runs on the AgentCore Runtime (as the shared Blocks execution role) and
+        // streams to the browser over Realtime. AgentCoreRuntime co-bundles the app backend,
+        // provisions the runtime, adds the bedrock-agentcore trust + Bedrock to the shared role, and
+        // injects the config location so the container loads the same app config as the handler
+        // (the session bucket/tables and Realtime publish are already granted to that role). Kept
+        // self-contained so it can later fold into a per-BB compute abstraction.
+        new AgentCoreRuntime(this, 'runtime', {
+            agentFullId: this.fullId,
+            agentcoreAssetPath: config?.agentcoreAssetPath,
         });
     }
 }

package/dist/index.cdk.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.cdk.test.d.ts.map

package/dist/index.cdk.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.test.d.ts","sourceRoot":"","sources":["../src/index.cdk.test.ts"],"names":[],"mappings":""}

package/dist/index.cdk.test.js

@@ -0,0 +1,143 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CDK-side tests for the Agent BB.
+ *
+ * Pin that the Agent provisions an AgentCore Runtime for the streaming loop that runs AS the shared
+ * Blocks execution role (the same principal as the handler) — not a bespoke per-runtime role. That
+ * shared role already carries everything the loop touches (Realtime publish via the handler wiring,
+ * Bedrock, the conversation/message tables, the session bucket); the Agent adds only the
+ * AgentCore-specific bits — the scoped `bedrock-agentcore` assume-role trust, Bedrock model access,
+ * and the shared handler's permission to INVOKE the runtime — and injects the config location so the
+ * container loads the same app config as the handler.
+ */
+import { test, before, after } from 'node:test';
+import assert from 'node:assert';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { BlocksStack, BlocksPresets } from '@aws-blocks/core/cdk';
+import { LambdaCompute } from '@aws-blocks/bb-lambda-compute/cdk';
+import { Agent } from './index.cdk.js';
+/**
+ * Inject LambdaCompute as the stack's default compute, the same way
+ * `@aws-blocks/blocks` does for real apps. `main` (PR #459) made the Agent
+ * resolve the stack's `defaultCompute` at construction (the Realtime/AgentCore
+ * wiring reads it), so a bare handler-only stub stack (no default compute) can
+ * no longer synthesize it — `BlocksStack.create` initializes the default
+ * compute the getter resolves to. (`root as never` is core's existing plumbing
+ * pattern for the factory signature.)
+ */
+const lambdaFactory = (root) => new LambdaCompute(root, 'DefaultCompute');
+/** A real directory to hand fromCodeAsset (any existing dir works for a synth-only test). */
+const ASSET_DIR = dirname(fileURLToPath(import.meta.url));
+let tmpDir;
+let handlerPath;
+let backendPath;
+before(() => {
+    // Building Blocks resolve to their mock entry points unless `--conditions=cdk`
+    // is active; keep it set so `BlocksStack.create` produces real CloudFormation.
+    process.env.NODE_OPTIONS = `${process.env.NODE_OPTIONS ?? ''} --conditions=cdk`;
+    // `BlocksStack.create` needs a real backend handler + backend module on disk
+    // (it imports the backend module and points the handler compute at the file).
+    tmpDir = mkdtempSync(join(ASSET_DIR, 'tmp-agent-cdk-'));
+    handlerPath = join(tmpDir, 'handler.mjs');
+    writeFileSync(handlerPath, "export const handler = async () => ({ statusCode: 200, body: '{}' });\n");
+    backendPath = join(tmpDir, 'backend.mjs');
+    writeFileSync(backendPath, 'export default () => {};\n');
+});
+after(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+async function synth() {
+    const app = new cdk.App();
+    // Real BlocksStack (with the shared executionRole/BlocksRole + a LambdaCompute default compute)
+    // so the Agent can resolve its default compute. `id` === 'teststack' so BLOCKS_STACK_NAME (derived
+    // from the owning root id) resolves to 'teststack', which the injection assertion below matches.
+    const stack = await BlocksStack.create(app, 'teststack', {
+        backendHandlerPath: handlerPath,
+        backendCDKPath: backendPath,
+        defaults: BlocksPresets.production,
+        defaultComputeFactory: lambdaFactory,
+    });
+    // agentcoreAssetPath bypasses the synth-time co-bundle (which needs a BlocksStack backend path).
+    new Agent(stack, 'agent', { systemPrompt: 'You are a test agent.', agentcoreAssetPath: ASSET_DIR });
+    return Template.fromStack(stack);
+}
+test('CDK: Agent provisions an AgentCore Runtime for the loop', async () => {
+    const template = await synth();
+    assert.ok(Object.keys(template.findResources('AWS::BedrockAgentCore::Runtime')).length >= 1, 'expected an AWS::BedrockAgentCore::Runtime resource');
+});
+test('CDK: the loop runs as the shared execution role, which carries everything it touches', async () => {
+    const template = await synth();
+    const json = JSON.stringify(template.toJSON());
+    // Realtime publish (both halves) — load-bearing for streaming from the container. Granted to the
+    // shared role by the Realtime BB's handler wiring (not by the Agent), and inherited because the
+    // loop runs AS that role.
+    assert.ok(json.includes('execute-api:ManageConnections'), 'Realtime postToConnection');
+    assert.ok(json.includes('dynamodb:Query'), 'connections-table + history query');
+    // Model + storage the loop uses (Bedrock granted here; S3/DynamoDB via the child BBs).
+    assert.ok(json.includes('bedrock:InvokeModel'), 'Bedrock invoke');
+    assert.ok(json.includes('s3:GetObject'), 'session-bucket access (via FileBucket)');
+    // The RPC handler (also the shared role) can start the loop.
+    assert.ok(json.includes('bedrock-agentcore:InvokeAgentRuntime'), 'InvokeAgentRuntime');
+    // The runtime runs AS the shared BlocksRole — not a bespoke per-runtime role. Its RoleArn
+    // should reference BlocksRole, and there should be no `RuntimeRole` construct anywhere.
+    const runtime = Object.values(template.findResources('AWS::BedrockAgentCore::Runtime'))[0];
+    assert.ok(JSON.stringify(runtime.Properties ?? {}).includes('BlocksRole'), 'runtime executionRole should be the shared BlocksRole');
+    assert.ok(!json.includes('RuntimeRole'), 'no bespoke per-runtime role should be created');
+    // The container is given the config location so loadConfigToProcessEnv() loads the same full app
+    // config as the handler (delivers BLOCKS_RT_CALLBACK_URL + any config-backed BB values a tool needs).
+    const runtimeJson = JSON.stringify(runtime.Properties ?? {});
+    assert.ok(runtimeJson.includes('BLOCKS_CONFIG_BUCKET'), 'runtime must be injected BLOCKS_CONFIG_BUCKET');
+    assert.ok(runtimeJson.includes('BLOCKS_CONFIG_KEY'), 'runtime must be injected BLOCKS_CONFIG_KEY');
+    // BLOCKS_STACK_NAME must be the owning root id (`backendStackName`) — the SAME value the handler
+    // uses to derive resource names — so the container's namespace matches what CDK provisioned. Here
+    // the owning BlocksStack's id is 'teststack', so backendStackName resolves to 'teststack'.
+    assert.ok(runtimeJson.includes('BLOCKS_STACK_NAME'), 'runtime must be injected BLOCKS_STACK_NAME');
+    assert.ok(runtimeJson.includes('teststack'), 'BLOCKS_STACK_NAME resolves to the owning root id');
+});
+test('CDK: the Agent adds the bedrock-agentcore assume-role trust to the shared role (scoped)', async () => {
+    // Core is BB-agnostic — it does not trust bedrock-agentcore. The Agent adds that trust here, so
+    // the AgentCore Runtime can assume the shared role it runs AS. It must be scoped by
+    // aws:SourceAccount (AWS's recommended AgentCore trust policy), and lambda trust must remain.
+    const template = await synth();
+    const roles = template.findResources('AWS::IAM::Role');
+    const blocksRoleId = Object.keys(roles).find(k => k.includes('BlocksRole'));
+    assert.ok(blocksRoleId, 'expected the shared BlocksRole');
+    const statements = roles[blocksRoleId].Properties.AssumeRolePolicyDocument.Statement;
+    const servicesOf = (s) => {
+        const svc = s.Principal?.Service;
+        return Array.isArray(svc) ? svc : svc ? [svc] : [];
+    };
+    const services = statements.flatMap(servicesOf);
+    assert.ok(services.includes('lambda.amazonaws.com'), 'shared role must stay Lambda-assumable');
+    assert.ok(services.includes('bedrock-agentcore.amazonaws.com'), 'shared role must be assumable by the AgentCore Runtime');
+    const agentCoreStmt = statements.find(s => servicesOf(s).includes('bedrock-agentcore.amazonaws.com'));
+    assert.ok(agentCoreStmt?.Condition, 'AgentCore trust statement must carry a scoping Condition');
+    assert.ok(JSON.stringify(agentCoreStmt.Condition).includes('aws:SourceAccount'), 'AgentCore trust must be scoped by aws:SourceAccount');
+});
+test('CDK: multiple agents add the identical shared-role grants ONCE, not per-agent', async () => {
+    // Every agent would otherwise add the SAME bedrock-agentcore trust / Bedrock / InvokeAgentRuntime
+    // statements to the one shared role. They're identical (stack-scoped), so they must be added
+    // exactly once regardless of agent count — keeping the shared role's policy from bloating with
+    // duplicates. (Overflow into managed policies is a normal CDK mechanism and not asserted against.)
+    const app = new cdk.App();
+    const stack = await BlocksStack.create(app, 'teststack', {
+        backendHandlerPath: handlerPath,
+        backendCDKPath: backendPath,
+        defaults: BlocksPresets.production,
+        defaultComputeFactory: lambdaFactory,
+    });
+    for (const id of ['agent1', 'agent2', 'agent3']) {
+        new Agent(stack, id, { systemPrompt: 'You are a test agent.', agentcoreAssetPath: ASSET_DIR });
+    }
+    const template = Template.fromStack(stack);
+    const json = JSON.stringify(template.toJSON());
+    // Three runtimes (per-agent), but the shared-role grant statements appear once (deduped).
+    assert.strictEqual(Object.keys(template.findResources('AWS::BedrockAgentCore::Runtime')).length, 3, 'three runtimes');
+    const invokeGrants = json.split('bedrock-agentcore:InvokeAgentRuntime').length - 1;
+    assert.strictEqual(invokeGrants, 1, `InvokeAgentRuntime should be granted once, found ${invokeGrants}`);
+});