---
name: majiayu000/bedrock-agentcore
source: https://app.decimal.ai/s/majiayu000-bedrock-agentcore@1/SKILL.md
source_sha256: 84c9eb8ef9a0
---

# 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

```bash
# 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**:
```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

---

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

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

---

## Error Handling

```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
```

---

## IAM Permissions

### 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:*:*:*"
    }
  ]
}
```

---

## 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](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)