Autonomous Cloud Orchestration

AWS Bedrock AgentCore

AWS Bedrock AgentCore provides a complete platform for deploying and scaling AI agents with seven core services. This skill guides you through service selection, deployment patterns, and integration workflows using AWS CLI.

AWS Documentation Requirement

CRITICAL: This skill requires AWS MCP tools for accurate, up-to-date AWS information.

Before Answering AWS Questions

1. Always verify using AWS MCP tools (if available):

• mcp__aws-mcp__aws___search_documentation or mcp__*awsdocs*__aws___search_documentation - Search AWS docs
• mcp__aws-mcp__aws___read_documentation or mcp__*awsdocs*__aws___read_documentation - Read specific pages
• mcp__aws-mcp__aws___get_regional_availability - Check service availability

2. If AWS MCP tools are unavailable:

• Guide user to configure AWS MCP: See AWS MCP Setup Guide
• Help determine which option fits their environment:
• Has uvx + AWS credentials → Full AWS MCP Server
• No Python/credentials → AWS Documentation MCP (no auth)
• If cannot determine → Ask user which option to use

When to Use This Skill

Use this skill when you need to:

• Deploy REST APIs as MCP tools for AI agents (Gateway)
• Execute agents in serverless runtime (Runtime)
• Add conversation memory to agents (Memory)
• Manage API credentials and authentication (Identity)
• Enable agents to execute code securely (Code Interpreter)
• Allow agents to interact with websites (Browser)
• Monitor and trace agent performance (Observability)

Available Services

Common Workflows

Deploying a Gateway Target

MANDATORY - READ DETAILED DOCUMENTATION: See `services/gateway/README.md` for complete Gateway setup guide including deployment strategies, troubleshooting, and IAM configuration.

Quick Workflow: 1. Upload OpenAPI schema to S3 2. (API Key auth only) Create credential provider and store API key 3. Create gateway target linking schema (and credentials if using API key) 4. Verify target status and test connectivity

Note: Credential provider is only needed for API key authentication. Lambda targets use IAM roles, and MCP servers use OAuth.

Managing Credentials

MANDATORY - READ DETAILED DOCUMENTATION: See `cross-service/credential-management.md` for unified credential management patterns across all services.

Quick Workflow: 1. Use Identity service credential providers for all API keys 2. Link providers to gateway targets via ARN references 3. Rotate credentials quarterly through credential provider updates 4. Monitor usage with CloudWatch metrics

Monitoring Agents

MANDATORY - READ DETAILED DOCUMENTATION: See `services/observability/README.md` for comprehensive monitoring setup.

Quick Workflow: 1. Enable observability for agents 2. Configure CloudWatch dashboards for metrics 3. Set up alarms for error rates and latency 4. Use X-Ray for distributed tracing

Service-Specific Documentation

For detailed documentation on each AgentCore service, see the following resources:

Gateway Service

• Overview: `services/gateway/README.md`
• Deployment Strategies: `services/gateway/deployment-strategies.md`
• Troubleshooting: `services/gateway/troubleshooting-guide.md`

Runtime, Memory, Identity, Code Interpreter, Browser, Observability

Each service has comprehensive documentation in its respective directory:

• `services/runtime/README.md`
• `services/memory/README.md`
• `services/identity/README.md`
• `services/code-interpreter/README.md`
• `services/browser/README.md`
• `services/observability/README.md`

Cross-Service Resources

For patterns and best practices that span multiple AgentCore services:

• Credential Management: `cross-service/credential-management.md` - Unified credential patterns, security practices, rotation procedures

Additional Resources

• AWS Documentation: Amazon Bedrock AgentCore
• API Reference: Bedrock AgentCore Control Plane API
• AWS CLI Reference: bedrock-agentcore-control commands

Cross-Service Credential Management

Applies to: Gateway, Runtime, Memory, Identity

Overview

Credential management is a cross-cutting concern across all AgentCore services. This guide provides unified patterns for managing API keys, tokens, and authentication credentials across the AgentCore platform.

Authentication Overview

Inbound Authorization (Who Can Access Your Services)

Gateway Options (docs):

• IAM Identity: Uses AWS IAM credentials for authorization
• JWT: Tokens from identity providers (Cognito, Microsoft Entra ID, etc.)
• No Authorization: Open access - only for production with proper security controls

Runtime Options (docs):

• IAM (SigV4): Default authentication (works automatically)
• JWT Bearer Token: Token-based auth with discovery URL and audience validation

Note: A Runtime can only use one inbound auth type (IAM or JWT), not both simultaneously.

Outbound Authorization (Accessing External Services)

Gateway Options (docs):

• OAuth 2LO: Client credentials grant (machine-to-machine)
• OAuth 3LO: Authorization code grant (user-delegated access)

Runtime Options:

• OAuth: Tokens on behalf of users via Identity Service
• API Key: Key-based authentication via Identity Service

Best Practices

✅ DO's

1. Use Identity Service: Always manage credentials through the Identity service

   # ✅ Correct - Use Identity API
   aws bedrock-agentcore-control create-api-key-credential-provider \
     --name MyCredentialProvider \
     --api-key "YOUR_API_KEY_VALUE"

2. Separate by Environment: Use different providers for different environments

   - dev-api-key-provider      # Development
   - staging-api-key-provider  # Staging
   - prod-api-key-provider     # Production

3. Rotate Regularly: Implement quarterly credential rotation

   aws bedrock-agentcore-control update-api-key-credential-provider \
     --name MyCredentialProvider \
     --api-key "NEW_API_KEY"

4. Least Privilege: Grant minimal required permissions to each credential

   # API key should only have necessary API permissions
   # IAM roles should have scoped-down policies

5. Monitor Usage: Track credential usage and set up alerts

   {
     "CloudWatch Alarms": {
       "HighErrorRate": "Alert if > 10% failed requests",
       "UnusualActivity": "Alert on usage spikes"
     }
   }

❌ DON'Ts

1. Never Hardcode: Don't embed credentials in code or configuration files

   # ❌ Bad - Hardcoded API key
   const apiKey = "sk-1234567890abcdef"

   # ✅ Good - Reference credential provider
   const credentialProvider = "MyCredentialProvider"

2. Don't Share Across Environments: Avoid using production keys in development

   # ❌ Bad - Same key everywhere
   dev:  third-party-api-key: prod-key
   prod: third-party-api-key: prod-key

   # ✅ Good - Separate keys
   dev:  third-party-api-key: dev-key
   prod: third-party-api-key: prod-key

3. Don't Commit to Git: Exclude credential files from version control

   # .gitignore
   *.env
   *.secret
   credential-*.json

4. Don't Use Long-Lived Tokens: Implement token refresh for OAuth

   # OAuth tokens should auto-refresh
   # Don't use tokens with > 30 day expiration

Multi-Service Credential Patterns

Pattern 1: Centralized Identity, Distributed Usage

┌─────────────────────────────────────┐
│  Identity Service                   │
│  - Stores ALL credentials           │
│  - Manages rotation                 │
│  - Provides audit logs              │
└──────────┬──────────────────────────┘
           │
           ├────────────┬────────────┬────────────┐
           ▼            ▼            ▼            ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ Gateway  │ │ Runtime  │ │  Memory  │ │  Other   │
    │  Uses    │ │  Uses    │ │  Uses    │ │  Uses    │
    └──────────┘ └──────────┘ └──────────┘ └──────────┘

Benefits:

• Single source of truth for all credentials
• Unified rotation and audit
• Consistent access patterns

Setup:

# 1. Create master credential in Identity
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name MasterAPICredentials \
  --api-key "YOUR_MASTER_API_KEY"

# 2. Grant access to each service
# - Gateway: can read MasterAPICredentials
# - Runtime: can read MasterAPICredentials
# - Memory: can read MasterAPICredentials

Pattern 2: Service-Specific Credentials

┌─────────────────────────────────────┐
│  Identity Service                   │
│  - Stores credentials per service   │
└──────────┬──────────────────────────┘
           │
    ┌──────┴──────┬────────┬─────────┐
    ▼             ▼        ▼         ▼
┌─────────┐ ┌─────────┐ ┌──────┐ ┌─────┐
│ Gateway │ │ Runtime │ │Memory││Other│
│  Cred   │ │  Cred   │ │ Cred ││Cred │
└─────────┘ └─────────┘ └──────┘ └─────┘

Benefits:

• Isolation between services
• Independent rotation per service
• Service-specific permissions

Setup:

# Create separate providers
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name GatewayAPICredentials \
  --api-key "YOUR_GATEWAY_API_KEY"

aws bedrock-agentcore-control create-api-key-credential-provider \
  --name RuntimeCredentials \
  --api-key "YOUR_RUNTIME_API_KEY"

Pattern 3: Tiered (Master + Service)

┌─────────────────────────────────────┐
│  Identity Service                   │
│  - Master credential                │
│  - Per-service credentials          │
└──────────┬──────────────────────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
┌─────────┐ ┌─────────────┐
│ Master  │ │   Services  │
│  Cred   │ │   - Gateway │ │
└────┬────┘ │   - Runtime │
     │      │   - Memory  │
     └──────┤   (each has │
            │ own creds)  │
            └─────────────┘

Use Cases:

• Production: Master credential for critical APIs
• Development: Service-specific credentials for testing
• Emergency: Master credential as backup

Security Best Practices

Encryption

# Use KMS for secret encryption
aws secretsmanager create-secret \
  --name MySecret \
  --kms-key-id arn:aws:kms:us-west-2:123456789012:key/12345678-abcd-ef12-3456-7890abcdef12 \
  --secret-string "my-secret-value"

Access Control

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetResourceApiKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:PrincipalTag/Service": "gateway"
        }
      }
    }
  ]
}

Audit Logging

# Enable CloudTrail for Bedrock AgentCore
aws cloudtrail create-trail \
  --name agentcore-audit \
  --s3-bucket-name agentcore-audit-logs \
  --include-global-service-events true

Rotation Strategy

Automated Rotation

# Enable automatic rotation (when supported)
aws secretsmanager rotate-secret \
  --secret-id MySecret \
  --lambda-arn arn:aws:lambda:us-west-2:123456789012:function:MyRotationFunction

# Rotation schedule (every 30 days)
aws secretsmanager rotate-secret \
  --secret-id MySecret \
  --rotation-rules AutomaticAfterDays=30

Manual Rotation Process

#!/bin/bash
# rotate-credentials.sh

echo "Step 1: Generate new credential"
NEW_KEY=$(generate-new-api-key)

echo "Step 2: Update in Identity service"
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name MyCredentialProvider \
  --api-key "$NEW_KEY"

echo "Step 3: Verify all services work"
./test-all-services.sh

echo "Step 4: Delete old credential"
# Old credential is automatically deprecated

Common Patterns

Pattern: Credential Fallback

// Try primary credential, fallback to backup
async function callWithFallback(provider: string) {
  try {
    return await callAPI(provider);
  } catch (error) {
    if (error.code === 'InvalidAPICredentials') {
      // Fallback to backup provider
      return await callAPI(`${provider}-backup`);
    }
    throw error;
  }
}

Pattern: Rate Limiting with Credential Pool

// Rotate through multiple credentials to avoid rate limits
const credentialPool = [
  'cred-1',
  'cred-2',
  'cred-3'
];

let currentIndex = 0;

function getNextCredential(): string {
  const credential = credentialPool[currentIndex];
  currentIndex = (currentIndex + 1) % credentialPool.length;
  return credential;
}

Troubleshooting Credential Issues

Issue: "Credential not found"

Diagnosis:

# Check if provider exists
aws bedrock-agentcore-control get-api-key-credential-provider \
  --name MyCredentialProvider

# Check IAM permissions
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:role/MyRole \
  --action-names bedrock-agentcore:GetResourceApiKey \
  --resource-arns arn:aws:bedrock-agentcore:us-west-2:123456789012:*

Solution: Create provider or grant IAM permissions

---

Issue: "Invalid credentials" after rotation

Diagnosis:

# Check secret value format
aws secretsmanager get-secret-value \
  --secret-id arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret

# Should be: {"apiKey": "valid-key"}

Solution: Use correct update API

aws bedrock-agentcore-control update-api-key-credential-provider \
  --name MyCredentialProvider \
  --api-key "VALID_KEY"

---

Issue: Cross-service access denied

Diagnosis:

# Check which services can access the credential
aws bedrock-agentcore-control get-api-key-credential-provider \
  --name MyCredentialProvider

# Review service IAM policies

Solution: Add cross-service access policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:GetResourceApiKey",
      "Resource": "*",
      "Condition": {
        "ArnLike": {
          "aws:PrincipalArn": [
            "arn:aws:iam::*:role/*gateway*",
            "arn:aws:iam::*:role/*runtime*"
          ]
        }
      }
    }
  ]
}

Cost Considerations

Secrets Manager Costs

• Per secret: ~$0.40/month
• Per 10,000 API calls: ~$0.05
• Cross-region replication: Additional costs

Optimization:

• Share credentials across services when possible
• Use regional replication only when necessary
• Cache credential retrieval (respect security requirements)

Identity Service Costs

• Credential provider storage: Included in Secrets Manager
• API calls: Same as Secrets Manager pricing
• Cross-account access: No additional cost

References

• [Identity Service](../services/identity/README.md): Credential provider management
• [Gateway Service](../services/gateway/README.md): Uses credentials for API authentication
• AWS Secrets Manager: Pricing
• AWS Documentation: Managing AWS Secrets Manager secrets

---

Related Guides:

• Observability Service
• AWS AgentCore Identity Documentation

AgentCore Browser Service

Status: ✅ Available

Overview

Amazon Bedrock AgentCore Browser provides a fast, secure, cloud-based browser runtime enabling AI agents to interact with websites at scale without infrastructure management.

Core Capabilities

Cloud-Based Runtime

• Fast Execution: High-performance browser instances with minimal latency
• Auto Scaling: Automatic scaling based on demand without configuration
• Zero Infrastructure: No servers or containers to manage
• Multi-Region: Deploy browser instances across AWS regions globally

Security and Compliance

• Enterprise Security: Industry-standard security controls and encryption
• Isolated Sessions: Each browsing session runs in complete isolation
• Data Protection: Secure data handling and privacy controls
• Compliance Ready: Meets enterprise compliance requirements (SOC, HIPAA, GDPR)

Web Interaction Capabilities

• Full Automation: Complete browser automation capabilities
• JavaScript Support: Execute JavaScript in browser context
• Form Interaction: Fill forms, click buttons, navigate pages
• Content Extraction: Extract text, data, and media from pages
• Session Management: Handle cookies, local storage, and sessions
• Screenshot Capture: Take screenshots of pages and elements

Observability

• Execution Logging: Comprehensive logs of browser actions
• Performance Metrics: Track page load times and operation latency
• Error Tracking: Detailed error capture and debugging information
• Request Monitoring: Monitor network requests and responses

Use Cases

Web Scraping and Data Extraction

Enable agents to:

• Extract data from websites at scale
• Scrape content from dynamic pages
• Collect structured data from multiple sources
• Monitor website changes over time

Automated Testing and QA

Support scenarios like:

• Automated UI testing of web applications
• Regression testing for web features
• Cross-browser compatibility testing
• Performance testing and monitoring

Form Filling and Workflow Automation

Allow agents to:

• Automate form submissions
• Complete multi-step workflows
• Handle authentication and logins
• Process batch operations on web interfaces

Real-Time Monitoring

Enable agents to:

• Monitor website availability and uptime
• Track content changes and updates
• Verify website functionality
• Gather competitive intelligence

Content Verification

Support tasks like:

• Validate web content accuracy
• Check link integrity
• Verify page rendering
• Test responsive designs

Architecture

Browser Execution Flow

Agent Request
    ↓
┌─────────────────────────────────────────┐
│  Browser Service API                    │
│  - Parse browser action request         │
│  - Validate parameters                  │
│  - Allocate browser instance            │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Browser Instance                       │
│  - Navigate to URL                      │
│  - Execute JavaScript                   │
│  - Interact with page elements          │
│  - Extract content and data             │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Result Processing                      │
│  - Package extracted data               │
│  - Capture screenshots (if requested)   │
│  - Log execution details                │
│  - Return results to agent              │
└─────────────────────────────────────────┘

Security Architecture

1. Session Isolation: Each browser session runs in isolated environment 2. Network Security: Controlled outbound internet access 3. Data Encryption: All data encrypted in transit and at rest 4. Resource Limits: CPU, memory, and time limits per session 5. Access Control: IAM-based authentication and authorization

Configuration

Basic Browser Session

# Configure browser service for agent
aws bedrock-agentcore-control configure-browser \
  --agent-id <AGENT_ID> \
  --session-timeout 600 \
  --viewport-width 1920 \
  --viewport-height 1080 \
  --region <REGION>

Advanced Configuration

# Set browser preferences and capabilities
aws bedrock-agentcore-control update-browser-config \
  --agent-id <AGENT_ID> \
  --browser-config '{
    "headless": true,
    "javascript": true,
    "images": true,
    "cookies": true,
    "userAgent": "CustomUserAgent/1.0",
    "timeout": 30000
  }' \
  --region <REGION>

Browser Actions

Navigation

// Navigate to URL
{
  "action": "navigate",
  "url": "https://example.com"
}

// Go back
{
  "action": "goBack"
}

// Refresh page
{
  "action": "reload"
}

Element Interaction

// Click element
{
  "action": "click",
  "selector": "#submit-button"
}

// Fill input field
{
  "action": "type",
  "selector": "#username",
  "text": "user@example.com"
}

// Select option
{
  "action": "select",
  "selector": "#country",
  "value": "US"
}

Content Extraction

// Extract text
{
  "action": "getText",
  "selector": ".article-content"
}

// Get element attribute
{
  "action": "getAttribute",
  "selector": "img.logo",
  "attribute": "src"
}

// Evaluate JavaScript
{
  "action": "evaluate",
  "script": "return document.title;"
}

Screenshots

// Full page screenshot
{
  "action": "screenshot",
  "fullPage": true
}

// Element screenshot
{
  "action": "screenshot",
  "selector": "#chart-container"
}

Best Practices

Performance Optimization

• Use headless mode for non-visual operations
• Disable unnecessary resources (images, stylesheets)
• Set appropriate timeouts for page loads
• Reuse browser sessions when possible
• Implement exponential backoff for retries

Reliability

• Handle network failures gracefully
• Implement proper error handling
• Use explicit waits for dynamic content
• Verify element existence before interaction
• Set reasonable timeout values

Security

• Validate all URLs before navigation
• Sanitize extracted data
• Use secure credential storage
• Implement rate limiting
• Monitor for suspicious patterns

Cost Optimization

• Close browser sessions when done
• Use session pooling for frequent operations
• Set appropriate resource limits
• Monitor usage patterns
• Implement caching where appropriate

Integration Patterns

With Memory Service

Browser ←→ Memory Service
- Store extracted data in memory
- Cache frequently accessed pages
- Share session state across agents

With Identity Service

Browser ←→ Identity Service
- Authenticate browser sessions
- Access credentials for protected sites
- Manage authentication tokens

With Code Interpreter

Browser ←→ Code Interpreter
- Process scraped data with code
- Transform extracted content
- Analyze website data

Troubleshooting

Common Issues

Page Load Timeout

• Symptom: Page takes too long to load
• Solution: Increase timeout or optimize target page

Element Not Found

• Symptom: Cannot locate page element
• Solution: Use explicit waits or verify selector

JavaScript Errors

• Symptom: Page JavaScript fails
• Solution: Check console logs, handle errors

Session Terminated

• Symptom: Browser session unexpectedly ends
• Solution: Check resource limits and session timeout

Authentication Required

• Symptom: Cannot access protected pages
• Solution: Configure credentials via Identity service

Monitoring

Key Metrics

• Session Count: Number of active browser sessions
• Success Rate: Percentage of successful operations
• Page Load Time: Average time to load pages
• Error Rate: Percentage of failed operations
• Resource Usage: CPU and memory utilization

CloudWatch Integration

# Query browser metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/BedrockAgentCore/Browser \
  --metric-name SessionCount \
  --dimensions Name=AgentId,Value=<AGENT_ID> \
  --start-time <START> \
  --end-time <END> \
  --period 3600 \
  --statistics Average

Logging

# View browser execution logs
aws logs tail /aws/bedrock-agentcore/browser/<AGENT_ID> \
  --follow \
  --format short

Performance Considerations

Optimization Techniques

1. Disable Unnecessary Resources: Turn off images/stylesheets when not needed 2. Use Headless Mode: Faster execution without rendering overhead 3. Implement Caching: Cache static resources and repeated queries 4. Parallel Execution: Run multiple browser sessions concurrently 5. Smart Waiting: Use explicit waits instead of fixed delays

Scaling Patterns

• Horizontal Scaling: Launch multiple browser instances
• Session Pooling: Reuse browser sessions for efficiency
• Request Queuing: Queue browser operations during high load
• Regional Distribution: Distribute load across AWS regions

Additional Resources

• AWS Documentation: Bedrock AgentCore Browser
• Best Practices: Browser Automation Guide
• API Reference: Browser API
• Selector Reference: CSS Selectors

---

Related Services:

• Runtime Service - Agent execution
• Code Interpreter - Data processing
• Memory Service - State management
• Observability Service - Monitoring

AgentCore Code Interpreter Service

Status: ✅ Available

Overview

Amazon Bedrock AgentCore Code Interpreter enables agents to securely execute code in isolated sandbox environments, supporting complex data analysis workflows and computational tasks.

Core Capabilities

Secure Execution

• Isolated Sandboxes: Each code execution runs in a completely isolated environment
• No Cross-Contamination: Sessions are independent with no shared state
• Enterprise Security: Meets enterprise security and compliance requirements
• Resource Controls: Configurable limits and timeout controls for execution

Framework Integration

• Popular Frameworks: Seamless integration with LangGraph, CrewAI, Strands, and other agent frameworks
• Multi-Language Support: Execute code in Python, JavaScript, and other languages
• Advanced Configuration: Extensive customization options for runtime environments
• Custom Runtimes: Support for specialized runtime configurations

Data Processing

• File Operations: Upload and download files for processing
• Multi-Modal Data: Handle structured and unstructured data
• Result Formatting: Format and visualize execution results
• Error Handling: Comprehensive error reporting and debugging support

Use Cases

Data Analysis and Transformation

Enable agents to:

• Process and analyze datasets
• Transform data formats
• Perform statistical calculations
• Generate data insights

Complex Computational Workflows

Support scenarios like:

• Running scientific computations
• Executing business logic calculations
• Processing batch operations
• Performing iterative algorithms

Visualization and Reporting

Allow agents to:

• Generate charts and graphs
• Create formatted reports
• Build visualizations from data
• Export results in various formats

Dynamic Code Testing

Enable agents to:

• Test code snippets dynamically
• Validate logic and algorithms
• Debug code execution issues
• Prototype solutions quickly

Architecture

Execution Flow

Agent Request
    ↓
┌─────────────────────────────────────────┐
│  Code Interpreter Service               │
│  - Parse code execution request         │
│  - Validate code and parameters         │
│  - Allocate isolated sandbox            │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Sandbox Environment                    │
│  - Execute code in isolation            │
│  - Process data and files               │
│  - Generate outputs                     │
│  - Capture errors and logs              │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Result Processing                      │
│  - Format execution results             │
│  - Package outputs and artifacts        │
│  - Return to agent                      │
└─────────────────────────────────────────┘

Security Model

1. Sandbox Isolation: Each execution runs in a completely isolated environment 2. Resource Limits: CPU, memory, and time limits prevent resource exhaustion 3. Network Restrictions: Controlled network access from sandbox environments 4. Data Encryption: Data at rest and in transit is encrypted 5. Audit Logging: All code executions are logged for compliance

Configuration

Basic Setup

# Configure code interpreter for agent
aws bedrock-agentcore-control configure-code-interpreter \
  --agent-id <AGENT_ID> \
  --execution-timeout 300 \
  --memory-limit 2048 \
  --region <REGION>

Custom Runtime Configuration

# Set custom runtime environment
aws bedrock-agentcore-control update-code-interpreter-runtime \
  --agent-id <AGENT_ID> \
  --runtime-config '{
    "language": "python3.11",
    "packages": ["pandas", "numpy", "matplotlib"],
    "environment": {
      "CUSTOM_VAR": "value"
    }
  }' \
  --region <REGION>

Best Practices

Code Security

• Validate all code inputs before execution
• Implement input sanitization for user-provided code
• Use resource limits to prevent denial of service
• Monitor code execution patterns for anomalies

Performance Optimization

• Cache common dependencies in runtime images
• Use appropriate timeout values for expected workload
• Optimize code for execution within timeout limits
• Batch similar operations when possible

Error Handling

• Implement comprehensive error catching in code
• Provide clear error messages for debugging
• Log execution details for troubleshooting
• Use structured output formats for results

Data Management

• Minimize data transfer in and out of sandboxes
• Use streaming for large data processing
• Clean up temporary files after execution
• Implement data validation before processing

Integration Patterns

With Memory Service

Code Interpreter ←→ Memory Service
- Store execution results in memory
- Retrieve past computation results
- Share data across agent sessions

With Identity Service

Code Interpreter ←→ Identity Service
- Authenticate code execution requests
- Access credentials for external APIs
- Manage permissions for data access

With Observability Service

Code Interpreter ←→ Observability Service
- Trace code execution workflows
- Monitor performance metrics
- Log execution events
- Alert on execution failures

Troubleshooting

Common Issues

Execution Timeout

• Symptom: Code execution exceeds timeout limit
• Solution: Increase timeout or optimize code performance

Memory Limit Exceeded

• Symptom: Code runs out of memory
• Solution: Increase memory limit or process data in chunks

Package Import Errors

• Symptom: Required packages not found
• Solution: Configure custom runtime with needed packages

Permission Denied

• Symptom: Cannot access required resources
• Solution: Configure IAM permissions for code interpreter

Monitoring

Key Metrics

• Execution Count: Number of code executions
• Success Rate: Percentage of successful executions
• Average Duration: Mean execution time
• Error Rate: Percentage of failed executions
• Resource Utilization: CPU and memory usage

CloudWatch Integration

# Query execution metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/BedrockAgentCore/CodeInterpreter \
  --metric-name ExecutionCount \
  --dimensions Name=AgentId,Value=<AGENT_ID> \
  --start-time <START> \
  --end-time <END> \
  --period 3600 \
  --statistics Sum

Additional Resources

• AWS Documentation: Bedrock AgentCore Code Interpreter
• Security Best Practices: Secure Code Execution
• API Reference: Code Interpreter API

---

Related Services:

• Runtime Service - Agent execution environment
• Memory Service - State management
• Observability Service - Monitoring and tracing

AgentCore Gateway Deployment Strategies

Overview

This reference guide covers different deployment strategies for AWS Bedrock AgentCore Gateway targets, including credential management approaches, multi-environment patterns, and rollback procedures.

Credential Provider Strategies

Strategy 1: Shared Provider (Recommended for Most Cases)

Concept: Create ONE credential provider and share across all gateway targets

Setup:

# Create shared provider with API key (run once)
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name SharedAPICredentialProvider \
  --api-key "YOUR_API_KEY" \
  --profile default --region us-west-2

Environment Configuration:

# .env.gateway-a
GATEWAY_IDENTIFIER=gateway-a-abc123xyz
CREDENTIAL_PROVIDER_NAME=SharedAPICredentialProvider  # Same for all

# .env.gateway-b
GATEWAY_IDENTIFIER=gateway-b-def456uvw
CREDENTIAL_PROVIDER_NAME=SharedAPICredentialProvider  # Same for all

Benefits:

• ✅ Simplified key management - single key to rotate
• ✅ Reduced operational overhead
• ✅ Consistent authentication across all gateways
• ✅ Easier compliance and auditing

Use Cases:

• Same API, multiple gateway deployments
• Development/Testing/Production gateways
• Regional deployments (us-west-2, eu-west-1)

Trade-offs:

• Less isolation between gateways (all or nothing key rotation)

Strategy 2: Isolated Provider (Per-Gateway)

Concept: Create UNIQUE credential provider for each gateway

Setup:

# Create provider for Gateway A
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name GatewayAAPICredentialProvider \
  --api-key "API_KEY_A" \
  --profile default --region us-west-2

# Create provider for Gateway B
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name GatewayBAPICredentialProvider \
  --api-key "API_KEY_B" \
  --profile default --region us-west-2

Environment Configuration:

# .env.gateway-a
GATEWAY_IDENTIFIER=gateway-a-abc123xyz
CREDENTIAL_PROVIDER_NAME=GatewayAAPICredentialProvider  # Unique

# .env.gateway-b
GATEWAY_IDENTIFIER=gateway-b-def456uvw
CREDENTIAL_PROVIDER_NAME=GatewayBAPICredentialProvider  # Unique

Benefits:

• ✅ Complete isolation between gateways
• ✅ Independent key rotation per environment
• ✅ Different API keys for different use cases
• ✅ Better security boundaries

Use Cases:

• Production vs Development with different API keys
• Different APIs for different gateways
• Compliance requiring environment separation
• Testing new API versions in isolation

Trade-offs:

• More complex key management
• Multiple keys to rotate and maintain

Strategy 3: Tiered (Shared + Isolated)

Concept: Hybrid approach with shared provider for non-prod, isolated for production

Setup:

# Shared provider for dev/test
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name DevTestAPICredentialProvider \
  --api-key "DEV_TEST_API_KEY" \
  --profile default --region us-west-2

# Isolated provider for production
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name ProdAPICredentialProvider \
  --api-key "PROD_API_KEY" \
  --profile default --region us-west-2

Environment Configuration:

# .env.development
GATEWAY_IDENTIFIER=dev-gateway-abc123xyz
CREDENTIAL_PROVIDER_NAME=DevTestAPICredentialProvider

# .env.staging
GATEWAY_IDENTIFIER=staging-gateway-def456uvw
CREDENTIAL_PROVIDER_NAME=DevTestAPICredentialProvider

# .env.production
GATEWAY_IDENTIFIER=prod-gateway-ghi789rst
CREDENTIAL_PROVIDER_NAME=ProdAPICredentialProvider

Benefits:

• ✅ Balance of simplicity and security
• ✅ Production isolation with dev/test convenience
• ✅ Easier testing in non-prod environments
• ✅ Production key remains protected

Use Cases:

• Most common enterprise pattern
• Clear separation between environments
• Controlled production access

Multi-Account Deployment

When deploying across multiple AWS accounts:

Setup

1. Credential Provider per Account:

   # Account 1 (Dev)
   aws bedrock-agentcore-control create-api-key-credential-provider \
     --name APICredentialProvider \
     --api-key "DEV_API_KEY" \
     --profile dev-account

   # Account 2 (Prod)
   aws bedrock-agentcore-control create-api-key-credential-provider \
     --name APICredentialProvider \
     --api-key "PROD_API_KEY" \
     --profile prod-account

2. Centralized Configuration:

   # .env.dev
   ACCOUNT_ID=123456789012
   GATEWAY_IDENTIFIER=dev-gateway-abc123xyz
   AWS_PROFILE=dev-account

   # .env.prod
   ACCOUNT_ID=987654321098
   GATEWAY_IDENTIFIER=prod-gateway-abc123xyz
   AWS_PROFILE=prod-account

3. Cross-Account Deployment Script:

   #!/bin/bash
   ENV_FILE=$1

   # Load environment
   export $(cat $ENV_FILE | xargs)

   # Get AWS account ID
   export CDK_DEFAULT_ACCOUNT=$(aws sts get-caller-identity \
     --profile $AWS_PROFILE \
     --query Account --output text)

   # Deploy
   npm run build && cdk deploy --profile $AWS_PROFILE --require-approval never

Key Rotation Procedures

Shared Provider Strategy

Manual Rotation:

# 1. Update key in provider
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name SharedAPICredentialProvider \
  --api-key "NEW_API_KEY" \
  --profile default --region us-west-2

# 2. Restart gateway targets (if needed) to pick up new key

Automated Rotation:

• Use AWS Secrets Manager rotation (if supported by credential provider)
• Triggered by CloudWatch Events schedule
• Lambda function handles key generation/update

Isolated Provider Strategy

Per-Gateway Rotation:

# Rotate dev environment only
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name DevAPICredentialProvider \
  --api-key "NEW_DEV_KEY"

# Production remains unchanged
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name ProdAPICredentialProvider \
  --api-key "EXISTING_PROD_KEY"

Rollback Procedures

Rollback Failed Deployment

# List CloudFormation stacks
aws cloudformation list-stacks --stack-status-filter UPDATE_ROLLBACK_FAILED

# Get previous stack configuration
aws cloudformation describe-stack-resources --stack-name StackName

# Rollback to previous version
aws cloudformation continue-update-rollback --stack-name StackName

Rollback Credential Changes

# If new API key is causing issues, restore previous key
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name APICredentialProvider \
  --api-key "PREVIOUS_WORKING_KEY"

Monitoring and Alerting

CloudWatch Metrics to Monitor

• Gateway Target Status: Monitor target health
• API Request Count: Track usage per gateway
• Error Rates: 4xx and 5xx errors
• Latency: P95, P99 response times
• Credential Provider Errors: Secret access failures

CloudWatch Alarms

// CDK Example: Create alarm for high error rate
new cloudwatch.Alarm(this, 'HighErrorRate', {
  metric: new cloudwatch.Metric({
    namespace: 'AWS/BedrockAgentCore',
    metricName: 'TargetErrorRate',
    dimensionsMap: {
      GatewayId: gatewayId,
      TargetId: targetId,
    },
    statistic: 'avg',
    period: Duration.minutes(5),
  }),
  threshold: 10,
  evaluationPeriods: 2,
  datapointsToAlarm: 2,
  comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
  alarmDescription: 'Error rate exceeds 10%',
  actionsEnabled: true,
});

Cost Optimization

Cost Considerations

1. AgentCore Gateway: Pay per tool invocation

• Optimize schema to reduce unnecessary API calls
• Cache frequently accessed data in schema descriptions
• Use batch operations where available

2. S3 Asset Storage: Negligible (<$0.01/month)

• Schema files are small
• CDK automatically cleans up old versions

3. Lambda (GatewayRoleUpdater): ~$0.01 per deployment

• Covered by AWS Lambda free tier (1M requests/month)
• Only runs during deployment/update

4. Secrets Manager: ~$0.40/month per secret

• Use shared provider to minimize secret count
• Rotate secrets on schedule to maintain security

5. API Calls (RapidAPI Example):

• Free tier: 100 requests/day
• Paid tiers: From $10/month
• Optimize by embedding IDs in schema

Optimization Strategies

Schema Optimization:

# Embed common IDs to reduce API calls by 50%
info:
  description: |
    COMMON LEAGUE IDs:
    - Premier League: 39
    - Champions League: 2
    - World Cup: 1

Credential Provider Sharing:

• Single provider for all gateways = 1 secret = $0.40/month
• Separate providers = N secrets = $0.40N/month

Security Best Practices

Credential Management

• Never commit API keys to source control
• Use AWS Secrets Manager via credential providers
• Rotate keys regularly (quarterly minimum)
• Use different keys for different environments

IAM Permissions

• Custom Resource Lambda has scoped permissions
• Only allows access to Gateway service roles
• Follows principle of least privilege
• Audit policy versions regularly

Network Security

• Ensure Gateway is in VPC if required
• Use AWS PrivateLink for on-premises integrations
• Enable encryption in transit (TLS 1.2+)
• Verify API endpoints use HTTPS

Common Patterns

Pattern 1: Development Pipeline

# Branch-based deployment
if [ "$BRANCH" = "main" ]; then
  ./deploy.sh .env.production
elif [ "$BRANCH" = "develop" ]; then
  ./deploy.sh .env.staging
else
  ./deploy.sh .env.development
fi

Pattern 2: Regional Deployment

# Deploy to multiple regions
for region in us-west-2 eu-west-1 ap-southeast-1; do
  export AWS_REGION=$region
  export GATEWAY_IDENTIFIER="my-gateway-${region}"
  npm run build && cdk deploy --require-approval never
done

Pattern 3: Blue-Green Deployment

# Deploy to blue environment
./deploy.sh .env.blue

# Test blue environment
./test-target.sh blue

# Switch to green if blue is healthy
./deploy.sh .env.green

Migration Strategies

Migrating from Manual to CDK Management

1. Discovery Phase:

   # Document existing targets
   aws bedrock-agentcore-control list-gateway-targets \
     --gateway-identifier existing-gateway \
     --profile default --region us-west-2

2. Schema Extraction:

• Export existing OpenAPI schemas
• Audit and optimize schema descriptions
• Embed common IDs for performance

3. CDK Implementation:

• Create stack with existing target configuration
• Import existing credential provider
• Add GatewayRoleUpdater for IAM automation

4. Cutover:

• Deploy to new gateway first (test)
• Update AI agents to use new target
• Decommission old target after verification

Additional References

• Main Skill Documentation: `../../SKILL.md`
• Troubleshooting Guide: `./troubleshooting-guide.md`
• Deployment Template Script: `./deploy-template.sh`
• Credential Management: `../../cross-service/credential-management.md`

Gateway Service

The Gateway service converts REST APIs into MCP tools that AI agents can use. It handles authentication, schema validation, and request routing.

Quick Start

Prerequisites

• AWS CLI configured with appropriate permissions
• An existing Gateway (created via AWS Console or CLI)
• OpenAPI schema for your target API

Deploy a Gateway Target

Step 1: Upload OpenAPI schema to S3

aws s3 cp my-api-openapi.yaml s3://<BUCKET_NAME>/schemas/

Step 2: Create credential provider (API Key auth only)

aws bedrock-agentcore-control create-api-key-credential-provider \
  --name MyAPICredentialProvider \
  --api-key "YOUR_API_KEY" \
  --region us-west-2

Step 3: Create gateway target

aws bedrock-agentcore-control create-gateway-target \
  --gateway-identifier <GATEWAY_ID> \
  --name MyAPITarget \
  --endpoint-configuration '{"openApiSchema": {"s3": {"uri": "s3://<BUCKET_NAME>/schemas/my-api-openapi.yaml"}}}' \
  --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_API_KEY_CREDENTIAL_PROVIDER", "apiKeyCredentialProvider": {"providerArn": "arn:aws:bedrock-agentcore:us-west-2:<ACCOUNT_ID>:api-key-credential-provider/MyAPICredentialProvider"}}]' \
  --region us-west-2

Step 4: Verify deployment

aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier <GATEWAY_ID> \
  --target-identifier <TARGET_ID> \
  --region us-west-2

Authentication Options

Outbound (Accessing External APIs)

Inbound (Who Can Invoke Tools)

• IAM: AWS IAM credentials
• JWT: Tokens from identity providers (Cognito, Entra ID)
• No Auth: Open access (use with caution)

Documentation

Common Operations

List Gateway Targets

aws bedrock-agentcore-control list-gateway-targets \
  --gateway-identifier <GATEWAY_ID> \
  --region us-west-2

Update Credential Provider

aws bedrock-agentcore-control update-api-key-credential-provider \
  --name MyAPICredentialProvider \
  --api-key "NEW_API_KEY" \
  --region us-west-2

Delete Gateway Target

aws bedrock-agentcore-control delete-gateway-target \
  --gateway-identifier <GATEWAY_ID> \
  --target-identifier <TARGET_ID> \
  --region us-west-2

Related Resources

• Cross-Service Credential Management
• AWS Gateway Documentation
• Bedrock AgentCore CLI Reference

AgentCore Gateway Troubleshooting Guide

Quick Diagnosis

Symptom: Target Creation Fails

Error Message: "Gateway target creation failed"

Diagnosis Steps: 1. Verify gateway exists

   aws bedrock-agentcore-control get-gateway \
     --gateway-identifier <GATEWAY_ID> \
     --profile default --region us-west-2

2. Check credential provider exists (if using API key auth)

   aws bedrock-agentcore-control get-api-key-credential-provider \
     --name <PROVIDER_NAME> \
     --profile default --region us-west-2

3. List existing targets

   aws bedrock-agentcore-control list-gateway-targets \
     --gateway-identifier <GATEWAY_ID> \
     --profile default --region us-west-2

Common Causes:

• Gateway ID incorrect or gateway doesn't exist
• Credential provider name misspelled (for API key auth)
• OpenAPI schema syntax error
• S3 bucket permissions issue for schema

---

Permission Errors

Error: "User is not authorized to perform: bedrock-agentcore:GetResourceApiKey"

Full Error:

User: arn:aws:sts::<ACCOUNT_ID>:assumed-role/GatewayServiceRole is not
authorized to perform: bedrock-agentcore:GetResourceApiKey on resource: *

Root Cause: Gateway service role missing credential provider access permissions

Diagnosis:

# Get gateway role ARN
GATEWAY_ROLE=$(aws bedrock-agentcore-control get-gateway \
  --gateway-identifier <GATEWAY_ID> \
  --query 'roleArn' --output text \
  --profile default --region us-west-2)

echo $GATEWAY_ROLE

# Extract role name
ROLE_NAME=$(echo $GATEWAY_ROLE | cut -d'/' -f2)

# Check attached policies
aws iam list-attached-role-policies \
  --role-name $ROLE_NAME \
  --profile default --region us-west-2

Solution: Add required permissions to gateway role:

cat > /tmp/gateway-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetResourceApiKey",
      "Effect": "Allow",
      "Action": ["bedrock-agentcore:GetResourceApiKey"],
      "Resource": "*"
    },
    {
      "Sid": "GetWorkloadAccessToken",
      "Effect": "Allow",
      "Action": ["bedrock-agentcore:GetWorkloadAccessToken"],
      "Resource": "*"
    },
    {
      "Sid": "GetCredentials",
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": ["arn:aws:secretsmanager:us-west-2:<ACCOUNT_ID>:secret:bedrock-agentcore-identity!*"]
    }
  ]
}
EOF

# Get policy ARN from role
POLICY_ARN=$(aws iam list-attached-role-policies \
  --role-name $ROLE_NAME \
  --query 'AttachedPolicies[0].PolicyArn' \
  --output text \
  --profile default --region us-west-2)

# Create new policy version
aws iam create-policy-version \
  --policy-arn $POLICY_ARN \
  --policy-document file:///tmp/gateway-policy.json \
  --set-as-default \
  --profile default --region us-west-2

---

Error: "AccessDeniedException: Secrets Manager"

Full Error:

AccessDeniedException: User: arn:aws:sts::<ACCOUNT_ID>:assumed-role/GatewayServiceRole
is not authorized to perform: secretsmanager:GetSecretValue on resource: ...

Root Cause: Gateway cannot access Secrets Manager for credential provider

Solution: Add secretsmanager:GetSecretValue permission to gateway role (see above)

---

Credential Provider Issues

Error: "Credential provider not found"

Diagnosis:

# Check if provider exists
aws bedrock-agentcore-control get-api-key-credential-provider \
  --name <PROVIDER_NAME> \
  --profile default --region us-west-2

# List all providers
aws bedrock-agentcore-control list-api-key-credential-providers \
  --profile default --region us-west-2

Solution:

# Create provider if missing
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name <PROVIDER_NAME> \
  --api-key "YOUR_API_KEY" \
  --profile default --region us-west-2

---

Error: "Invalid API key"

Symptom: API calls return 403 or authentication errors

Diagnosis:

# Check API key format in secret
SECRET=$(aws secretsmanager get-secret-value \
  --secret-id "arn:aws:secretsmanager:us-west-2:<ACCOUNT_ID>:secret:bedrock-agentcore-identity/default/apikeycredentialprovider/<PROVIDER_NAME>-AbCdEf" \
  --query 'SecretString' --output text \
  --profile default --region us-west-2)

echo $SECRET | jq '.'
# Should be: {"apiKey": "your-key-here"}

Solution:

# Use the correct update command (not secretsmanager put-secret-value)
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name <PROVIDER_NAME> \
  --api-key "YOUR_VALID_API_KEY" \
  --profile default --region us-west-2

Common Mistake: Using secretsmanager put-secret-value directly bypasses credential provider validation

---

OpenAPI Schema Issues

Error: "Invalid OpenAPI schema"

Diagnosis:

# Validate OpenAPI schema locally
npm install -g @apidevtools/swagger-cli
swagger-cli validate schemas/my-api-openapi.yaml

# Check for unsupported constructs
grep -n "oneOf\|anyOf\|allOf" schemas/my-api-openapi.yaml
# These constructs are not supported in Gateway

Common Issues: 1. oneOf/anyOf/allOf: Not supported, use simple types 2. Missing operationId: All operations must have operationId 3. Invalid $ref references: Must point to valid components 4. YAML syntax errors: Use online YAML validator

Solution: Use OpenAPI 3.0 simple types only:

# ❌ Bad - unsupported
schema:
  oneOf:
    - type: string
    - type: number

# ✅ Good - simple type
schema:
  type: string

---

Error: "Schema size exceeds limit"

Root Cause: OpenAPI schema too large for Gateway

Solutions: 1. Remove unused endpoints from schema 2. Simplify descriptions (keep essential info only) 3. Remove redundant component definitions 4. Split into multiple targets if necessary

---

API Call Issues

Error: "Rate limit exceeded"

Symptom: API calls return 429 Too Many Requests

Root Cause: Gateway or upstream API rate limits

Diagnosis:

# Check gateway target status
aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier <GATEWAY_ID> \
  --target-identifier <TARGET_ID> \
  --profile default --region us-west-2

Solutions: 1. Check Gateway limits: Verify gateway quota in AWS Console 2. Upstream API limits: Check your API provider dashboard for limits 3. Optimize calls: Use embedded IDs in schema to reduce API queries 4. Implement caching: Cache responses when possible 5. Request limit increase: Contact AWS support if needed

---

Error: "Invalid API host header"

Root Cause: API endpoint or host header configuration mismatch

Diagnosis:

# Check schema for correct server URL
grep -A5 "servers:" schemas/my-api-openapi.yaml

# Verify host header in security scheme
grep -A10 "securitySchemes:" schemas/my-api-openapi.yaml

Solution: Update OpenAPI schema with correct server URL and host header

---

Error: "Connection timeout"

Symptom: Gateway target calls fail with timeout errors

Root Cause: Upstream API not responding within timeout limit

Solutions: 1. Verify upstream API is accessible 2. Check network connectivity from Gateway 3. Increase timeout in target configuration (if supported) 4. Check if upstream API requires VPC configuration

---

Target Status Issues

Target Status: "FAILED"

Diagnosis:

# Get target details including status reason
aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier <GATEWAY_ID> \
  --target-identifier <TARGET_ID> \
  --query '{status: status, statusReason: statusReason}' \
  --profile default --region us-west-2

Common Status Reasons:

• SCHEMA_VALIDATION_FAILED: OpenAPI schema has errors
• CREDENTIAL_PROVIDER_NOT_FOUND: API key provider doesn't exist
• PERMISSION_DENIED: IAM permissions missing

---

Target Status: "PENDING" for too long

Root Cause: Target creation stuck

Solutions: 1. Check if all dependencies exist (gateway, credential provider) 2. Delete and recreate target 3. Check AWS service health dashboard

---

Testing and Verification

How to Test Target Deployment

#!/bin/bash
# test-target.sh

GATEWAY_ID=$1
TARGET_ID=$2

# Test 1: List targets
echo "Listing gateway targets..."
aws bedrock-agentcore-control list-gateway-targets \
  --gateway-identifier $GATEWAY_ID \
  --profile default --region us-west-2

# Test 2: Get target details
echo "Getting target details..."
aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier $GATEWAY_ID \
  --target-identifier $TARGET_ID \
  --profile default --region us-west-2

# Test 3: Get tools from target
echo "Getting tools..."
aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier $GATEWAY_ID \
  --target-identifier $TARGET_ID \
  --query 'tools' \
  --profile default --region us-west-2

---

Common Error Summary Table

---

Escalation Path

If issues persist after troubleshooting:

1. Check AWS Documentation: https://docs.aws.amazon.com/bedrock-agentcore/ 2. AWS Support: Open case with Bedrock AgentCore service 3. Community: AWS Developer Forums

Information to gather for AWS Support:

• Gateway ID and target ID
• Error messages and timestamps
• OpenAPI schema (sanitized)
• IAM role and policy configuration

AgentCore Identity Service

Status: ✅ Available

Overview

Amazon Bedrock AgentCore Identity is an identity and credential management service designed specifically for AI agents and automated workloads. It provides secure authentication, authorization, and credential management capabilities that enable agents and tools to access AWS resources and third-party services on behalf of users while maintaining strict security controls and audit trails.

Core Capabilities

Centralized Agent Identity Management

• Workload Identities: Agent identities implemented as workload identities with specialized attributes
• Unified Directory: Create, manage, and organize agent identities through unified directory service
• Hierarchical Organization: Group-based access controls and hierarchical organization
• Cross-Environment: Consistent identity management regardless of deployment location

Secure Credential Storage

• Token Vault: Securely store OAuth 2.0 tokens, client credentials, and API keys
• Encryption: Comprehensive encryption at rest and in transit
• Access Controls: Strict access controls with independent request validation
• Defense-in-Depth: Protects end-user data from malicious or misbehaving agent code

OAuth 2.0 Flow Support

• Client Credentials Grant: Machine-to-machine authentication (2LO)
• Authorization Code Grant: User-delegated access (3LO)
• Built-in Providers: Pre-configured providers for Google, GitHub, Slack, Salesforce
• Custom Providers: Configurable OAuth 2.0 credential providers for custom integrations

Credential Provider Management

• API Key Providers: Securely store and manage API keys
• OAuth Credential Providers: Handle OAuth flow and token management
• Token Lifecycle: Automatic token refresh and expiration handling
• Provider Discovery: Automatically discover available credential providers

Agent Identity and Access Controls

• Impersonation Flow: Agents access resources using provided credentials
• Audit Trails: Maintain audit trails for all actions performed on behalf of users
• Request Verification: Token signature verification, expiration checks, scope validation
• Identity-Aware Authorization: Pass user context to agent code for dynamic decisions

Use Cases

Securing AI Agent Access

Enable agents to:

• Authenticate with external services securely
• Access resources on behalf of users
• Maintain proper audit trails
• Implement least-privilege access patterns

Multi-Provider Authentication

Support scenarios like:

• Different authentication methods for different APIs
• Unified credential management across services
• OAuth flows for user-delegated access
• API key management for service accounts

Zero-Trust Security Models

Allow implementation of:

• No long-lived credentials in application code
• Centralized, audited credential vault
• Automated rotation to reduce attack window
• Comprehensive access logging

Compliance and Auditing

Enable teams to:

• Generate reports for compliance audits (SOC2, ISO27001)
• Implement periodic access reviews
• Maintain secrets inventory
• Enforce credential policies

Quick Start

Create API Key Credential Provider

aws bedrock-agentcore-control create-api-key-credential-provider \
  --name MyAPICredentialProvider \
  --api-key "YOUR_API_KEY" \
  --region us-west-2

Create OAuth Credential Provider

aws bedrock-agentcore-control create-oauth2-credential-provider \
  --name MyOAuthProvider \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET" \
  --authorization-url "https://provider.com/oauth/authorize" \
  --token-url "https://provider.com/oauth/token" \
  --scopes '["read", "write"]' \
  --region us-west-2

Using Credentials with SDK

from bedrock_agentcore.identity import CredentialProvider

# Get credentials for external API
provider = CredentialProvider("MyAPICredentialProvider")
api_key = provider.get_api_key()

# Get OAuth token
oauth_provider = CredentialProvider("MyOAuthProvider")
token = oauth_provider.get_access_token()

Common Operations

List Credential Providers

aws bedrock-agentcore-control list-api-key-credential-providers \
  --region us-west-2

Update Credential Provider

aws bedrock-agentcore-control update-api-key-credential-provider \
  --name MyAPICredentialProvider \
  --api-key "NEW_API_KEY" \
  --region us-west-2

Delete Credential Provider

aws bedrock-agentcore-control delete-api-key-credential-provider \
  --name MyAPICredentialProvider \
  --region us-west-2

Built-in OAuth Providers

AgentCore Identity includes built-in providers for popular services:

Best Practices

Security

• Use credential providers instead of hardcoded credentials
• Implement least-privilege access for each credential
• Rotate credentials regularly (quarterly minimum)
• Monitor credential usage with CloudWatch

Development

• Use separate credential providers per environment
• Implement proper error handling for credential access
• Test credential flows in non-production first
• Use SDK annotations for cleaner code

Operations

• Set up alerts for credential access failures
• Audit credential usage periodically
• Implement automated rotation where possible
• Document credential ownership and purpose

Troubleshooting

Related Services

• [Gateway Service](../gateway/README.md): Uses Identity for MCP target authentication
• [Runtime Service](../runtime/README.md): Uses Identity for agent authentication
• [Memory Service](../memory/README.md): May use Identity for data encryption

References

• AWS Identity Documentation
• Credential Provider Setup
• Identity Features
• Securing AI Agents Blog

AgentCore Memory Service

Status: ✅ Available

Overview

Amazon Bedrock AgentCore Memory is a fully managed service that gives AI agents the ability to remember past interactions, enabling more intelligent, context-aware, and personalized conversations. It addresses a fundamental challenge in agentic AI: statelessness. Without memory capabilities, AI agents treat each interaction as a new instance with no knowledge of previous conversations.

Memory Types

AgentCore Memory offers two types of memory that work together:

Short-Term Memory

Captures turn-by-turn interactions within a single session, allowing agents to maintain immediate context without requiring users to repeat information.

Example: When a user asks "What's the weather like in Seattle?" and follows up with "What about tomorrow?", the agent relies on recent conversation history to understand that "tomorrow" refers to Seattle weather.

Long-Term Memory

Automatically extracts and stores key insights from conversations across multiple sessions, including user preferences, important facts, and session summaries for persistent knowledge retention.

Example: If a customer mentions they prefer window seats during flight booking, the agent stores this preference and proactively offers window seats in future interactions.

Core Capabilities

Memory Resource Management

• Logical Containers: Encapsulate both raw events and processed long-term memories
• Retention Policies: Define how long data is retained
• Security Configuration: Control access and encryption
• Data Transformation: Transform raw interactions into meaningful insights

Short-Term Memory Features

• Event Storage: Store conversations, system events, and state changes as immutable events
• Session Organization: Organize by actor and session
• Context Preservation: Maintain immediate context within sessions
• Structured Storage: Support structured storage of interaction data

Long-Term Memory Features

• Insight Extraction: Automatically extract insights, preferences, and knowledge
• Asynchronous Processing: Extract memories asynchronously using memory strategies
• Cross-Session Persistence: Retain information across multiple sessions
• Semantic Search: Search memories by meaning and context

Memory Strategies

Define the intelligence layer that transforms raw events into meaningful memories:

Advanced Features

• Branching: Create alternative conversation paths from specific points
• Checkpointing: Save and mark specific states for later reference
• Memory Consolidation: Merge related memories without duplicates
• Audit Trail: Immutable audit trail for all memory operations

Use Cases

Conversational Agents

Enable chatbots to:

• Remember previous issues and preferences
• Provide relevant assistance based on history
• Create personalized customer experiences
• Maintain context across session breaks

Task-Oriented Agents

Support workflows like:

• Track multi-step business process status
• Maintain workflow progress across sessions
• Remember task context for resumption
• Store intermediate results

Multi-Agent Systems

Allow agent teams to:

• Share memory for synchronized operations
• Coordinate inventory levels and logistics
• Maintain shared context
• Optimize collaborative workflows

Autonomous Agents

Enable agents to:

• Plan routes based on past experiences
• Learn from previous interactions
• Improve decision-making over time
• Build persistent knowledge bases

Quick Start

Create Memory Resource

aws bedrock-agentcore-control create-memory \
  --memory-name my-agent-memory \
  --memory-strategies '[{"strategyName": "SEMANTIC", "configuration": {}}]' \
  --region us-west-2

Using Memory with SDK

from bedrock_agentcore.memory import MemoryClient

# Initialize memory client
memory = MemoryClient(memory_id="my-agent-memory")

# Add short-term memory event
memory.add_event(
    session_id="session-123",
    actor_id="user-456",
    event_type="message",
    content={"role": "user", "message": "Book a flight to Seattle"}
)

# Retrieve conversation history
history = memory.get_session_events(session_id="session-123")

# Search long-term memories
memories = memory.search_memories(
    query="user flight preferences",
    limit=5
)

Store and Retrieve Memories

# Store long-term memory
memory.store_memory(
    memory_type="user_preference",
    content={"preference": "window_seat", "context": "flights"}
)

# Retrieve relevant memories
relevant = memory.search_memories(
    query="seating preferences for flights",
    actor_id="user-456"
)

Common Operations

List Memories

aws bedrock-agentcore-control list-memories \
  --region us-west-2

Get Memory Details

aws bedrock-agentcore-control get-memory \
  --memory-id <MEMORY_ID> \
  --region us-west-2

Update Memory Configuration

aws bedrock-agentcore-control update-memory \
  --memory-id <MEMORY_ID> \
  --memory-strategies '[{"strategyName": "SEMANTIC"}, {"strategyName": "USER_PREFERENCE"}]' \
  --region us-west-2

Delete Memory

aws bedrock-agentcore-control delete-memory \
  --memory-id <MEMORY_ID> \
  --region us-west-2

Memory Strategies Configuration

Built-in Strategies

# Use semantic strategy
aws bedrock-agentcore-control create-memory \
  --memory-name semantic-memory \
  --memory-strategies '[{
    "strategyName": "SEMANTIC",
    "configuration": {}
  }]'

Custom Strategies

# Create custom strategy with specific model
aws bedrock-agentcore-control create-memory \
  --memory-name custom-memory \
  --memory-strategies '[{
    "strategyName": "CUSTOM",
    "configuration": {
      "modelId": "anthropic.claude-3-sonnet",
      "extractionPrompt": "Extract key user preferences from this conversation"
    }
  }]'

Best Practices

Memory Architecture

• Design memory architecture intentionally
• Choose appropriate strategies for use case
• Implement proper retention policies
• Consider memory costs and storage

Performance

• Use appropriate time-to-live settings
• Extract only relevant information
• Implement rhythm of memory operations
• Monitor memory search latency

Security

• Implement proper access controls
• Encrypt sensitive memories
• Audit memory access
• Follow data privacy regulations (GDPR, HIPAA)

Operations

• Monitor memory usage and costs
• Set up alerts for memory failures
• Implement backup strategies
• Test memory operations regularly

Troubleshooting

Related Services

• [Gateway Service](../gateway/README.md): Expose APIs as tools for agents
• [Runtime Service](../runtime/README.md): Execute agents that generate conversation data
• [Identity Service](../identity/README.md): Secure access to conversation data
• [Observability Service](../observability/README.md): Monitor memory operations

References

• AWS Memory Documentation
• Memory Types
• Memory Strategies
• Building Context-Aware Agents Blog
• Long-Term Memory Deep Dive

AgentCore Observability Service

Status: ✅ Available

Overview

Amazon Bedrock AgentCore Observability helps developers trace, debug, and monitor agent performance in production through unified operational dashboards and OpenTelemetry-compatible telemetry.

Core Capabilities

Distributed Tracing

• End-to-End Tracing: Complete request tracing across all AgentCore services
• Workflow Visualization: Detailed step-by-step workflow execution views
• Service Dependencies: Automatic mapping of service interactions
• Bottleneck Detection: Identify performance bottlenecks in agent workflows
• Error Attribution: Pinpoint exact failure points in complex workflows

Metrics and Monitoring

• Real-Time Metrics: Live operational metrics for all agent activities
• Token Tracking: Monitor token consumption and costs
• Latency Measurements: Track P50, P95, P99 response times
• Session Monitoring: Track session duration and status
• Error Rates: Monitor error rates by service and operation
• Throughput: Measure requests per second and operation counts

Logging

• Centralized Aggregation: All service logs in one place
• Structured Logging: Consistent log format with correlation IDs
• Search and Filter: Query logs by service, operation, or time
• Real-Time Streaming: Live log tailing for debugging
• Log Retention: Configurable retention policies

Dashboards and Alerting

• Unified Dashboards: Pre-built operational dashboards
• Custom Metrics: Define and visualize custom metrics
• CloudWatch Integration: Native AWS CloudWatch support
• Configurable Alerts: Set up alerts for critical conditions
• Multi-Service Views: Consolidated view across all services

OpenTelemetry Support

• Industry Standard: Compatible with OpenTelemetry specification
• Tool Integration: Works with existing observability tools
• Custom Instrumentation: Add custom traces and metrics
• External Export: Export telemetry to external systems

Use Cases

Production Debugging

Enable teams to:

• Debug agent execution issues in real-time
• Identify root causes of failures quickly
• Trace request flows across services
• Analyze error patterns and trends

Performance Monitoring

Support scenarios like:

• Monitor agent response times
• Track token usage and costs
• Identify slow operations
• Optimize agent workflows

Behavior Analysis

Allow teams to:

• Analyze agent behavior patterns
• Understand user interaction flows
• Identify usage trends
• Detect anomalies

Quality Assurance

Enable teams to:

• Ensure SLA compliance
• Monitor service reliability
• Track quality metrics
• Validate performance standards

Capacity Planning

Support activities like:

• Forecast resource needs
• Identify scaling requirements
• Optimize resource allocation
• Plan for growth

Architecture

Observability Data Flow

┌─────────────────────────────────────────┐
│  AgentCore Services                     │
│  - Gateway, Runtime, Memory, etc.       │
│  - Emit traces, logs, metrics           │
└─────────────────────────────────────────┘
           ↓
┌─────────────────────────────────────────┐
│  OpenTelemetry Collector                │
│  - Receive telemetry data               │
│  - Process and enrich                   │
│  - Route to destinations                │
└─────────────────────────────────────────┘
           ↓
    ┌──────┴──────┐
    ↓             ↓
┌─────────┐  ┌─────────────┐
│CloudWatch│  │  X-Ray      │
│ Logs    │  │  Traces     │
│ Metrics │  │  Service Map│
└─────────┘  └─────────────┘
    ↓             ↓
┌─────────────────────────────────────────┐
│  Unified Dashboards                     │
│  - Service health                       │
│  - Performance metrics                  │
│  - Error analysis                       │
│  - Cost tracking                        │
└─────────────────────────────────────────┘

Data Collection Model

1. Automatic Instrumentation: Built-in instrumentation for all services 2. Context Propagation: Correlation IDs passed across service boundaries 3. Sampling: Intelligent sampling for high-volume operations 4. Buffering: Local buffering for reliability 5. Batch Export: Efficient batch transmission to backends

Configuration

Enable Observability

# Enable observability for agent
aws bedrock-agentcore-control update-observability-config \
  --agent-id <AGENT_ID> \
  --config '{
    "tracing": {
      "enabled": true,
      "samplingRate": 1.0
    },
    "metrics": {
      "enabled": true,
      "interval": 60
    },
    "logging": {
      "enabled": true,
      "level": "INFO"
    }
  }' \
  --region <REGION>

Configure Sampling

# Set trace sampling rate
aws bedrock-agentcore-control update-tracing-config \
  --agent-id <AGENT_ID> \
  --sampling-rate 0.1 \
  --region <REGION>

Custom Metrics

# Define custom metric
aws bedrock-agentcore-control create-custom-metric \
  --agent-id <AGENT_ID> \
  --metric-name "CustomOperationCount" \
  --metric-type "Counter" \
  --description "Count of custom operations" \
  --region <REGION>

Traces

View Traces

# Query recent traces
aws xray get-trace-summaries \
  --start-time <START_TIMESTAMP> \
  --end-time <END_TIMESTAMP> \
  --filter-expression 'service(id(name: "AgentCore", type: "AWS::Service"))'

Trace Details

# Get specific trace
aws xray batch-get-traces \
  --trace-ids <TRACE_ID_1> <TRACE_ID_2>

Service Map

# Get service map
aws xray get-service-graph \
  --start-time <START_TIMESTAMP> \
  --end-time <END_TIMESTAMP>

Metrics

Common Metrics

Gateway Metrics:

• TargetInvocations: Number of target invocations
• TargetErrors: Number of target errors
• TargetLatency: Target response latency

Runtime Metrics:

• AgentExecutions: Number of agent executions
• ExecutionDuration: Agent execution duration
• ExecutionErrors: Number of execution failures

Memory Metrics:

• MemoryReads: Number of memory read operations
• MemoryWrites: Number of memory write operations
• MemorySize: Total memory storage size

Token Metrics:

• TokensConsumed: Total tokens used
• TokenCost: Estimated cost in dollars

Query Metrics

# Get metric statistics
aws cloudwatch get-metric-statistics \
  --namespace AWS/BedrockAgentCore \
  --metric-name TargetInvocations \
  --dimensions Name=AgentId,Value=<AGENT_ID> \
  --start-time <START> \
  --end-time <END> \
  --period 300 \
  --statistics Sum Average

Custom Metrics

# Put custom metric data
aws cloudwatch put-metric-data \
  --namespace AgentCore/Custom \
  --metric-name CustomMetric \
  --value 1.0 \
  --dimensions AgentId=<AGENT_ID>

Logs

Query Logs

# Tail agent logs
aws logs tail /aws/bedrock-agentcore/<AGENT_ID> \
  --follow \
  --format short

# Query logs with filter
aws logs filter-log-events \
  --log-group-name /aws/bedrock-agentcore/<AGENT_ID> \
  --filter-pattern "ERROR" \
  --start-time <TIMESTAMP>

Log Insights

# Run Insights query
aws logs start-query \
  --log-group-name /aws/bedrock-agentcore/<AGENT_ID> \
  --start-time <START_TIMESTAMP> \
  --end-time <END_TIMESTAMP> \
  --query-string 'fields @timestamp, @message
    | filter @message like /ERROR/
    | sort @timestamp desc
    | limit 20'

Dashboards

Create Dashboard

# Create CloudWatch dashboard
aws cloudwatch put-dashboard \
  --dashboard-name AgentCore-<AGENT_ID> \
  --dashboard-body file://dashboard-definition.json

Dashboard Definition Example

{
  "widgets": [
    {
      "type": "metric",
      "properties": {
        "metrics": [
          ["AWS/BedrockAgentCore", "TargetInvocations", {"stat": "Sum"}]
        ],
        "period": 300,
        "stat": "Sum",
        "region": "us-west-2",
        "title": "Target Invocations"
      }
    },
    {
      "type": "metric",
      "properties": {
        "metrics": [
          ["AWS/BedrockAgentCore", "TargetErrors", {"stat": "Sum"}]
        ],
        "period": 300,
        "stat": "Sum",
        "region": "us-west-2",
        "title": "Target Errors"
      }
    }
  ]
}

Alerting

Create Alarm

# Create CloudWatch alarm
aws cloudwatch put-metric-alarm \
  --alarm-name high-error-rate-<AGENT_ID> \
  --alarm-description "Alert when error rate exceeds threshold" \
  --metric-name TargetErrors \
  --namespace AWS/BedrockAgentCore \
  --statistic Sum \
  --period 300 \
  --evaluation-periods 2 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold \
  --dimensions Name=AgentId,Value=<AGENT_ID> \
  --alarm-actions <SNS_TOPIC_ARN>

Alarm Templates

High Error Rate:

# Alert on >5% error rate
aws cloudwatch put-metric-alarm \
  --alarm-name error-rate-high \
  --metric-name ErrorRate \
  --threshold 5 \
  --comparison-operator GreaterThanThreshold

High Latency:

# Alert on P95 latency >2s
aws cloudwatch put-metric-alarm \
  --alarm-name latency-high \
  --metric-name TargetLatency \
  --statistic p95 \
  --threshold 2000 \
  --comparison-operator GreaterThanThreshold

High Token Usage:

# Alert on excessive token usage
aws cloudwatch put-metric-alarm \
  --alarm-name tokens-high \
  --metric-name TokensConsumed \
  --statistic Sum \
  --threshold 1000000 \
  --comparison-operator GreaterThanThreshold

Best Practices

Instrumentation

• Enable observability for all production agents
• Use appropriate sampling rates (1.0 for dev, 0.1 for prod)
• Add custom metrics for business-critical operations
• Include context in log messages
• Use structured logging formats

Performance

• Use appropriate metric aggregation periods
• Implement metric sampling for high-volume operations
• Set reasonable log retention periods
• Use log filtering to reduce noise
• Archive old traces and logs

Cost Optimization

• Adjust sampling rates based on traffic
• Use metric filters to create custom metrics
• Set appropriate log retention (7-30 days)
• Archive infrequently accessed data to S3
• Use CloudWatch Insights for complex queries

Alerting

• Define clear SLOs and SLIs
• Set meaningful alert thresholds
• Avoid alert fatigue with proper tuning
• Use composite alarms for complex conditions
• Implement escalation policies

Security

• Encrypt logs and metrics at rest
• Use IAM for access control
• Implement least privilege access
• Audit observability data access
• Protect sensitive data in logs

Integration Patterns

With All Services

Observability is automatically integrated with all AgentCore services:

Gateway ──→ Observability
Runtime ──→ Observability
Memory ──→ Observability
Identity ──→ Observability
Code Interpreter ──→ Observability
Browser ──→ Observability

With External Tools

Export telemetry to external observability platforms:

AgentCore Observability
    ↓
OpenTelemetry Collector
    ↓
┌────────┬────────┬────────┐
│Datadog │New Relic│Grafana│
└────────┴────────┴────────┘

Troubleshooting

No Traces Appearing

Diagnosis:

# Check if tracing is enabled
aws bedrock-agentcore-control get-observability-config \
  --agent-id <AGENT_ID>

Solution: Enable tracing in observability configuration

High Cardinality Metrics

Symptom: Too many unique metric combinations Solution: Reduce dimension cardinality, use metric filters

Missing Logs

Diagnosis:

# Check log group exists
aws logs describe-log-groups \
  --log-group-name-prefix /aws/bedrock-agentcore

Solution: Verify IAM permissions for CloudWatch Logs

High Costs

Symptom: Excessive CloudWatch costs Solution: Adjust sampling rates, reduce log retention, archive old data

Performance Monitoring

Key Performance Indicators

Availability:

• Service uptime percentage
• Error rate by service
• Failed request percentage

Performance:

• P50, P95, P99 latency
• Request throughput
• Operation duration

Efficiency:

• Token consumption rate
• Cost per operation
• Resource utilization

Quality:

• Agent success rate
• User satisfaction metrics
• Workflow completion rate

Additional Resources

• AWS Documentation: Bedrock AgentCore Observability
• CloudWatch Guide: CloudWatch User Guide
• X-Ray Guide: AWS X-Ray Developer Guide
• OpenTelemetry: OpenTelemetry Documentation
• Best Practices: Observability Best Practices

---

Related Services:

• Gateway Service - Gateway monitoring
• Runtime Service - Runtime tracing
• Memory Service - Memory metrics
• Credential Management - Cross-service credential patterns

Runtime Service

The Runtime service provides a secure, serverless hosting environment for deploying and running AI agents or tools. It handles scaling, session management, security isolation, and infrastructure management.

Key Features

Quick Start

Prerequisites

• AWS CLI configured with appropriate permissions
• Docker installed for container builds
• Python 3.9+ for SDK usage

Deploy an Agent

Step 1: Install AgentCore SDK

pip install bedrock-agentcore

Step 2: Create agent code

from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@app.handler()
async def handle_request(request, context):
    user_input = request.get("input", "")
    # Your agent logic here
    return {"response": f"Processed: {user_input}"}

Step 3: Create AgentCore Runtime

aws bedrock-agentcore-control create-agent-runtime \
  --agent-runtime-name my-agent \
  --runtime-artifact '{"containerConfiguration": {"containerUri": "<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/my-agent:latest"}}' \
  --role-arn arn:aws:iam::<ACCOUNT_ID>:role/AgentRuntimeExecutionRole \
  --network-configuration '{"networkMode": "PUBLIC"}' \
  --region us-west-2

Step 4: Invoke agent

aws bedrock-agentcore-runtime invoke-agent-runtime \
  --agent-runtime-endpoint-arn arn:aws:bedrock-agentcore:us-west-2:<ACCOUNT_ID>:runtime/my-agent/endpoint/DEFAULT \
  --payload '{"input": "Hello, agent!"}' \
  --region us-west-2

Core Components

AgentCore Runtime

Containerized application hosting your AI agent or tool code. Each runtime:

• Has a unique identity
• Is versioned for controlled deployment and updates
• Can use popular frameworks or custom implementations

Versions

Immutable snapshots of configuration:

• Version 1 (V1) created automatically with new runtime
• Each update creates a new version
• Enables rollback capabilities

Endpoints

Addressable access points to runtime versions:

• DEFAULT: Automatically created, points to latest version
• Custom endpoints for different environments (dev, test, prod)
• Unique ARN for invocation

Endpoint states: CREATING → READY (or CREATE_FAILED) → UPDATING → READY

Sessions

Individual interaction contexts with complete isolation:

• Dedicated microVM per session
• Preserves context across interactions
• Persists up to 8 hours
• Auto-terminates after 15 minutes idle

Session states: Active → Idle → Terminated

Authentication

Inbound (Who Can Access Your Agent)

OAuth Flow: 1. User authenticates with identity provider 2. Client receives bearer token 3. Token passed in authorization header 4. Runtime validates token 5. Request processed or rejected

Outbound (Accessing External Services)

Modes:

• User-delegated: Acting on behalf of end user
• Autonomous: Acting with service-level credentials

Common Operations

List Agent Runtimes

aws bedrock-agentcore-control list-agent-runtimes \
  --region us-west-2

Get Runtime Details

aws bedrock-agentcore-control get-agent-runtime \
  --agent-runtime-id <RUNTIME_ID> \
  --region us-west-2

Update Runtime

aws bedrock-agentcore-control update-agent-runtime \
  --agent-runtime-id <RUNTIME_ID> \
  --runtime-artifact '{"containerConfiguration": {"containerUri": "<NEW_IMAGE_URI>"}}' \
  --region us-west-2

Delete Runtime

aws bedrock-agentcore-control delete-agent-runtime \
  --agent-runtime-id <RUNTIME_ID> \
  --region us-west-2

Long-Running Agents

For workloads exceeding request/response cycles (up to 8 hours):

from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@app.handler()
async def handle_request(request, context):
    # Add async task
    task_id = context.add_async_task("background-processing")

    # Start background work
    # ... long-running operation ...

    # Complete task when done
    context.complete_async_task(task_id)

    return {"status": "Task started", "task_id": task_id}

Streaming Responses

Enable real-time partial results:

@app.handler()
async def handle_request(request, context):
    async for chunk in generate_response(request):
        yield {"partial": chunk}
    yield {"complete": True}

Supported Frameworks

Troubleshooting

Related Services

• [Gateway Service](../gateway/README.md): Expose APIs as tools for agents
• [Memory Service](../memory/README.md): Store agent conversation history
• [Identity Service](../identity/README.md): Manage agent credentials
• [Observability Service](../observability/README.md): Monitor agent performance

References

• AWS Runtime Documentation
• How Runtime Works
• Runtime Troubleshooting
• Runtime API Reference