amazon-bedrock-agentcore-samples/04-infrastructure-as-code/cdk/python/multi-agent-runtime/README.md

Multi-Agent AgentCore Runtime - CDK

This CDK stack demonstrates a multi-agent architecture where one agent (orchestrator) can invoke another agent (specialist) to handle complex tasks. This pattern is useful for building sophisticated AI systems with specialized capabilities.

Table of Contents

• Overview
• Architecture
• Prerequisites
• Deployment
• Testing
• Sample Queries
• Cleanup
• Cost Estimate
• Troubleshooting
• 🤝 Contributing
• 📄 License

Overview

This CDK stack creates a two-agent system that demonstrates agent-to-agent communication:

Agent 1: Orchestrator Agent

• Role: Main entry point for user queries
• Capabilities:
  • Handles simple queries directly
  • Delegates complex tasks to Agent 2
  • Has a tool to invoke Agent 2's runtime
• Use Cases: Routing, task delegation, simple Q&A

Agent 2: Specialist Agent

• Role: Expert agent for detailed analysis
• Capabilities:
  • Provides in-depth analytical responses
  • Handles complex reasoning tasks
  • Focuses on accuracy and completeness
• Use Cases: Data analysis, expert knowledge, detailed explanations

Key Features

• Multi-Agent Communication: Agent 1 can invoke Agent 2 using bedrock-agentcore:InvokeAgentRuntime
• Automatic Orchestration: Agent 1 decides when to delegate based on query complexity
• Independent Deployment: Each agent has its own ECR repository and runtime
• Modular Architecture: Easy to extend with additional specialized agents

Architecture

The architecture consists of:

• User: Sends questions to Agent 1 (Orchestrator) and receives responses
• Agent 1 - Orchestrator Agent:
  • AWS CodeBuild: Builds the ARM64 Docker container image for Agent 1
  • Amazon ECR Repository: Stores Agent 1's container image
  • AgentCore Runtime: Hosts the Orchestrator Agent
    • Routes simple queries directly
    • Delegates complex queries to Agent 2 using the call_specialist_agent tool
    • Invokes Amazon Bedrock LLMs for reasoning
  • IAM Role: Permissions to invoke Agent 2's runtime and access Bedrock
• Agent 2 - Specialist Agent:
  • AWS CodeBuild: Builds the ARM64 Docker container image for Agent 2
  • Amazon ECR Repository: Stores Agent 2's container image
  • AgentCore Runtime: Hosts the Specialist Agent
    • Provides detailed analysis and expert responses
    • Invokes Amazon Bedrock LLMs for in-depth reasoning
  • IAM Role: Standard runtime permissions and Bedrock access
• Amazon Bedrock LLMs: Provides AI model capabilities for both agents
• Agent-to-Agent Communication: Agent 1 can invoke Agent 2's runtime via bedrock-agentcore:InvokeAgentRuntime API

Prerequisites

AWS Account Setup

1. AWS Account: You need an active AWS account with appropriate permissions

   • Create AWS Account
   • AWS Console Access

2. AWS CLI: Install and configure AWS CLI with your credentials

   • Install AWS CLI
   • Configure AWS CLI

   aws configure
   

3. Python 3.10+ and AWS CDK v2 installed

   # Install CDK
   npm install -g aws-cdk
   
   # Verify installation
   cdk --version
   

4. CDK version 2.220.0 or later (for BedrockAgentCore support)

5. Bedrock Model Access: Enable access to Amazon Bedrock models in your AWS region

   • Navigate to Amazon Bedrock Console
   • Go to "Model access" and request access to:
     • Anthropic Claude models
   • Bedrock Model Access Guide

6. Required Permissions: Your AWS user/role needs permissions for:

   • CloudFormation stack operations
   • ECR repository management
   • IAM role creation
   • Lambda function creation
   • CodeBuild project creation
   • BedrockAgentCore resource creation

Deployment

CDK vs CloudFormation

This is the CDK version of the multi-agent runtime. If you prefer CloudFormation, see the CloudFormation version.

Option 1: Quick Deploy (Recommended)

# Install dependencies
pip install -r requirements.txt

# Bootstrap CDK (first time only)
cdk bootstrap

# Deploy
cdk deploy

Option 2: Step by Step

# 1. Create and activate Python virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Bootstrap CDK in your account/region (first time only)
cdk bootstrap

# 4. Synthesize the CloudFormation template (optional)
cdk synth

# 5. Deploy the stack
cdk deploy --require-approval never

# 6. Get outputs
cdk list

Deployment Time

• Expected Duration: 15-20 minutes
• Main Steps:
  • Stack creation: ~2 minutes
  • Docker image builds (CodeBuild): ~10-12 minutes
  • Runtime provisioning: ~3-5 minutes

Testing

Test Agent 1 (Orchestrator)

Agent 1 is your main entry point. It will handle simple queries directly or delegate to Agent 2 for complex tasks.

Using AWS CLI

# Get Agent1 Runtime ID
AGENT1_ID=$(aws cloudformation describe-stacks \
  --stack-name MultiAgentDemo \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`Agent1RuntimeId`].OutputValue' \
  --output text)

# Test with a simple query (Agent1 handles directly)
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-id $AGENT1_ID \
  --qualifier DEFAULT \
  --payload '{"prompt": "Hello, how are you?"}' \
  --region us-east-1 \
  response.json

# Test with a complex query (Agent1 delegates to Agent2)
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-id $AGENT1_ID \
  --qualifier DEFAULT \
  --payload '{"prompt": "Provide a detailed analysis of cloud computing benefits"}' \
  --region us-east-1 \
  response.json

cat response.json

Using AWS Console

1. Navigate to Bedrock AgentCore Console
2. Go to "Runtimes" in the left navigation
3. Find Agent1 runtime (name starts with MultiAgentDemo_OrchestratorAgent)
4. Click on the runtime name
5. Click "Test" button
6. Enter test payload:

   {
     "prompt": "Hello, how are you?"
   }
   

7. Click "Invoke"

Test Agent 2 (Specialist) Directly

You can also test Agent 2 directly to see its specialized capabilities.

# Get Agent2 Runtime ID
AGENT2_ID=$(aws cloudformation describe-stacks \
  --stack-name MultiAgentDemo \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`Agent2RuntimeId`].OutputValue' \
  --output text)

# Invoke Agent2 directly
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-id $AGENT2_ID \
  --qualifier DEFAULT \
  --payload '{"prompt": "Explain quantum computing in detail"}' \
  --region us-east-1 \
  response.json

Sample Queries

Queries that Agent 1 Handles Directly

These simple queries don't require specialist knowledge:

1. Greetings:

   {"prompt": "Hello, how are you?"}
   

2. Simple Math:

   {"prompt": "What is 5 + 3?"}
   

Queries that Trigger Agent 2 Delegation

These complex queries require expert analysis:

1. Detailed Analysis:

   {"prompt": "Provide a detailed analysis of the benefits and drawbacks of serverless architecture"}
   

2. Expert Knowledge:

   {"prompt": "Explain the CAP theorem and its implications for distributed systems"}
   

3. Complex Reasoning:

   {"prompt": "Compare and contrast different machine learning algorithms for time series forecasting"}
   

4. In-depth Explanation:

   {"prompt": "Provide expert analysis on best practices for securing cloud infrastructure"}
   

Cleanup

Using CDK (Recommended)

cdk destroy

Using AWS CLI

aws cloudformation delete-stack \
  --stack-name MultiAgentDemo \
  --region us-east-1

# Wait for deletion to complete
aws cloudformation wait stack-delete-complete \
  --stack-name MultiAgentDemo \
  --region us-east-1

Using AWS Console

1. Navigate to CloudFormation Console
2. Select the MultiAgentDemo stack
3. Click "Delete"
4. Confirm deletion

Cost Estimate

Monthly Cost Breakdown (us-east-1)

Service	Usage	Monthly Cost
AgentCore Runtimes	2 runtimes, minimal usage	~$10-20
ECR Repositories	2 repositories, <2GB storage	~$0.20
CodeBuild	Occasional builds	~$2-4
Lambda	Custom resource executions	~$0.01
CloudWatch Logs	Agent logs	~$1.00
Bedrock Model Usage	Pay per token	Variable*

Estimated Total: ~$13-25/month (excluding Bedrock model usage)

*Bedrock costs depend on your usage patterns and chosen models. See Bedrock Pricing for details.

Cost Optimization Tips

• Delete when not in use: Use cdk destroy to remove all resources
• Monitor usage: Set up CloudWatch billing alarms
• Choose efficient models: Select appropriate Bedrock models for your use case

Troubleshooting

CDK Bootstrap Required

If you see bootstrap errors:

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

Permission Issues

Ensure your IAM user/role has:

• CDKToolkit permissions or equivalent
• Permissions to create all resources in the stack
• iam:PassRole for service roles

Python Dependencies

Install dependencies in the project directory:

pip install -r requirements.txt

Build Failures

Check CodeBuild logs in the AWS Console:

1. Go to CodeBuild console
2. Find the build projects (names contain "agent1-build" and "agent2-build")
3. Check build history and logs

Agent Communication Issues

If Agent 1 can't invoke Agent 2:

1. Check IAM permissions for bedrock-agentcore:InvokeAgentRuntime
2. Verify Agent 2 runtime is running
3. Check CloudWatch logs for both agents

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.