bedrock-agentcore

name	bedrock-agentcore
description	Amazon Bedrock AgentCore platform for building, deploying, and operating production AI agents. Covers Runtime, Gateway, Browser, Code Interpreter, and Identity services. Use when building Bedrock agents, deploying AI agents to production, or integrating with AgentCore services.
allowed-tools	Task, Read, Write, Edit, Glob, Grep, Bash

Amazon Bedrock AgentCore

Overview

Amazon Bedrock AgentCore is an agentic platform for building, deploying, and operating effective AI agents securely at scale—no infrastructure management needed. It provides framework-agnostic primitives that work with popular open-source frameworks (Strands, LangGraph, CrewAI, Autogen) and any model.

Purpose: Transform any AI agent into a production-ready application with enterprise-grade infrastructure

Pattern: Capabilities-based (6 independent service modules)

Key Principles (validated by AWS December 2025):

1. Framework Agnostic - Works with any agent framework or model
2. Zero Infrastructure - Fully managed, no ops overhead
3. Session Isolation - Complete data isolation between sessions
4. Enterprise Security - VPC, PrivateLink, identity integration
5. Composable Services - Use only what you need
6. Production Ready - Built for scale, reliability, and security

Quality Targets:

• Deployment: < 5 minutes from code to production
• Latency: Low-latency to 8-hour async workloads
• Observability: Full CloudWatch integration

---

When to Use

Use bedrock-agentcore when:

• Building production AI agents on AWS
• Need managed infrastructure for agent deployment
• Require session isolation and enterprise security
• Want to use existing agent frameworks (LangGraph, CrewAI, etc.)
• Need browser automation or code execution capabilities
• Integrating with existing identity providers

When NOT to Use:

• Simple Bedrock model invocations (use bedrock-runtime)
• Standard Bedrock Agents with action groups (use bedrock-agent)
• Non-AWS deployments

---

Prerequisites

Required

• AWS account with Bedrock access
• IAM permissions for AgentCore services
• Python 3.10+ (for SDK)

Recommended

• bedrock-agentcore-sdk-python installed
• bedrock-agentcore-starter-toolkit CLI
• Foundation model access enabled (Claude, etc.)

Installation

# Install SDK and CLI
pip install bedrock-agentcore strands-agents bedrock-agentcore-starter-toolkit

# Verify installation
agentcore --help

---

Core Services

1. AgentCore Runtime

Secure, session-isolated compute for running agent code.

Boto3 Client:

import boto3

# Data plane operations
client = boto3.client('bedrock-agentcore')

# Control plane operations
control = boto3.client('bedrock-agentcore-control')

Create Agent Runtime:

# Using starter toolkit
# agentcore configure -e main.py -n my-agent
# agentcore deploy

# Using boto3 control plane
response = control.create_agent_runtime(
    name='my-production-agent',
    description='Customer service agent',
    agentRuntimeArtifact={
        's3': {
            'uri': 's3://my-bucket/agent-package.zip'
        }
    },
    roleArn='arn:aws:iam::123456789012:role/AgentCoreExecutionRole',
    pythonRuntime='PYTHON_3_13',
    entryPoint=['main.py']
)
agent_runtime_arn = response['agentRuntimeArn']

Invoke Agent:

# Invoke deployed agent
response = client.invoke_agent_runtime(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-east-1:123456789012:agent-runtime/xxx',
    runtimeSessionId='session-123',
    payload={
        'prompt': 'What is my order status?',
        'context': {'user_id': 'user-456'}
    }
)

result = response['payload']
print(result)

Agent Entry Point Structure:

from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp(debug=True)
agent = Agent()

@app.entrypoint
def invoke(payload):
    """Main agent entry point"""
    user_message = payload.get("prompt", "Hello!")
    app.logger.info(f"Processing: {user_message}")

    result = agent(user_message)
    return {"result": result.message}

if __name__ == "__main__":
    app.run()

---

2. AgentCore Gateway

Transforms existing APIs and Lambda functions into agent-compatible tools with semantic search discovery.

Create Gateway:

response = control.create_gateway(
    name='customer-service-gateway',
    description='Gateway for customer service tools',
    protocolType='REST'
)
gateway_arn = response['gatewayArn']

Add Gateway Target (Tool):

# Add an existing Lambda as a tool
response = control.create_gateway_target(
    gatewayId='gateway-xxx',
    name='GetOrderStatus',
    description='Retrieves order status by order ID',
    targetConfiguration={
        'lambdaTarget': {
            'lambdaArn': 'arn:aws:lambda:us-east-1:123456789012:function:GetOrder'
        }
    },
    toolSchema={
        'name': 'get_order_status',
        'description': 'Get the current status of a customer order',
        'inputSchema': {
            'type': 'object',
            'properties': {
                'order_id': {
                    'type': 'string',
                    'description': 'The unique order identifier'
                }
            },
            'required': ['order_id']
        }
    }
)

Synchronize Tools:

# Sync gateway tools for discovery
control.synchronize_gateway_targets(
    gatewayId='gateway-xxx'
)

---

3. Browser Runtime

Execute complex web-based workflows securely.

Start Browser Session:

response = client.start_browser_session(
    browserId='browser-xxx',
    sessionConfiguration={
        'timeout': 300,
        'viewport': {'width': 1920, 'height': 1080}
    }
)
session_id = response['browserSessionId']

Execute Browser Action:

# Navigate and interact
response = client.update_browser_stream(
    browserSessionId=session_id,
    action={
        'navigate': {'url': 'https://example.com'},
        'click': {'selector': '#submit-button'},
        'type': {'selector': '#search', 'text': 'query'}
    }
)

---

4. Code Interpreter

Safely execute code for tasks like data analysis and visualization.

Start Code Interpreter Session:

response = client.start_code_interpreter_session(
    codeInterpreterId='interpreter-xxx'
)
session_id = response['codeInterpreterSessionId']

Execute Code:

response = client.invoke_code_interpreter(
    codeInterpreterSessionId=session_id,
    code='''
import pandas as pd
import matplotlib.pyplot as plt

# Analyze data
df = pd.DataFrame({'x': [1,2,3,4,5], 'y': [2,4,6,8,10]})
plt.plot(df['x'], df['y'])
plt.savefig('output.png')
print(df.describe())
''',
    language='PYTHON'
)

output = response['output']
files = response['files']  # Generated files

---

5. Identity Integration

Native integration with existing identity providers for authentication and permission delegation.

Create OAuth2 Provider:

response = control.create_oauth2_credential_provider(
    name='okta-provider',
    credentialProviderVendor='OKTA',
    oauth2ProviderConfig={
        'clientId': 'your-client-id',
        'clientSecret': 'your-client-secret',
        'authorizationServerUrl': 'https://your-domain.okta.com/oauth2/default',
        'scopes': ['openid', 'profile', 'email']
    }
)

Create Workload Identity:

response = control.create_workload_identity(
    name='agent-identity',
    allowedRoleArns=['arn:aws:iam::123456789012:role/AgentRole']
)

Get Access Token:

# Get token for workload
response = client.get_workload_access_token(
    workloadIdentityId='identity-xxx'
)
access_token = response['accessToken']

---

6. Observability

Real-time visibility via CloudWatch and OpenTelemetry.

Enable Observability:

# In your agent entry point
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

# Configure tracing
provider = TracerProvider()
trace.set_tracer_provider(provider)

# Entry point with OTel
# entryPoint: ['opentelemetry-instrument', 'main.py']

CloudWatch Metrics:

• Token usage per session
• Latency (p50, p95, p99)
• Session duration
• Error rates
• Tool call success/failure

---

Boto3 Client Reference

Data Plane (bedrock-agentcore)

Method	Purpose
invoke_agent_runtime	Execute agent logic
stop_runtime_session	Halt active session
list_sessions	List all sessions
start_browser_session	Initialize browser
stop_browser_session	End browser session
start_code_interpreter_session	Launch interpreter
invoke_code_interpreter	Execute code
batch_create_memory_records	Create memories
retrieve_memory_records	Fetch memories
get_workload_access_token	Get auth token
evaluate	Run evaluation

Control Plane (bedrock-agentcore-control)

Method	Purpose
create_agent_runtime	Create runtime
delete_agent_runtime	Remove runtime
update_agent_runtime	Modify runtime
create_gateway	Create gateway
create_gateway_target	Add tool
create_memory	Create memory store
create_policy	Create policy
create_evaluator	Create evaluator
create_browser	Create browser
create_code_interpreter	Create interpreter

---

Quick Start: Hello World Agent

Step 1: Create Agent File

# main.py
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent(model="anthropic.claude-sonnet-4-20250514-v1:0")

@app.entrypoint
def invoke(payload):
    prompt = payload.get("prompt", "Hello!")
    result = agent(prompt)
    return {"response": result.message}

if __name__ == "__main__":
    app.run()

Step 2: Configure and Deploy

# Configure
agentcore configure -e main.py -n hello-world-agent

# Test locally
python main.py &
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello!"}'

# Deploy to AWS
agentcore deploy

# Test deployed
agentcore invoke '{"prompt": "Hello from production!"}'

Step 3: Invoke Programmatically

import boto3

client = boto3.client('bedrock-agentcore')

response = client.invoke_agent_runtime(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-east-1:123456789012:agent-runtime/hello-world',
    runtimeSessionId='test-session-1',
    payload={'prompt': 'What can you help me with?'}
)

print(response['payload'])

---

Error Handling

from botocore.exceptions import ClientError

try:
    response = client.invoke_agent_runtime(
        agentRuntimeArn=agent_arn,
        runtimeSessionId='session-1',
        payload={'prompt': 'test'}
    )
except ClientError as e:
    error_code = e.response['Error']['Code']

    if error_code == 'ResourceNotFoundException':
        print("Agent runtime not found")
    elif error_code == 'ValidationException':
        print("Invalid request parameters")
    elif error_code == 'ThrottlingException':
        print("Rate limited - implement backoff")
    elif error_code == 'AccessDeniedException':
        print("Check IAM permissions")
    else:
        raise

---

IAM Permissions

Minimum Execution Role

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:StartBrowserSession",
        "bedrock-agentcore:InvokeCodeInterpreter"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "arn:aws:bedrock:*::foundation-model/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        
        
        
      
       
    
  

---

Related Skills

• bedrock-agentcore-policy: Cedar policy authoring and enforcement
• bedrock-agentcore-evaluations: Agent testing and quality evaluation
• bedrock-agentcore-memory: Episodic and short-term memory management
• bedrock-agentcore-deployment: Production deployment patterns
• bedrock-agentcore-multi-agent: Multi-agent orchestration (A2A protocol)
• boto3-eks: For EKS-hosted agents
• terraform-aws: Infrastructure as code

---

References

• references/gateway-configuration.md - Detailed gateway setup
• references/identity-integration.md - OAuth and workload identity
• references/troubleshooting.md - Common issues and solutions

---

Sources

• Amazon Bedrock AgentCore
• Boto3 BedrockAgentCore
• AgentCore SDK Python
• AgentCore Starter Toolkit