bedrock-agentcore

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

---

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

---

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

```bash

# Install SDK and CLI

pip install bedrock-agentcore strands-agents bedrock-agentcore-starter-toolkit

# Verify installation

agentcore --help

```

---

1. AgentCore Runtime

Secure, session-isolated compute for running agent code.

Boto3 Client:

```python

import boto3

# Data plane operations

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

# Control plane operations

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

```

Create Agent Runtime:

```python

# 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:

```python

# 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:

```python

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:

```python

response = control.create_gateway(

name='customer-service-gateway',

description='Gateway for customer service tools',

protocolType='REST'

)

gateway_arn = response['gatewayArn']

```

Add Gateway Target (Tool):

```python

# 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:

```python

# Sync gateway tools for discovery

control.synchronize_gateway_targets(

gatewayId='gateway-xxx'

)

```

---

3. Browser Runtime

Execute complex web-based workflows securely.

Start Browser Session:

```python

response = client.start_browser_session(

browserId='browser-xxx',

sessionConfiguration={

'timeout': 300,

'viewport': {'width': 1920, 'height': 1080}

}

)

session_id = response['browserSessionId']

```

Execute Browser Action:

```python

# 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:

```python

response = client.start_code_interpreter_session(

codeInterpreterId='interpreter-xxx'

)

session_id = response['codeInterpreterSessionId']

```

Execute Code:

```python

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:

```python

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:

```python

response = control.create_workload_identity(

name='agent-identity',

allowedRoleArns=['arn:aws:iam::123456789012:role/AgentRole']

)

```

Get Access Token:

```python

# 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:

```python

# 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

---

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 |

---

Step 1: Create Agent File

```python

# 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

```bash

# 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

```python

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'])

```

---

```python

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

```

---

Minimum Execution Role

```json

{

"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": [

"logs:CreateLogGroup",

"logs:CreateLogStream",

"logs:PutLogEvents"

],

"Resource": "arn:aws:logs:::*"

}

]

}

```

---

• 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/gateway-configuration.md - Detailed gateway setup
• references/identity-integration.md - OAuth and workload identity
• references/troubleshooting.md - Common issues and solutions

---

• [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/)
• [Boto3 BedrockAgentCore](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore.html)
• [AgentCore SDK Python](https://github.com/aws/bedrock-agentcore-sdk-python)
• [AgentCore Starter Toolkit](https://github.com/aws/bedrock-agentcore-starter-toolkit)