agentcore

What this skill does

Specialist guidance for Amazon Bedrock AgentCore. Covers the full platform: Runtime, Memory, Gateway, Identity, Policy, Code Interpreter, Browser, Observability, and Evaluations. Framework-agnostic and model-agnostic.

## Process

1. Identify the agent workload: purpose, framework (Strands, LangGraph, custom), model requirements, tool integrations, latency/duration needs
2. Use the `awsknowledge` MCP tools (`mcp__plugin_aws-dev-toolkit_awsknowledge__aws___search_documentation`, `mcp__plugin_aws-dev-toolkit_awsknowledge__aws___read_documentation`, `mcp__plugin_aws-dev-toolkit_awsknowledge__aws___recommend`) to verify current AgentCore quotas, regional availability, and API changes
3. Select the appropriate AgentCore services for the workload (not every agent needs every service)
4. Design the deployment topology: Runtime config, memory strategy, tool connectivity, identity model
5. Configure security: Identity, Policy (Cedar), VPC connectivity, guardrails
6. Set up observability and evaluations from day one
7. Plan the PoC-to-production migration path

## AgentCore Service Selection Matrix

| Requirement | Service | Why |
|---|---|---|
| Deploy and scale agents serverlessly | **Runtime** | Secure, framework-agnostic hosting with session isolation, auto-scaling, consumption-based pricing |
| Conversation history and learned context | **Memory** | Short-term (session) and long-term (episodic) memory without managing infrastructure |
| Expose APIs/Lambda as agent tools | **Gateway** | Converts existing APIs and Lambda functions into MCP-compatible tools, handles auth |
| Agent-to-third-party auth (OAuth, API keys) | **Identity** | Manages workload identities, OAuth2 token exchange, API key vaults |
| Control what agents can do with tools | **Policy** | Cedar-based deterministic enforcement at the Gateway boundary, natural language authoring |
| Execute code in sandbox | **Code Interpreter** | Isolated sandbox for Python execution, file I/O, data analysis |
| Browse web pages programmatically | **Browser** | Cloud-based browser runtime for web interaction at scale |
| Trace, debug, monitor agent behavior | **Observability** | OpenTelemetry-compatible traces to CloudWatch/X-Ray, unified dashboards |
| Test and score agent quality | **Evaluations** | 13 built-in evaluators, custom scoring, continuous monitoring |

## When You Need Each Service

### Always Start With
- **Runtime** — every production agent needs managed hosting
- **Observability** — instrument from day one, not after the first incident

### Add Based on Workload
- **Memory** — when agents need conversation continuity or personalization
- **Gateway** — when agents call external APIs or Lambda functions (most agents)
- **Identity** — when agents access third-party services requiring OAuth or API keys
- **Policy** — when you need deterministic guardrails on tool usage (compliance, financial, PII)

### Add for Specialized Capabilities
- **Code Interpreter** — data analysis agents, code generation agents
- **Browser** — web scraping, form-filling, UI testing agents
- **Evaluations** — continuous quality monitoring (should be added before production)

## Runtime

AgentCore Runtime is a serverless, purpose-built hosting environment for AI agents.

### Key Capabilities
- Framework-agnostic: Strands Agents, LangGraph, custom Python, any framework
- Model-agnostic: any foundation model (Bedrock, self-hosted, third-party)
- Session isolation: each user session runs in its own execution context
- Supports real-time conversations (<1s latency) through to 8-hour async workloads
- Bidirectional streaming (WebSocket) for natural conversations
- Consumption-based pricing: CPU + memory billed per-second (1-second minimum)
- A2A (Agent-to-Agent) protocol support for cross-framework multi-agent systems

### Development vs Production Deployment

**Development and testing**: Use the AgentCore CLI or Starter Toolkit for fast iteration — scaffolding, local dev, quick deploys, and testing.

**Production**: Define all AgentCore resources in IaC (CDK, Terraform, CloudFormation, or SAM). CLI-created resources are useful for prototyping but should not be the source of truth for production infrastructure. The Starter Toolkit's CDK templates are a solid starting point for production IaC.

### Deployment Options
- **AgentCore CLI** (dev/test): Fastest path — `agentcore init` → `agentcore deploy` in minutes
- **Starter Toolkit** (reference IaC): Full-stack CDK template with auth, frontend, and all services pre-wired — fork and customize for production
- **CDK / Terraform / SAM** (production): Define resources in IaC, deploy via CI/CD pipeline
- **Container image** (manual): Docker image pushed to ECR, deployed to Runtime — full control over build

## AgentCore CLI

The [AgentCore CLI](https://github.com/aws/agentcore-cli) is the preferred tool for scaffolding, local development, and rapid iteration on agents. It abstracts away container builds, ECR pushes, and runtime configuration into simple commands. Use it for dev/test workflows — for production, define the same resources in IaC.

### Install

```bash
pip install agentcore-cli
```

### Quick Start

```bash
# Initialize a new agent project (choose framework: strands, langgraph, or custom)
agentcore init my-agent --framework strands

# Develop locally
cd my-agent
agentcore dev

# Deploy to AgentCore Runtime
agentcore deploy --region us-east-1

# Test the deployed agent
agentcore invoke --agent-name my-agent --input "Hello, what can you do?"
```

### What the CLI Handles
- **Project scaffolding**: generates agent code, Dockerfile, requirements, and config
- **Local development**: `agentcore dev` runs the agent locally with hot-reload
- **Build + push**: builds the Docker container, pushes to ECR automatically
- **Deploy**: creates/updates the agent runtime and endpoint
- **Invoke**: test deployed agents from the command line
- **Alias management**: create and update aliases for version routing

### CLI vs Direct AWS CLI

| Task | AgentCore CLI | AWS CLI |
|---|---|---|
| Create new agent | `agentcore init` | Manual Dockerfile + ECR + create-agent-runtime |
| Deploy | `agentcore deploy` | docker build + docker push + create/update API calls |
| Local dev | `agentcore dev` | Manual server setup |
| Test | `agentcore invoke` | `aws bedrock-agentcore invoke-agent-runtime` |

Use the AgentCore CLI for day-to-day development and testing. For production, define the equivalent resources in CDK, Terraform, or CloudFormation — the CLI is great for proving out configurations quickly, but IaC is the source of truth for production infrastructure.

## Starter Toolkit (FAST Template)

The [AgentCore Starter Toolkit](https://github.com/aws/bedrock-agentcore-starter-toolkit) provides a full-stack CDK reference architecture. Use it when you need a complete production deployment with authentication, frontend, and all AgentCore services wired together.

### What It Provides
- **CDK infrastructure**: Full IaC for Runtime, Gateway, Memory, Code Interpreter, and Observability — one `cdk deploy`
- **Auth integration**: Amazon Cognito authentication pre-wired for frontend → Runtime, agents → Gateway, and API Gateway
- **Frontend template**: React app with streamable HTTP for real-time agent response streaming via CloudFront
- **Framework templates**: Pre-built agent patterns for Strands Agents and LangGraph (framework-agnostic by design)
- **CI/CD patterns**: GitHub Actions workflow for build, scan (Amazon Inspector), deploy, and alias management
- **Observability**: AWS OpenTelemetry Distro auto-instrumentation for traces → X-Ray, metrics/logs → CloudWatch

### Quick Start

```bash
git clone https://github.com/aws/bedrock-agentcore-starter-toolkit.git
cd bedrock-agentcore-starter-toolkit
pip install -r requirements.txt
cdk deploy --all
```

### Architecture

The Fullstack AgentCore Solution Template (FAST) deploys:

```
CloudFront (React frontend)
  → Cognito (auth)
    → AgentCore Runtime (age