New pattern - sfn-agentcore-bedrock-cdk

sfn-agentcore-bedrock-cdk/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+build
+cdk.out

sfn-agentcore-bedrock-cdk/README.md

@@ -0,0 +1,114 @@
+# Step Functions with Bedrock AgentCore Multi-Agent Orchestration
+
+This pattern deploys an AWS Step Functions state machine that orchestrates multiple Bedrock AgentCore agents in parallel, then aggregates their responses into a unified summary using Amazon Bedrock Converse.
+
+Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/sfn-agentcore-bedrock-cdk
+
+Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
+
+## Requirements
+
+* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
+* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* [Node.js 18+](https://nodejs.org/en/download/) installed
+* [AWS CDK v2](https://docs.aws.amazon.com/cdk/v2/guide/getting-started.html) installed
+* [Amazon Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) enabled for your chosen model (default: Claude Sonnet) in your target region
+* One or more [Bedrock AgentCore agent runtimes](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore.html) already deployed and accessible
+
+## Architecture
+
+```
+┌──────────┐     ┌──────────────────┐     ┌──────────────────────────────────────┐
+│  Trigger  │────▶│  Step Functions   │────▶│  Map State (parallel)                │
+│  Lambda   │     │  State Machine    │     │                                      │
+└──────────┘     └──────────────────┘     │  ┌─────────────────────────────────┐  │
+                                           │  │ Invoke Agent Lambda (bundled)    │  │
+                                           │  │   → AgentCore Runtime 1          │  │
+                                           │  ├─────────────────────────────────┤  │
+                                           │  │ Invoke Agent Lambda (bundled)    │  │
+                                           │  │   → AgentCore Runtime 2          │  │
+                                           │  ├─────────────────────────────────┤  │
+                                           │  │ Invoke Agent Lambda (bundled)    │  │
+                                           │  │   → AgentCore Runtime N          │  │
+                                           │  └─────────────────────────────────┘  │
+                                           └───────────────────┬──────────────────┘
+                                                               │
+                                                               ▼
+                                           ┌──────────────────────────────────────┐
+                                           │  Aggregate Lambda                     │
+                                           │    → Bedrock Converse (summarize)     │
+                                           │    → Returns unified summary          │
+                                           └──────────────────────────────────────┘
+```
+
+## How it works
+
+1. The **Trigger Lambda** receives a prompt and a list of AgentCore runtime ARNs, then starts the Step Functions state machine execution.
+2. The **Map state** fans out to invoke each AgentCore agent in parallel. Each iteration calls the **Invoke Agent Lambda**, which uses the bundled `@aws-sdk/client-bedrock-agentcore` SDK to call `InvokeAgentRuntime` and collect the streaming response.
+3. After all agents respond, the **Aggregate Lambda** uses Amazon Bedrock Converse (Claude) to synthesize all agent responses into a single coherent summary.
+4. The state machine returns the aggregated summary along with the agent count.
+
+## Important Notes
+
+- **Bundled SDK**: The `@aws-sdk/client-bedrock-agentcore` package is not included in the Lambda runtime. The invoke-agent function uses `NodejsFunction` with esbuild bundling to include it.
+- **Streaming Response**: `InvokeAgentRuntime` returns a streaming response, which cannot be consumed directly by Step Functions SDK integrations. A Lambda intermediary collects the stream and returns the full response.
+- **Enforced Guardrails**: If your account has account-level enforced guardrails configured, all roles that call Bedrock must have `bedrock:ApplyGuardrail` permission — even if your code does not explicitly apply guardrails. The aggregate Lambda role includes this permission.
+
+## Deployment Instructions
+
+1. Clone the repository:
+    ```bash
+    git clone https://github.com/aws-samples/serverless-patterns
+    cd serverless-patterns/sfn-agentcore-bedrock-cdk
+    ```
+
+2. Install dependencies:
+    ```bash
+    npm install
+    ```
+
+3. Deploy the stack with your AgentCore runtime ARNs:
+    ```bash
+    cdk deploy \
+      --parameters AgentRuntimeArns=arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/agent1,arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/agent2 \
+      --parameters BedrockModelId=us.anthropic.claude-sonnet-4-20250514-v1:0
+    ```
+
+4. Note the `TriggerFunctionName` from the stack outputs.
+
+## Testing
+
+1. Invoke the trigger function with a prompt and your agent runtime ARNs:
+    ```bash
+    aws lambda invoke \
+      --function-name <TriggerFunctionName> \
+      --payload '{
+        "prompt": "What are the best practices for building serverless applications?",
+        "agentRuntimeArns": [
+          "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/agent1",
+          "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/agent2"
+        ]
+      }' \
+      --cli-binary-format raw-in-base64-out \
+      output.json
+    ```
+
+2. The trigger returns the Step Functions execution ARN. Monitor the execution:
+    ```bash
+    aws stepfunctions describe-execution \
+      --execution-arn <executionArn-from-output.json>
+    ```
+
+3. Once the execution completes (status: `SUCCEEDED`), view the output which contains the aggregated summary from all agents.
+
+## Cleanup
+
+```bash
+cdk destroy
+```
+
+----
+Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0

sfn-agentcore-bedrock-cdk/bin/app.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { SfnAgentcoreBedrockStack } from '../lib/sfn-agentcore-bedrock-stack';
+
+const app = new cdk.App();
+new SfnAgentcoreBedrockStack(app, 'SfnAgentcoreBedrockStack');

sfn-agentcore-bedrock-cdk/cdk.json

@@ -0,0 +1,3 @@
+{
+  "app": "npx ts-node bin/app.ts"
+}

sfn-agentcore-bedrock-cdk/example-pattern.json

@@ -0,0 +1,61 @@
+{
+  "title": "Step Functions with Bedrock AgentCore Multi-Agent Orchestration",
+  "description": "Use AWS Step Functions to orchestrate multiple Bedrock AgentCore agents in parallel via a Map state, then aggregate their responses into a unified summary using Bedrock Converse.",
+  "language": "TypeScript",
+  "level": "400",
+  "framework": "AWS CDK",
+  "introBox": {
+    "headline": "How it works",
+    "text": [
+      "This pattern deploys a Step Functions state machine that invokes multiple Bedrock AgentCore agents in parallel using a Map state, then aggregates their responses into a single coherent summary via Amazon Bedrock Converse.",
+      "The workflow: (1) A trigger Lambda starts the state machine with a prompt and list of agent runtime ARNs, (2) the Map state fans out to invoke each AgentCore agent in parallel via a bundled Lambda intermediary, (3) an aggregate Lambda uses Bedrock Converse to synthesize all agent responses into a unified summary.",
+      "Key architectural decisions: The @aws-sdk/client-bedrock-agentcore SDK is not available in the Lambda runtime and must be bundled using NodejsFunction. InvokeAgentRuntime returns a streaming response, requiring a Lambda intermediary rather than direct Step Functions SDK integration. Account-level enforced guardrails require bedrock:ApplyGuardrail permission on all Bedrock-calling roles."
+    ]
+  },
+  "gitHub": {
+    "template": {
+      "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/sfn-agentcore-bedrock-cdk",
+      "templateURL": "serverless-patterns/sfn-agentcore-bedrock-cdk",
+      "projectFolder": "sfn-agentcore-bedrock-cdk",
+      "templateFile": "lib/sfn-agentcore-bedrock-stack.ts"
+    }
+  },
+  "resources": {
+    "bullets": [
+      {
+        "text": "Amazon Bedrock AgentCore Documentation",
+        "link": "https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore.html"
+      },
+      {
+        "text": "AWS Step Functions Map State",
+        "link": "https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-map-state.html"
+      },
+      {
+        "text": "Amazon Bedrock Converse API",
+        "link": "https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-call.html"
+      }
+    ]
+  },
+  "deploy": {
+    "text": [
+      "cdk deploy --parameters AgentRuntimeArns=<comma-separated-arns> --parameters BedrockModelId=<model-id>"
+    ]
+  },
+  "testing": {
+    "text": [
+      "See the GitHub repo for detailed testing instructions."
+    ]
+  },
+  "cleanup": {
+    "text": [
+      "Delete the stack: <code>cdk destroy</code>."
+    ]
+  },
+  "authors": [
+    {
+      "name": "Nithin Chandran R",
+      "bio": "Technical Account Manager at AWS",
+      "linkedin": "nithin-chandran-r"
+    }
+  ]
+}

sfn-agentcore-bedrock-cdk/lib/sfn-agentcore-bedrock-stack.ts

@@ -0,0 +1,167 @@
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as lambdaNode from 'aws-cdk-lib/aws-lambda-nodejs';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as sfn from 'aws-cdk-lib/aws-stepfunctions';
+import * as path from 'path';
+
+export class SfnAgentcoreBedrockStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    const agentRuntimeArnsParam = new cdk.CfnParameter(this, 'AgentRuntimeArns', {
+      type: 'String',
+      default: 'arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/placeholder-agent',
+      description: 'Comma-separated list of AgentCore runtime ARNs',
+    });
+
+    const bedrockModelIdParam = new cdk.CfnParameter(this, 'BedrockModelId', {
+      type: 'String',
+      default: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+      description: 'Bedrock model ID for aggregation',
+    });
+
+    // Lambda to invoke a single AgentCore agent (bundled SDK for streaming support)
+    const invokeAgentFn = new lambdaNode.NodejsFunction(this, 'InvokeAgentFn', {
+      entry: path.join(__dirname, '..', 'src', 'invoke-agent.ts'),
+      handler: 'handler',
+      runtime: lambda.Runtime.NODEJS_20_X,
+      memorySize: 256,
+      timeout: cdk.Duration.minutes(3),
+      bundling: {
+        minify: true,
+        sourceMap: false,
+      },
+    });
+
+    // Note: AgentCore runtime ARNs are user-provided at deploy time via parameter,
+    // so resource-level scoping requires wildcard for flexibility
+    invokeAgentFn.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['bedrock-agentcore:InvokeAgentRuntime'],
+      resources: ['*'],
+    }));
+
+    // Aggregate Lambda — summarizes multi-agent responses via Bedrock Converse
+    const aggregateFn = new lambda.Function(this, 'AggregateFn', {
+      runtime: lambda.Runtime.NODEJS_20_X,
+      handler: 'aggregate.handler',
+      code: lambda.Code.fromAsset('src'),
+      memorySize: 256,
+      timeout: cdk.Duration.seconds(60),
+      environment: {
+        BEDROCK_MODEL_ID: bedrockModelIdParam.valueAsString,
+      },
+    });
+
+    aggregateFn.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['bedrock:InvokeModel'],
+      resources: [
+        `arn:aws:bedrock:${this.region}:${this.account}:inference-profile/${bedrockModelIdParam.valueAsString}`,
+        'arn:aws:bedrock:*::foundation-model/*',
+      ],
+    }));
+
+    // Required when account-level enforced guardrails are active
+    aggregateFn.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['bedrock:ApplyGuardrail'],
+      resources: [`arn:aws:bedrock:${this.region}:${this.account}:guardrail/*`],
+    }));
+
+    // SFN IAM Role
+    const sfnRole = new iam.Role(this, 'SfnRole', {
+      assumedBy: new iam.ServicePrincipal('states.amazonaws.com'),
+    });
+
+    sfnRole.addToPolicy(new iam.PolicyStatement({
+      actions: ['lambda:InvokeFunction'],
+      resources: [invokeAgentFn.functionArn, aggregateFn.functionArn],
+    }));
+
+    // State machine: Map → invoke agents in parallel → aggregate
+    const definition = {
+      Comment: 'Orchestrate multiple AgentCore agents in parallel and aggregate responses with Bedrock',
+      StartAt: 'InvokeAgents',
+      States: {
+        InvokeAgents: {
+          Type: 'Map',
+          ItemsPath: '$.agentRuntimeArns',
+          Parameters: {
+            'agentRuntimeArn.$': '$$.Map.Item.Value',
+            'prompt.$': '$.prompt',
+          },
+          Iterator: {
+            StartAt: 'CallAgent',
+            States: {
+              CallAgent: {
+                Type: 'Task',
+                Resource: 'arn:aws:states:::lambda:invoke',
+                Parameters: {
+                  FunctionName: invokeAgentFn.functionArn,
+                  'Payload.$': '$',
+                },
+                OutputPath: '$.Payload',
+                Retry: [
+                  {
+                    ErrorEquals: ['States.TaskFailed'],
+                    IntervalSeconds: 15,
+                    MaxAttempts: 2,
+                    BackoffRate: 2,
+                  },
+                ],
+                End: true,
+              },
+            },
+          },
+          ResultPath: '$.agentResults',
+          Next: 'AggregateResults',
+        },
+        AggregateResults: {
+          Type: 'Task',
+          Resource: 'arn:aws:states:::lambda:invoke',
+          Parameters: {
+            FunctionName: aggregateFn.functionArn,
+            'Payload.$': '$',
+          },
+          OutputPath: '$.Payload',
+          End: true,
+        },
+      },
+    };
+
+    const stateMachine = new sfn.CfnStateMachine(this, 'StateMachine', {
+      definitionString: JSON.stringify(definition),
+      roleArn: sfnRole.roleArn,
+      stateMachineType: 'STANDARD',
+    });
+
+    // Trigger Lambda
+    const triggerFn = new lambda.Function(this, 'TriggerFn', {
+      runtime: lambda.Runtime.NODEJS_20_X,
+      handler: 'trigger.handler',
+      code: lambda.Code.fromAsset('src'),
+      memorySize: 256,
+      timeout: cdk.Duration.seconds(60),
+      environment: {
+        STATE_MACHINE_ARN: stateMachine.attrArn,
+      },
+    });
+
+    triggerFn.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['states:StartExecution'],
+      resources: [stateMachine.attrArn],
+    }));
+
+    new cdk.CfnOutput(this, 'StateMachineArn', {
+      value: stateMachine.attrArn,
+    });
+
+    new cdk.CfnOutput(this, 'TriggerFunctionName', {
+      value: triggerFn.functionName,
+    });
+
+    new cdk.CfnOutput(this, 'TriggerFunctionArn', {
+      value: triggerFn.functionArn,
+    });
+  }
+}