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.
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 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.
is AWS's managed set of these harness pieces. You bring the agent (built with , LangGraph, or anything); AgentCore hosts, secures, and scales it. The components, composable and framework-agnostic:
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
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 wrapperfrom strands import Agent # the framework (brain)
app = BedrockAgentCoreApp()
agent = Agent()
@app.entrypoint # every request lands heredefinvoke(payload):
user_message = payload.get("prompt", "Hello! How can I help you today?")
result = agent(user_message) # this one call IS the entire agent loopreturn {"result": result.message}
if __name__ == "__main__":
app.run() # `agentcore dev` runs exactly this
To give the agent a real capability, add a tool. The @tool decorator turns a function into something the model can call, and the docstring is read by the model to decide when to call it and what to pass (Strands parses the first paragraph as the description and the Args: section as parameter docs):
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent, tool
app = BedrockAgentCoreApp()
@tooldefword_count(text: str) -> str:
"""Count the number of words in a piece of text.
Args:
text: The text to count words in.
"""returnf"The text has {len(text.split())} words."
agent = Agent(tools=[word_count]) # add/remove tools here = change abilities@app.entrypointdefinvoke(payload):
user_message = payload.get("prompt", "Hello!")
result = agent(user_message)
return {"result": result.message}
if __name__ == "__main__":
app.run()
Design note: a tool's return value is read by the model. Return recoverable strings on failure ("Error: no city 'X'. Ask the user to rephrase.") rather than raising an unhandled exception, which crashes the turn. Prebuilt tools are available too: pip install strands-agents-tools, then from strands_tools import calculator and pass it in Agent(tools=[calculator]).
4. Test locally (free) before deploying
cd MyAgent
agentcore dev # hot-reload server on localhost:8080 + browser inspector
agentcore dev "count the words here"# invoke the local agent
5. Deploy to AWS
agentcore deploy --plan # dry run: preview the infra
agentcore deploy # provision for real
Under the hood this reads agentcore.json, packages app/ (CodeZip or Docker) built for ARM64/Graviton (required by the runtime; the CLI handles the arch), uses CDK to synthesize CloudFormation provisioning the Runtime + an IAM execution role + S3 staging, and returns an Agent ARN.
6. Invoke
agentcore invoke "Tell me a joke" --stream
agentcore invoke --session-id my-session "and another"# continuity across calls
From application code (verified verbatim pattern):
import json, uuid, boto3
client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
agentRuntimeArn="<AGENT_ARN>", # from `agentcore status`
runtimeSessionId=str(uuid.uuid4()), # must be 33+ chars; uuid4 is 36
payload=json.dumps({"prompt": "Tell me a joke"}).encode(),
qualifier="DEFAULT",
)
content = []
for chunk in response.get("response", []):
content.append(chunk.decode("utf-8"))
print(json.loads("".join(content)))
7. Add production harness components
Snap pieces in with agentcore add, then re-deploy (run agentcore add --help for the full list):
agentcore remove all # mark resources for deletion
agentcore deploy # apply teardown via CloudFormation
Path B - Deploy an agent you already have
You already wrote an agent (Strands, LangGraph, OpenAI Agents, or plain Python). Two ways to ship it.
Option B1 - Wrap it with the SDK (fewest lines)
AgentCore Runtime just needs your agent behind an entrypoint. Wrap your existing agent object:
# main.py - the only new file you writefrom bedrock_agentcore import BedrockAgentCoreApp
from my_agent import agent # <-- your already-built agent (any framework)
app = BedrockAgentCoreApp()
@app.entrypointdefinvoke(payload):
result = agent(payload.get("prompt", ""))
return {"result": result.message ifhasattr(result, "message") elsestr(result)}
if __name__ == "__main__":
app.run()
pip install bedrock-agentcore
Then deploy it. Easiest: agentcore create a project (Path A) and paste your logic into the generated entrypoint - you reuse all of Path A's deploy/invoke tooling. Alternatively, the legacy starter toolkit points straight at an existing file:
Option B2 - Full container control (no SDK, no CLI)
For maximum control, meet the runtime contract yourself: an HTTP server exposing /invocations (POST) and /ping (GET) on port 8080, packaged as an ARM64 Docker image. This is the verified official path.
Runtime contract summary: platform linux/arm64, endpoints /invocations POST + /ping GET, port 8080, image in ECR, and Strands agents need AWS credentials at runtime.
Gotchas (all verified)
Wrong CLI: agentcore configure/launch = legacy pip toolkit; the new npm CLI uses create/deploy. Don't mix their command names.
CDK not bootstrapped: Path A agentcore deploy fails until you run cdk bootstrap once per account/region.
Model access denied: enable the Claude model in the Bedrock console, in the same region as your deploy.
Payload shape mismatch: an SDK/BedrockAgentCoreApp entrypoint reads payload.get("prompt") so you send {"prompt": ...}; the custom FastAPI contract reads request.input.get("prompt") so you send {"input": {"prompt": ...}}. Match them.
runtimeSessionId too short: it must be 33+ characters (str(uuid.uuid4()) is 36).
Not ARM64: containers must be linux/arm64 or the runtime rejects them.
result.message is a dict ({"role": ..., "content": [{"text": ...}]}), not a plain string. Use result.message for JSON responses, or str(result) / result.message["content"][0]["text"] for plain text.
Cost: deployed runtimes bill until torn down. Path A: agentcore remove all && agentcore deploy. Path B: stop_runtime_session, then delete the runtime and ECR repo.
