/aws-harness

name: aws-harness
description: Build a new AI agent on AWS and deploy it easily, OR wrap and deploy an agent you already have, using the Amazon Bedrock AgentCore harness. Explains what an "agent harness" is (the runtime scaffolding around a model - agent loop, tool execution, memory, identity, observability), then gives two fully-working, verified paths - (A) scaffold + ship a new agent with the AgentCore CLI (create/dev/deploy/invoke), and (B) deploy a prepared agent (Strands, LangGraph, or custom) via the SDK wrapper or a FastAPI + Docker + ECR container. Every import and command is verified against official AWS/Strands docs. Use when the goal is to create, wrap, or deploy an agent on AWS AgentCore. Triggers on agent harness, AWS harness, AgentCore, AgentCore CLI, agentcore create, agentcore deploy, deploy agent on AWS, bring your own agent, Bedrock AgentCore runtime, serverless agent.

AWS Agent Harness (Bedrock AgentCore)

Take an AI agent from an empty folder - or from code you already have - to a live, serverless endpoint on AWS. Every command and import below is verified against official docs (sources at the bottom).

> Companion skill: [aws-strands](../aws-strands/SKILL.md) is the agent framework (the "brain" - how to write the agent). **This** skill is the harness: how to run and deploy that agent on AWS. Write with Strands, ship with AgentCore.

What "harness" means (read this first)

A language model, alone, only turns text into text. It cannot call an API, remember yesterday, run code, or browse the web. The **harness** is the scaffolding around the model that makes it act:

• **Agent loop** - call the model, read the tool it wants, run that tool, feed the result back, repeat until done. The model *decides*; the harness *executes and loops*.
• **Tool execution, memory, identity, guardrails, sandboxing, observability** - everything that makes it useful and production-safe.

**Amazon Bedrock AgentCore** is AWS's managed set of these harness pieces. You bring the agent (built with [Strands](../aws-strands/SKILL.md), LangGraph, or anything); AgentCore hosts, secures, and scales it. The components, composable and framework-agnostic:

| Component | What it gives you | |---|---| | **Runtime** | Serverless, isolated agent execution (any framework, any model) | | **Memory** | Short-term (session) + long-term (cross-session) memory | | **Identity** | Let the agent act on behalf of a user (Cognito, Okta, Google, EntraID, OAuth) | | **Gateway** | Turn APIs / Lambda functions into agent tools (MCP) | | **Code Interpreter** | Sandboxed code execution | | **Browser** | Managed headless browser for web tasks | | **Observability** | Tracing, logs, metrics (CloudWatch / OpenTelemetry) |

You adopt these one at a time via `agentcore add` (Path A) or the SDK/API (Path B) - not all-or-nothing.

Which path are you on?

| | You want to... | Go to | |---|---|---| | **Path A** | Build a NEW agent from scratch, easiest possible | [Path A](#path-a---build-and-deploy-a-new-agent-cli) - the AgentCore CLI | | **Path B** | Deploy an agent you ALREADY have (Strands / LangGraph / anything) | [Path B](#path-b---deploy-an-agent-you-already-have) - wrap + ship |

Prerequisites

**Both paths need:**

| Requirement | Why | |---|---| | AWS account + `aws configure` credentials | Everything below provisions real, billable infrastructure in *your* account. | | Bedrock model access | Enable a Claude model (for example Claude Sonnet 4) in the Bedrock console, in your target region, before the agent can call it. | | Python 3.10+ | The agent code is Python. |

**Path A also needs:** Node.js 20+ (the CLI is an npm package) and AWS CDK (`npm i -g aws-cdk`, then `cdk bootstrap` once per account/region - the CLI deploys via CDK).

**Path B (container option) also needs:** Docker with `buildx` (for ARM64 images).

---

Path A - Build and deploy a new agent (CLI)

The AgentCore CLI scaffolds a working agent, runs it locally, and deploys it.

> Two CLIs exist. Use the **new** one: `@aws/agentcore` (npm), commands `create`/`dev`/`deploy`/`invoke`. The older `bedrock-agentcore-starter-toolkit` (pip) uses `configure`/`launch` and is marked legacy - it is handy for Path B (wrapping an existing file), shown later.

1. Install

npm install -g @aws/agentcore
agentcore --help

2. Create the project

# interactive wizard:
agentcore create

# or non-interactive:
agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none

# or accept all defaults (Python, Strands, Bedrock, no memory):
agentcore create --name MyAgent --defaults

Each flag shapes the agent:

| Flag | Verified options | Meaning | |---|---|---| | `--framework` | `Strands`, `LangChain_LangGraph`, `GoogleADK`, `OpenAIAgents` | The brain. Strands is AWS-native and simplest. | | `--model-provider` | `Bedrock`, `Anthropic`, `OpenAI`, `Gemini` | Bedrock = Claude inside AWS (no external key). Others call out with an API key. | | `--memory` | `none`, `shortTerm`, `longAndShortTerm` | none = amnesiac; shortTerm = within a session; longAndShortTerm = across sessions. | | `--protocol` | `HTTP`, `MCP`, `A2A` | HTTP for normal request/response; MCP to expose the agent as tools; A2A for agent-to-agent. | | `--build` | `CodeZip`, `Container` | CodeZip = zip to S3, no Docker. Container = Docker image, for custom system deps. |

It generates:

MyAgent/
  agentcore/
    agentcore.json      # project + agent config
    aws-targets.json    # AWS account / region
    .env.local          # local secrets (gitignored)
  app/
    MyAgent/
      main.py           # your starter agent, in the chosen framework
      pyproject.toml
  README.md

3. The agent code (this is all an AgentCore agent is)

The scaffolded `main.py` follows this verified minimal shape - a framework agent wrapped by the harness:

from bedrock_agentcore import BedrockAgentCoreApp   # the harness wrapper
from strands import Ag