@aws-blocks/bb-agent 0.3.5 → 0.4.1

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 { BuildingBlockScope } 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 {
+export declare class Agent extends BuildingBlockScope {
     /**
      * 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;AASpD,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;CAyCxD"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAOpD,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,kBAAkB;IAC5C;;;;;;;;;;;OAWG;gBACS,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW;CAyChE"}

package/dist/index.cdk.js

@@ -1,43 +1,38 @@
 // 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 { BuildingBlockScope } 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 * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { AgentCoreRuntime } from './agentcore-runtime.cdk.js';
 import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
-import { INTERACTIVE_JOB_EVENT_SOURCE } from './job-event-source.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 {
+export class Agent extends BuildingBlockScope {
     /**
      * 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.executionRole.addToPrincipalPolicy(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
+        super(id, { parent: scope, vpc: { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.BEDROCK_RUNTIME] } });
+        // 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,
@@ -50,13 +45,18 @@ export class Agent extends Scope {
         }
         new Realtime(this, 'rt', {
             namespaces: {
-                chunks: { schema: agentStreamChunkSchema },
+                chunks: Realtime.namespace(agentStreamChunkSchema),
             },
         });
-        new AsyncJob(this, 'job', {
-            schema: jobPayloadSchema,
-            ...INTERACTIVE_JOB_EVENT_SOURCE,
-            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,
         });
     }
 }