mirror of
https://github.com/awslabs/amazon-bedrock-agentcore-samples.git
synced 2025-09-08 20:50:46 +00:00
9912db27e2
- Add architecture.png diagram to images/ directory - Update ARCHITECTURE-FLOW.md to include architecture diagram - Move demo.gif from demo/ to images/ directory for better organization - Update README.md to reference new demo location - Minor updates to agent Lambda configuration and template - Consolidate all visual assets under images/ directory
38 KiB
38 KiB
Architecture Flow - Bedrock AgentCore Gateway MCP Integration
📋 Navigation
🏠 README | 📖 Setup Guide | 🏗️ Architecture | 🔧 Scripts | 🤖 Client | ⚙️ Config | 🔐 Okta Setup
System Architecture
Component Overview
Client Application
- CLI Interface: Interactive command-line client
- Authentication: AWS SigV4 + Okta JWT
- Conversation Management: Persistent chat history
- Natural Language: Human-friendly AWS operations
Function URL
- Direct Lambda Access: No API Gateway required
- Authentication: AWS SigV4 (IAM_AUTH)
- Streaming Support: Real-time AI responses
- CORS Enabled: For web client compatibility
AWS Operations Agent Lambda
- Strands Agent: AI-powered conversation manager
- MCP Client: Connects to Bedrock AgentCore Gateway
- DynamoDB Integration: Conversation persistence
- Streaming Responses: Real-time AI output
Bedrock AgentCore Gateway
- MCP Server: Model Context Protocol implementation
- Authentication: Okta JWT validation
- Target Management: Lambda function invocation
- Tool Registration: 20 AWS service tools
MCP Tool Lambda
- Docker Container: Consistent runtime environment
- AWS SDK: Access to 20+ AWS services
- Tool Implementation: Natural language AWS operations
- Security: Read-only operations by default
DynamoDB
- Conversation Storage: Persistent chat history
- TTL Support: Automatic expiration of old conversations
- On-Demand Capacity: Cost-effective scaling
- Point-in-Time Recovery: Data protection
Detailed Component Diagrams
Client Application
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Client Application │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Command Line Interface │ │
│ │ • Interactive prompt with command history │ │
│ │ • Streaming response display │ │
│ │ • Tool invocation visualization │ │
│ │ • Conversation management commands │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Authentication Manager │ │
│ │ • AWS SigV4 signing for Lambda Function URL │ │
│ │ • Okta token management for MCP authentication │ │
│ │ • Token refresh and validation │ │
│ │ • Profile selection (demo1, etc.) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ HTTP Client │ │
│ │ • Streaming response handling │ │
│ │ • Request retry with exponential backoff │ │
│ │ • Timeout management │ │
│ │ • Error handling and reporting │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Client ID: cli-client-<random-id> │
│ AWS Profile: demo1 │
│ AWS Region: us-east-1 │
│ Okta Token: eyJraWQiOiJxczFVSzFqWnN0NmZyZU... │
│ │
└─────────────────────────────────────────────────────────────────┘
Function URL
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Lambda Function URL │
│ │
│ URL: https://<unique-id>.lambda-url.us-east-1.on.aws/ │
│ Auth Type: AWS_IAM │
│ Invoke Mode: RESPONSE_STREAM │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Authentication │ │
│ │ • AWS SigV4 validation │ │
│ │ • IAM policy enforcement │ │
│ │ • No additional authorization layer needed │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ CORS Configuration │ │
│ │ • AllowOrigins: * │ │
│ │ • AllowMethods: * │ │
│ │ • AllowHeaders: * │ │
│ │ • AllowCredentials: true │ │
│ │ • MaxAge: 86400 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Endpoints │ │
│ │ • /stream - Streaming chat responses │ │
│ │ • /chat - Non-streaming chat │ │
│ │ • /api/conversations - Conversation management │ │
│ │ • /api/tools/fetch - Available MCP tools │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
AWS Operations Agent Lambda
┌─────────────────────────────────────────────────────────────────┐
│ │
│ AWS Operations Agent Lambda │
│ │
│ Function Name: aws-operations-agent-<environment> │
│ Runtime: Python 3.11 (Container Image) │
│ Memory: 1536 MB │
│ Timeout: 300 seconds │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ FastAPI Application │ │
│ │ • AWS Lambda Web Adapter integration │ │
│ │ • Streaming response support │ │
│ │ • API endpoints for conversation management │ │
│ │ • Error handling and validation │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Strands Agent │ │
│ │ • Claude 3.7 Sonnet integration │ │
│ │ • Tool selection and execution │ │
│ │ • Conversation context management │ │
│ │ • Natural language understanding │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ MCP Client │ │
│ │ • Bedrock AgentCore Gateway integration │ │
│ │ • Tool discovery and invocation │ │
│ │ • Authentication with Okta token │ │
│ │ • Error handling and retries │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ DynamoDB Integration │ │
│ │ • Conversation persistence │ │
│ │ • Message history management │ │
│ │ • TTL for automatic cleanup │ │
│ │ • Optimistic locking for concurrent access │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Bedrock AgentCore Gateway
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Bedrock AgentCore Gateway │
│ │
│ Gateway ID: example-gateway-<random-id> │
│ Data Plane URL: https://<gateway-id>.gateway.bedrock-agentcore.│
│ <region>.amazonaws.com/mcp │
│ Execution Role: BedrockAgentCoreGatewayExecutionRole-<env │
│ Service Account: (bedrock-agentcore-control) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Bedrock AgentCore Target │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Target Configuration │ │
│ │ • Name: example-mcp-target │ │
│ │ • Type: Lambda │ │
│ │ • Status: READY │ │
│ │ • Tool Count: 20 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Authentication │ │
│ │ • JWT Validation (Okta) │ │
│ │ • Audience: api://default │ │
│ │ • Discovery URL: https://dev-12345678.okta.com/oauth2/ │ │
│ │ default/.well-known/openid-configuration │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ MCP Protocol │ │
│ │ • JSON-RPC 2.0 over HTTPS │ │
│ │ • Tool discovery via list_tools │ │
│ │ • Tool invocation via execute_tool │ │
│ │ • Streaming response support │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
MCP Tool Lambda
┌─────────────────────────────────────────────────────────────────┐
│ │
│ MCP Tool Lambda │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Lambda Function Handler │ │
│ │ • Function: <environment>-bedrock-agentcore-mcp-tool │ │
│ │ • Runtime: Container (Docker) │ │
│ │ • Handler: mcp-tool-handler.lambda_handler │ │
│ │ • Architecture: x86_64 │ │
│ │ • Memory: 3008 MB (maximum for performance) │ │
│ │ • Timeout: 15 minutes (for complex operations) │ │
│ │ • Bedrock AgentCore Context Processing │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Target ID: <target-id> (docker-strands-target) │
│ ARN: arn:aws:lambda:<region>:<account-id>:function: │
│ <environment>-bedrock-agentcore-mcp-tool │
│ │
│ Credential Provider: GATEWAY_IAM_ROLE │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Docker Container │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Tool Implementation │ │
│ │ • hello_world: Basic greeting tool │ │
│ │ • get_time: Server time tool │ │
│ │ • ec2_read_operations: EC2 instance queries │ │
│ │ • s3_read_operations: S3 bucket operations │ │
│ │ • lambda_read_operations: Lambda function queries │ │
│ │ • cloudformation_read_operations: Stack queries │ │
│ │ • iam_read_operations: IAM role/policy queries │ │
│ │ • rds_read_operations: Database queries │ │
│ │ • cloudwatch_read_operations: Metrics and logs │ │
│ │ • cost_explorer_read_operations: Cost analysis │ │
│ │ • ecs_read_operations: Container queries │ │
│ │ • eks_read_operations: Kubernetes queries │ │
│ │ • sns_read_operations: Topic queries │ │
│ │ • sqs_read_operations: Queue queries │ │
│ │ • dynamodb_read_operations: Table queries │ │
│ │ • route53_read_operations: DNS queries │ │
│ │ • apigateway_read_operations: API queries │ │
│ │ • ses_read_operations: Email queries │ │
│ │ • bedrock_read_operations: Model queries │ │
│ │ • sagemaker_read_operations: ML queries │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Configuration Management │ │
│ │ • Config Source: configs/bedrock-agentcore-config.json │ │
│ │ • Environment Support: dev, gamma, prod │ │
│ │ • Endpoint Selection: production_endpoints (active) │ │
│ │ • Tool Schema: 20 AWS service tools defined │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
DynamoDB
┌─────────────────────────────────────────────────────────────────┐
│ │
│ DynamoDB Table │
│ │
│ Table Name: aws-operations-agent-conversations-<environment> │
│ Billing Mode: PAY_PER_REQUEST │
│ Capacity Mode: On-Demand │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Schema │ │
│ │ • conversation_id: String (Partition Key) │ │
│ │ • messages: List (Conversation history) │ │
│ │ • metadata: Map (Client info, timestamps) │ │
│ │ • ttl: Number (Auto-expiration) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Features │ │
│ │ • Point-in-Time Recovery: Enabled │ │
│ │ • TTL: Enabled (30 days default) │ │
│ │ • Stream: NEW_AND_OLD_IMAGES │ │
│ │ • Encryption: AWS Owned CMK │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Conversation Flow
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Conversation Flow │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ User Request │ │
│ │ • "List my EC2 instances in us-east-1" │ │
│ │ • conversation_id: "abc123" │ │
│ │ • okta_token: "eyJhbGciOiJSUzI1..." │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ AWS Operations Agent Lambda │ │
│ │ • Load conversation history from DynamoDB │ │
│ │ • Process user message with Claude + Bedrock AgentCore tools│
│ │ • Store updated conversation back to DynamoDB │ │
│ │ │ │
│ │ Conversation Object: │ │
│ │ { │ │
│ │ "conversation_id": "abc123", │ │
│ │ "messages": [ │ │
│ │ {"role": "user", "content": "List my EC2..."}, │ │
│ │ {"role": "assistant", "content": "I'll help..."} │ │
│ │ ], │ │
│ │ "session_metadata": { │ │
│ │ "client_type": "cli", │ │
│ │ "bedrock_agentcore_gateway_url": "..", │ │
│ │ "tools_available": 20 │ │
│ │ } │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Strands Agent │ │
│ │ • Analyzes user intent │ │
│ │ • Determines need for ec2_read_operations tool │ │
│ │ • Formulates natural language query │ │
│ │ • Prepares tool parameters │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ MCP Client │ │
│ │ • Connects to Bedrock AgentCore Gateway │ │
│ │ • Sends tool execution request │ │
│ │ • Includes Okta token for authentication │ │
│ │ • Receives tool execution results │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Response Generation │ │
│ │ • Combines tool results with AI reasoning │ │
│ │ • Formats response for human readability │ │
│ │ • Streams response back to client │ │
│ │ • Updates conversation history │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Authentication Flow
┌─────────────────────────────────────────────────────────────────┐
│ │
│ IAM Trust Relationships │
│ │
│ Bedrock AgentCore Service Account │
│ │ │
│ ▼ AssumeRole │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ <your-name>-bedrock-agentcore-gateway-role ││
│ │ • lambda:InvokeFunction ││
│ │ • bedrock-agentcore-test:*, bedrock-agentcore:* ││
│ │ • s3:*, logs:*, kms:* ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ InvokeFunction │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ <environment>-bedrock-agentcore-mcp-tool Lambda ││
│ │ • Resource Policy allows Gateway role ││
│ │ • Execution role trusts Lambda + Bedrock AgentCore services││
│ │ • ReadOnlyAccess policy for AWS service queries ││
│ │ • Bedrock model access for Strands Agent ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
Security Model
Authentication Layers:
- Function URL: AWS SigV4 authentication (IAM)
- Bedrock AgentCore Gateway: Okta JWT validation
- Lambda Target: Resource policy + execution role
Permission Details:
- Bedrock AgentCore Service Account (996756280381) assumes your gateway role
- Gateway role has permissions to invoke Lambda functions
- Lambda function resource policy allows the gateway role
- Lambda execution role trusts both Lambda and Bedrock AgentCore services
Data Flow Example
Example: "List my EC2 instances"
- Client → Function URL: POST /stream + AWS SigV4 + Okta token
- API Gateway → Agent Lambda: Lambda event + Authorization header
- Agent Lambda: Extract token from headers
- Agent Lambda → Bedrock AgentCore Gateway: POST /mcp + "Authorization: Bearer <okta_token>"
- Bedrock AgentCore Gateway: Validate Okta token
- Bedrock AgentCore Gateway → Lambda Target: Invoke with Bedrock AgentCore context
- Lambda Target → Bedrock AgentCore Gateway: Tool execution result
- Bedrock AgentCore Gateway → Agent Lambda: MCP response
- Agent Lambda: Process with Bedrock AI
- Agent Lambda → API Gateway: AI response with tool results
- API Gateway → Client: Streaming response
Example Tool Execution
Natural Language Query: "Show me my EC2 instances in us-east-1"
├── Client:
│ ├── Sends natural language query
│ └── Includes Okta token for authentication
├── AWS Operations Agent Lambda:
│ ├── Calls Bedrock AI to understand intent
│ ├── Identifies need for describe_ec2_instances tool
│ └── Calls Bedrock AgentCore Gateway with token
├── Bedrock AgentCore Gateway:
│ ├── Validates Okta token
│ ├── Invokes Lambda target with tool parameters
│ └── Returns results to AWS Operations Agent Lambda
├── MCP Tool Lambda:
│ ├── Executes ec2_read_operations tool
│ ├── Calls EC2 DescribeInstances API
│ ├── Formats results for human readability
│ └── Returns structured data to Gateway
├── AWS Operations Agent Lambda:
│ ├── Processes tool results with Claude
│ ├── Generates natural language response
│ └── Streams response back to client
└── Client:
└── Displays formatted instance information
Technical Reference
Endpoints
- Function URL:
https://<unique-id>.lambda-url.<region>.on.aws/ - Bedrock AgentCore Gateway (Data Plane):
https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp - Bedrock AgentCore Control Plane:
https://bedrock-agentcore-control.<region>.amazonaws.com - AWS Operations Agent Lambda:
aws-operations-agent-<environment>(invoked by Function URL) - Okta OAuth:
https://dev-09210948.okta.com/oauth2/default
Resource Names
- DynamoDB Table:
aws-operations-agent-conversations-<environment> - AWS Operations Agent Lambda:
aws-operations-agent-<environment> - MCP Tool Lambda:
<environment>-bedrock-agentcore-mcp-tool - Gateway Role:
BedrockAgentCoreGatewayExecutionRole-<environment>
Protocols
- Client ↔ API Gateway: HTTPS REST API
- API Gateway ↔ Agent Lambda: AWS Lambda Proxy Integration
- Agent Lambda ↔ Bedrock AgentCore Gateway: MCP (JSON-RPC 2.0 over HTTPS)
- Bedrock AgentCore Gateway ↔ Lambda Target: AWS Lambda Invocation
- OAuth: JWT Bearer tokens (Okta)
AWS Resources
- Account:
<your-account-id> - Region:
<your-region>(e.g., us-west-2) - Bedrock AgentCore Service Account: 996756280381 (trusted)
Configuration Template
Required Placeholders to Replace:
<api-id>: Your API Gateway ID (auto-generated)<gateway-id>: Your Bedrock AgentCore Gateway ID (e.g., 18HDCHKLHI)<target-id>: Your Gateway Target ID (e.g., L2NAO6MQLZ)<your-name>: Your name/identifier for role naming<environment>: Deployment environment (dev, staging, prod)<region>: AWS region (e.g., us-east-1)<account-id>: Your AWS account ID