Aws Harness

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.

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

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?

Prerequisites

Both paths need:

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

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

2. Create the project

bashCopy code
# 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:

It generates:

Copy code
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:

pythonCopy code
from bedrock_agentcore import BedrockAgentCoreApp   # the harness wrapper
from strands import Agent                           # the framework (brain)

app = BedrockAgentCoreApp()
agent = Agent()

@app.entrypoint                       # every request lands here
def invoke(payload):
    user_message = payload.get("prompt", "Hello! How can I help you today?")
    result = agent(user_message)      # this one call IS the entire agent loop
    return {"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):

pythonCopy code
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent, tool

app = BedrockAgentCoreApp()

@tool
def word_count(text: str) -> str:
    """Count the number of words in a piece of text.

    Args:
        text: The text to count words in.
    """
    return f"The text has {len(text.split())} words."

agent = Agent(tools=[word_count])     # add/remove tools here = change abilities

@app.entrypoint
def invoke(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

bashCopy code
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

bashCopy code
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

bashCopy code
agentcore invoke "Tell me a joke" --stream
agentcore invoke --session-id my-session "and another"   # continuity across calls

From application code (verified verbatim pattern):

pythonCopy code
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):

bashCopy code
agentcore add memory --name MyMemory --strategies SEMANTIC       # long-term recall
agentcore add agent  --name SecondAgent --framework Strands       # multi-agent
# also available: identity, target (gateway), evaluator
agentcore deploy                                                  # provision the additions

Observability is built in:

bashCopy code
agentcore logs           # stream runtime logs
agentcore traces list    # inspect steps, tokens, latency

8. Clean up (do NOT skip - this costs money)

bashCopy code
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:

pythonCopy code
# main.py - the only new file you write
from bedrock_agentcore import BedrockAgentCoreApp
from my_agent import agent          # <-- your already-built agent (any framework)

app = BedrockAgentCoreApp()

@app.entrypoint
def invoke(payload):
    result = agent(payload.get("prompt", ""))
    return {"result": result.message if hasattr(result, "message") else str(result)}

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

bashCopy code
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:

bashCopy code
pip install bedrock-agentcore-starter-toolkit
agentcore configure --entrypoint main.py    # generates IAM role, ECR repo, Dockerfile
agentcore launch                             # build + deploy
agentcore invoke '{"prompt": "hello"}'       # note: JSON string argument

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.

1. Project setup (uv):

bashCopy code
mkdir my-custom-agent && cd my-custom-agent
uv init --python 3.11
uv add fastapi 'uvicorn[standard]' pydantic httpx strands-agents

2. agent.py (FastAPI meeting the runtime contract):

pythonCopy code
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dict, Any
from datetime import datetime
from strands import Agent

app = FastAPI(title="Strands Agent Server", version="1.0.0")
strands_agent = Agent()   # replace with your prepared agent

class InvocationRequest(BaseModel):
    input: Dict[str, Any]

class InvocationResponse(BaseModel):
    output: Dict[str, Any]

@app.post("/invocations", response_model=InvocationResponse)
async def invoke_agent(request: InvocationRequest):
    user_message = request.input.get("prompt", "")
    if not user_message:
        raise HTTPException(status_code=400, detail="No 'prompt' in input.")
    result = strands_agent(user_message)
    return InvocationResponse(output={
        "message": result.message,
        "timestamp": datetime.utcnow().isoformat(),
    })

@app.get("/ping")
async def ping():
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8080)

3. Dockerfile (ARM64 - required):

dockerfileCopy code
FROM --platform=linux/arm64 ghcr.io/astral-sh/uv:python3.11-bookworm-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-cache
COPY agent.py ./
EXPOSE 8080
CMD ["uv", "run", "uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "8080"]

4. Build for ARM64, push to ECR:

bashCopy code
docker buildx create --use
aws ecr create-repository --repository-name my-strands-agent --region us-west-2
aws ecr get-login-password --region us-west-2 \
  | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-west-2.amazonaws.com
docker buildx build --platform linux/arm64 \
  -t <account-id>.dkr.ecr.us-west-2.amazonaws.com/my-strands-agent:latest --push .

5. Create the runtime (boto3, bedrock-agentcore-control):

pythonCopy code
import boto3

client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
    agentRuntimeName="strands_agent",
    agentRuntimeArtifact={"containerConfiguration": {
        "containerUri": "<account-id>.dkr.ecr.us-west-2.amazonaws.com/my-strands-agent:latest"
    }},
    networkConfiguration={"networkMode": "PUBLIC"},
    roleArn="arn:aws:iam::<account-id>:role/AgentRuntimeRole",
)
print(response["agentRuntimeArn"], response["status"])

6. Invoke (note the input wrapper matches the FastAPI contract):

pythonCopy code
import boto3, json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_agent_runtime(
    agentRuntimeArn="<AGENT_RUNTIME_ARN>",
    runtimeSessionId="a" * 40,   # must be 33+ chars
    payload=json.dumps({"input": {"prompt": "Explain machine learning simply"}}),
    qualifier="DEFAULT",
)
print(json.loads(response["response"].read()))

7. Stop the session to avoid runaway cost:

pythonCopy code
import boto3
boto3.client("bedrock-agentcore", region_name="us-west-2").stop_runtime_session(
    agentRuntimeArn="<AGENT_RUNTIME_ARN>",
    runtimeSessionId="a" * 40,
    qualifier="DEFAULT",
)

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.

Resources

• AgentCore CLI (new): https://github.com/aws/agentcore-cli
• Get started with the AgentCore CLI: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html
• Deploy without the CLI (custom/BYO agent): https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/getting-started-custom.html
• Bedrock AgentCore Python SDK: https://github.com/aws/bedrock-agentcore-sdk-python
• Strands custom tools (@tool): https://strandsagents.com/docs/user-guide/concepts/tools/custom-tools/
• Official samples: https://github.com/awslabs/amazon-bedrock-agentcore-samples