strands-compose-agentcore 0.11.0

---

Deploy strands-compose agent systems on AWS Bedrock AgentCore Runtime

What is this?

You built your agent system with strands-compose — models, tools, orchestrations, all described in YAML. It works locally. Now you want it running on AWS with per-session isolation, auto-scaling, and zero infrastructure management.

strands-compose-agentcore fills the gap between strands-compose and AWS Bedrock AgentCore Runtime. It wraps your YAML config as the ASGI app that AgentCore expects, provides a CLI for local development with a built-in REPL, and ships a client for invoking deployed agents — from the terminal or from your own apps.

Same config you already have. Same agents. Test locally, deploy, invoke — all from the command line.

See it in action

You have your strands-compose config.yaml. Here's how fast you go from zero to deployed:

Create the app — one function call wraps your config as a BedrockAgentCoreApp:

# main.py
from pathlib import Path
from strands_compose_agentcore import create_app

app = create_app(Path(__file__).parent / "config.yaml")

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

Run locally — dev server + interactive REPL in one terminal:

sca dev --config config.yaml

Deploy to AWS — register and ship it to AgentCore Runtime:

agentcore add agent \
  --type byo \
  --name my_agent \
  --code-location my_agent \
  --entrypoint main.py \
  --language Python \
  --framework Strands \
  --model-provider Bedrock
agentcore deploy

Invoke the deployed agent — interactive REPL or programmatic client:

sca client remote --arn <ARN> --region us-west-2

Your config.yaml never changed. Your agents never changed. You just moved from laptop to managed cloud infrastructure.

What this package gives you

🏭 create_app() — the core value

The real value of this package is a single factory function. AgentCore Runtime expects a specific ASGI app with /invocations and /ping endpoints, session-aware lifecycle management, event streaming, concurrency guards, and health reporting. create_app() handles all of that — you pass your YAML config and get a production-ready BedrockAgentCoreApp with zero knowledge of the runtime contract required:

from strands_compose_agentcore import create_app

app = create_app("config.yaml")  # that's it

Without this factory, you'd need to manually wire load_config, per-session load, the ASGI lifespan, session caching and teardown, event queue plumbing, streaming serialization, and concurrency guards. create_app() does all of that in one call.

🛠️ CLI for strands-compose streaming events

The AgentCore CLI provides create, add, deploy, status, logs, and more — we recommend it and don't replace or abstract any of it.

strands-compose-agentcore CLI tools dev and client use AnsiRenderer from strands-compose to render stream events with color, formatting, and progressive typewriter output. This is the only reason we ship our own CLI — we don't duplicate or replace the AgentCore CLI, we complement it for the streaming use case it doesn't cover.

📡 A client for your apps

AgentCoreClient is an async boto3 wrapper that streams SSE events from deployed agents. LocalClient (sync) and AsyncLocalClient (async, httpx) cover the local development server. All three embed cleanly into FastAPI, Django, Lambda, or background workers — one client instance, safe for concurrent multi-tenant use, with typed errors.

How you deploy

For individual developers and small teams, we recommend the AgentCore CLI. It handles project scaffolding, packaging, and deployment in a few commands. Use sca dev for local iteration, agentcore deploy to ship.

For enterprise teams, you likely have your own infrastructure-as-code (Terraform, CDK, CloudFormation) and CI/CD pipelines. In that case, create_app() is all you need from this package — build a Docker image with your main.py and config.yaml, push it to ECR, and let your pipeline update the agent runtime. Or ship as a CodeZip artifact to S3. The AgentCore CLI is optional — it's a convenient tool, not a requirement.

See Chapter 09 — Deployment Strategies for a deep dive on both paths.

How it works

┌─────────────────────────────────────────────────────────────┐
│  config.yaml                                                │  ← You write this
│  (models, agents, tools, orchestrations)                    │
├─────────────────────────────────────────────────────────────┤
│  strands-compose                                            │  ← Parses YAML,
│  (load_config, load)                                        │     resolves agents
├─────────────────────────────────────────────────────────────┤
│  strands-compose-agentcore       ◄── THIS PACKAGE           │  ← Wraps as ASGI app,
│  (app factory, CLI toolkit, AgentCoreClient)                │     CLI, client
├─────────────────────────────────────────────────────────────┤
│  AgentCore CLI + bedrock-agentcore SDK                      │  ← Project scaffold,
│  (agentcore create/deploy, BedrockAgentCoreApp)             │     deploy, ASGI server
├─────────────────────────────────────────────────────────────┤
│  AWS Bedrock AgentCore Runtime                              │  ← Managed compute
│  (per-session microVM, auto-scaling, CloudWatch)            │     (you deploy here)
└─────────────────────────────────────────────────────────────┘

Each layer does one thing. strands-compose parses your YAML and builds agents. This package wraps them as an ASGI app and provides the CLI glue. The AgentCore CLI and SDK handle project scaffolding, deployment, and the /invocations wire protocol. AgentCore Runtime runs it all on managed infrastructure. You only touch the top two layers.

Getting started

Install

pip install strands-compose-agentcore

This pulls in strands-compose and bedrock-agentcore automatically. The AgentCore CLI is a separate Node.js tool: npm install -g @aws/agentcore

Required files

Every agent needs three files:

config.yaml — your strands-compose agent definition:

models:
  default:
    provider: bedrock
    model_id: openai.gpt-oss-20b-1:0

agents:
  assistant:
    model: default
    system_prompt: "You are a helpful assistant."

entry: assistant

main.py — the entry script:

from pathlib import Path
from strands_compose_agentcore import create_app

app = create_app(Path(__file__).parent / "config.yaml")

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

pyproject.toml — declares dependencies for deployment:

[project]
name = "my-agent"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "strands-compose-agentcore",
]

The full workflow

# 1. Create an AgentCore project (AgentCore CLI)
agentcore create --name project --no-agent --skip-git
cd project

# 2. Create your agent files (main.py, config.yaml, pyproject.toml)
mkdir my_agent
# → Add the three files shown above to my_agent/

# 3. Test locally (dev server + REPL in one terminal)
sca dev --config my_agent/config.yaml

# 4. Register the agent and deploy to AWS
agentcore add agent \
  --type byo \
  --name my_agent \
  --code-location my_agent \
  --entrypoint main.py \
  --language Python \
  --framework Strands \
  --model-provider Bedrock
agentcore deploy

# 5. Connect to the live agent
sca client remote --arn <ARN> --region us-west-2

That's the entire journey — from an empty directory to a deployed, production-ready agent system. The dev command runs the exact same ASGI app that will run in production, so what works locally works deployed.

The CLI toolkit

Examples

Every example is self-contained with a README.md and everything you need to run it:

# Try the quick start example right now
sca dev --config examples/01_quick_start/config.yaml

Documentation

Deep dives into every component — architecture, API reference, deployment patterns, and advanced topics:

Developer setup

git clone https://github.com/strands-compose/bedrock-agentcore
cd bedrock-agentcore
uv run just install      # install deps + wire git hooks (run once after clone)

uv run just check        # lint + type check + security scan
uv run just test         # pytest with coverage
uv run just format       # auto-format (Ruff)

Re-install hooks after a fresh clone or if hooks stop running: uv run just install-hooks

See CONTRIBUTING.md for the full contribution guide, AGENTS.md for coding standards, and CHANGELOG.md for release history.

License

Apache-2.0 — see LICENSE.