@cdklabs/cdk-appmod-catalog-blueprints 1.10.0 → 1.12.0

package/lib/framework/agents/interactive-agent.d.ts

@@ -1,11 +1,14 @@
 import { Duration, RemovalPolicy } from 'aws-cdk-lib';
 import { RestApi } from 'aws-cdk-lib/aws-apigateway';
+import { CfnRuntime } from 'aws-cdk-lib/aws-bedrockagentcore';
 import { UserPool, UserPoolClient } from 'aws-cdk-lib/aws-cognito';
-import { IKey } from 'aws-cdk-lib/aws-kms';
-import { IFunction, Architecture } from 'aws-cdk-lib/aws-lambda';
+import { Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
+import { IFunction, Architecture, ILayerVersion } from 'aws-cdk-lib/aws-lambda';
 import { IBucket } from 'aws-cdk-lib/aws-s3';
 import { Construct } from 'constructs';
 import { BaseAgent, BaseAgentProps } from './base-agent';
+import { Network } from '../foundation';
 /**
  * Strategy interface for pluggable communication mechanisms.
  * Default implementation is StreamingHttpAdapter (API Gateway REST API with response streaming).
@@ -133,6 +136,9 @@ export declare class StreamingHttpAdapter implements ICommunicationAdapter {
  *
  * Session stores manage conversation state persistence across HTTP requests.
  * The default implementation (S3SessionManager) uses S3 for durable storage.
+ *
+ * @deprecated Use Strands-native `S3SessionManager` from `strands.session.s3_session_manager` instead.
+ * The Python handler now uses Strands-native session management automatically.
  */
 export interface ISessionStore {
     /**
@@ -148,6 +154,8 @@ export interface ISessionStore {
 }
 /**
  * Configuration properties for S3SessionManager.
+ *
+ * @deprecated Use Strands-native `S3SessionManager` from `strands.session.s3_session_manager` instead.
  */
 export interface S3SessionManagerProps {
     /**
@@ -208,6 +216,11 @@ export interface S3SessionManagerProps {
  *   sessionStore: sessionManager
  * });
  * ```
+ *
+ * @deprecated Use Strands-native `S3SessionManager` from `strands.session.s3_session_manager` instead.
+ * The Python handler now uses Strands-native session management automatically.
+ * An S3 bucket is still created for the Strands session manager; this CDK class
+ * is no longer needed to configure session persistence.
  */
 export declare class S3SessionManager implements ISessionStore {
     /**
@@ -233,6 +246,10 @@ export declare class S3SessionManager implements ISessionStore {
  *
  * Context strategies control how conversation history is maintained and provided
  * to the agent. Different strategies enable different conversation patterns.
+ *
+ * @deprecated Use Strands-native `SlidingWindowConversationManager` from
+ * `strands.agent.conversation_manager` instead. The Python handler now uses
+ * Strands-native conversation management automatically.
  */
 export interface IContextStrategy {
     /**
@@ -244,6 +261,9 @@ export interface IContextStrategy {
 }
 /**
  * Configuration properties for SlidingWindowConversationManager.
+ *
+ * @deprecated Use Strands-native `SlidingWindowConversationManager` from
+ * `strands.agent.conversation_manager` instead.
  */
 export interface SlidingWindowConversationManagerProps {
     /**
@@ -274,6 +294,10 @@ export interface SlidingWindowConversationManagerProps {
  *   contextStrategy: contextManager
  * });
  * ```
+ *
+ * @deprecated Use Strands-native `SlidingWindowConversationManager` from
+ * `strands.agent.conversation_manager` instead. The Python handler now handles
+ * conversation windowing natively.
  */
 export declare class SlidingWindowConversationManager implements IContextStrategy {
     /**
@@ -291,6 +315,9 @@ export declare class SlidingWindowConversationManager implements IContextStrateg
  *
  * Disables conversation history, treating each message as independent.
  * Useful for stateless use cases where context is not needed.
+ *
+ * @deprecated The Python handler now uses Strands-native conversation management.
+ * To disable conversation history, omit the session bucket configuration.
  */
 export declare class NullConversationManager implements IContextStrategy {
     /**
@@ -420,6 +447,242 @@ export declare class NoAuthenticator implements IAuthenticator {
      */
     environmentVariables(): Record<string, string>;
 }
+/**
+ * Configuration passed to a hosting adapter's deploy method.
+ */
+export interface AgentHostingConfig {
+    /** CDK scope for creating resources. */
+    readonly scope: Construct;
+    /** Agent name identifier. */
+    readonly agentName: string;
+    /** IAM role for the agent runtime. */
+    readonly agentRole: Role;
+    /** Environment variables to set on the runtime. */
+    readonly environment: Record<string, string>;
+    /** KMS encryption key. */
+    readonly encryptionKey: Key;
+    /** Optional VPC network configuration. */
+    readonly network?: Network;
+    /** Lambda architecture (Lambda hosting only). */
+    readonly architecture?: Architecture;
+    /** Lambda memory size in MB (Lambda hosting only). */
+    readonly memorySize?: number;
+    /** Lambda timeout (Lambda hosting only). */
+    readonly timeout?: Duration;
+    /** Reserved concurrent executions (Lambda hosting only). */
+    readonly reservedConcurrentExecutions?: number;
+    /** Lambda layers from agent definition (Lambda hosting only). */
+    readonly lambdaLayers?: ILayerVersion[];
+    /** Lambda layers from knowledge bases (Lambda hosting only). */
+    readonly knowledgeBaseLayers?: ILayerVersion[];
+    /** Whether observability is enabled. */
+    readonly enableObservability?: boolean;
+    /** Agent tools location definitions (JSON serialized). */
+    readonly toolsConfig: string;
+    /** System prompt S3 bucket name. */
+    readonly systemPromptBucket: string;
+    /** System prompt S3 key. */
+    readonly systemPromptKey: string;
+    /** Knowledge base configs (JSON serialized). */
+    readonly knowledgeBaseConfigs?: string;
+    /** Knowledge base system prompt addition. */
+    readonly knowledgeBaseSystemPromptAddition?: string;
+    /** Removal policy for resources. */
+    readonly removalPolicy?: RemovalPolicy;
+}
+/**
+ * Result returned by a hosting adapter's deploy method.
+ */
+export interface AgentHostingResult {
+    /** The agent endpoint URL or ARN. */
+    readonly endpoint: string;
+    /** The Lambda function (if Lambda-hosted). */
+    readonly agentFunction?: IFunction;
+    /** The AgentCore CfnRuntime (if AgentCore-hosted). */
+    readonly cfnRuntime?: CfnRuntime;
+}
+/**
+ * Strategy interface for pluggable hosting backends.
+ *
+ * Hosting adapters encapsulate the infrastructure needed to run an agent.
+ * The default implementation is `LambdaHostingAdapter` (Lambda + LWA + API Gateway).
+ * `AgentCoreRuntimeHostingAdapter` provides an alternative using AgentCore Runtime.
+ */
+export interface IHostingAdapter {
+    /**
+     * The IAM service principal that this hosting backend requires.
+     *
+     * BaseAgent uses this to create the agent role with the correct trust policy.
+     * For example, Lambda hosting requires `lambda.amazonaws.com` while AgentCore
+     * hosting requires `bedrock-agentcore.amazonaws.com`.
+     */
+    readonly servicePrincipal: ServicePrincipal;
+    /**
+     * Deploy the agent hosting infrastructure.
+     *
+     * @param config - Configuration for the agent hosting
+     * @returns The hosting result including endpoint and optional resources
+     */
+    deploy(config: AgentHostingConfig): AgentHostingResult;
+}
+/**
+ * Configuration properties for LambdaHostingAdapter.
+ */
+export interface LambdaHostingAdapterProps {
+    /**
+     * Communication adapter for client-agent interaction.
+     *
+     * @default StreamingHttpAdapter
+     */
+    readonly communicationAdapter?: ICommunicationAdapter;
+    /**
+     * Authenticator for securing API endpoints.
+     *
+     * @default CognitoAuthenticator
+     */
+    readonly authenticator?: IAuthenticator;
+    /**
+     * Lambda function memory size in MB.
+     *
+     * @default 1024
+     */
+    readonly memorySize?: number;
+    /**
+     * Lambda function timeout.
+     *
+     * @default Duration.minutes(15)
+     */
+    readonly timeout?: Duration;
+    /**
+     * Lambda function architecture.
+     *
+     * @default Architecture.X86_64
+     */
+    readonly architecture?: Architecture;
+    /**
+     * Reserved concurrent executions for the Lambda function.
+     *
+     * @default No reserved concurrency
+     */
+    readonly reservedConcurrentExecutions?: number;
+}
+/**
+ * Lambda hosting adapter for InteractiveAgent.
+ *
+ * Deploys the agent as a Lambda function behind Lambda Web Adapter and API Gateway
+ * REST API with response streaming. This is the default hosting backend.
+ *
+ * ## Architecture
+ *
+ * ```
+ * Client → POST /chat → API Gateway REST API (STREAM) → Lambda (FastAPI + LWA) → Bedrock
+ * Client ← SSE stream ← API Gateway ← Lambda response streaming ← Agent tokens
+ * ```
+ */
+export declare class LambdaHostingAdapter implements IHostingAdapter {
+    /** The communication adapter. */
+    readonly communicationAdapter?: ICommunicationAdapter;
+    /** The authenticator. */
+    readonly authenticator?: IAuthenticator;
+    private readonly props;
+    constructor(props?: LambdaHostingAdapterProps);
+    get servicePrincipal(): ServicePrincipal;
+    /**
+     * Deploy Lambda + LWA + API Gateway hosting infrastructure.
+     */
+    deploy(config: AgentHostingConfig): AgentHostingResult;
+}
+/**
+ * Custom JWT authorizer configuration for AgentCore Runtime.
+ */
+export interface AgentCoreJwtAuthorizerConfig {
+    /** OIDC discovery URL. */
+    readonly discoveryUrl: string;
+    /** Allowed audiences. */
+    readonly allowedAudience?: string[];
+    /** Allowed client IDs. */
+    readonly allowedClients?: string[];
+}
+/**
+ * Configuration properties for AgentCoreRuntimeHostingAdapter.
+ */
+export interface AgentCoreRuntimeHostingAdapterProps {
+    /**
+     * ECR container image URI. If not provided, builds from the bundled handler source.
+     *
+     * @default Builds from agentcore-agent-handler directory
+     */
+    readonly containerImageUri?: string;
+    /**
+     * Network mode: 'PUBLIC' or 'VPC'.
+     *
+     * @default 'PUBLIC'
+     */
+    readonly networkMode?: string;
+    /**
+     * Custom JWT authorizer configuration.
+     * Omit for IAM-only auth.
+     */
+    readonly customJwtAuthorizer?: AgentCoreJwtAuthorizerConfig;
+    /**
+     * Protocol configuration: 'HTTP' | 'MCP' | 'A2A'.
+     *
+     * @default 'HTTP'
+     */
+    readonly protocolConfiguration?: string;
+    /**
+     * Runtime endpoint name.
+     *
+     * @default Auto-generated from agent name
+     */
+    readonly endpointName?: string;
+}
+/**
+ * AgentCore Runtime hosting adapter for InteractiveAgent.
+ *
+ * Deploys the agent as a container running on AgentCore Runtime (microVM).
+ * Uses L1 constructs `CfnRuntime` and `CfnRuntimeEndpoint` from
+ * `aws-cdk-lib/aws-bedrockagentcore`.
+ *
+ * ## Architecture
+ *
+ * ```
+ * Client → AgentCore Runtime Endpoint → Container (FastAPI on port 8080) → Bedrock
+ * ```
+ *
+ * ## Features
+ *
+ * - **Session Isolation**: microVM provides per-session isolation (no S3 session bucket needed)
+ * - **Managed Infrastructure**: No Lambda cold starts or timeout limits
+ * - **Multiple Protocols**: HTTP, MCP, or A2A protocol support
+ * - **Container-Based**: Standard Docker image deployment
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Asset } from 'aws-cdk-lib/aws-s3-assets';
+ * import { InteractiveAgent, AgentCoreRuntimeHostingAdapter } from '@cdklabs/cdk-appmod-catalog-blueprints';
+ *
+ * declare const myPrompt: Asset;
+ *
+ * new InteractiveAgent(this, 'Agent', {
+ *   agentName: 'MyChatbot',
+ *   agentDefinition: { bedrockModel: {}, systemPrompt: myPrompt },
+ *   hostingAdapter: new AgentCoreRuntimeHostingAdapter({
+ *     networkMode: 'PUBLIC',
+ *   }),
+ * });
+ * ```
+ */
+export declare class AgentCoreRuntimeHostingAdapter implements IHostingAdapter {
+    private readonly props;
+    constructor(props?: AgentCoreRuntimeHostingAdapterProps);
+    get servicePrincipal(): ServicePrincipal;
+    /**
+     * Deploy AgentCore Runtime hosting infrastructure.
+     */
+    deploy(config: AgentHostingConfig): AgentHostingResult;
+}
 /**
  * Configuration properties for InteractiveAgent.
  *
@@ -427,6 +690,19 @@ export declare class NoAuthenticator implements IAuthenticator {
  * strategy interfaces for building real-time conversational AI agents.
  */
 export interface InteractiveAgentProps extends BaseAgentProps {
+    /**
+     * Hosting adapter for deploying the agent runtime.
+     *
+     * Use `LambdaHostingAdapter` for Lambda + API Gateway (default) or
+     * `AgentCoreRuntimeHostingAdapter` for AgentCore Runtime hosting.
+     *
+     * When provided, `communicationAdapter`, `authenticator`, `memorySize`,
+     * `timeout`, `architecture`, and `reservedConcurrentExecutions` props
+     * are ignored (configure them on the adapter directly).
+     *
+     * @default LambdaHostingAdapter
+     */
+    readonly hostingAdapter?: IHostingAdapter;
     /**
      * Communication adapter for client-agent interaction.
      *
@@ -438,6 +714,8 @@ export interface InteractiveAgentProps extends BaseAgentProps {
      * Set to undefined to disable session persistence (stateless mode).
      *
      * @default S3SessionManager with 24-hour TTL
+     * @deprecated Session management is now handled by Strands-native `S3SessionManager`.
+     * An S3 bucket is always created and passed as `SESSION_BUCKET` env var.
      */
     readonly sessionStore?: ISessionStore;
     /**
@@ -457,6 +735,8 @@ export interface InteractiveAgentProps extends BaseAgentProps {
      * Context strategy for conversation history management.
      *
      * @default SlidingWindowConversationManager with 20 messages
+     * @deprecated Conversation management is now handled by Strands-native
+     * `SlidingWindowConversationManager` in the Python handler.
      */
     readonly contextStrategy?: IContextStrategy;
     /**
@@ -465,6 +745,8 @@ export interface InteractiveAgentProps extends BaseAgentProps {
      * Ignored if contextStrategy is provided.
      *
      * @default 20
+     * @deprecated Conversation windowing is now handled by Strands-native
+     * `SlidingWindowConversationManager` in the Python handler (default: 20).
      */
     readonly messageHistoryLimit?: number;
     /**
@@ -550,13 +832,14 @@ export interface InteractiveAgentProps extends BaseAgentProps {
  * ```
  */
 export declare class InteractiveAgent extends BaseAgent {
-    readonly agentFunction: IFunction;
+    readonly agentFunction?: IFunction;
     readonly adapter?: ICommunicationAdapter;
     readonly sessionStore?: ISessionStore;
     readonly contextStrategy?: IContextStrategy;
     readonly authenticator?: IAuthenticator;
     readonly apiEndpoint: string;
     readonly sessionBucket?: IBucket;
+    readonly cfnRuntime?: CfnRuntime;
     constructor(scope: Construct, id: string, props: InteractiveAgentProps);
     /**
      * Validates InteractiveAgent props.