Your First Agent with BedrockAgentCoreApp

AgentCore Runtime hosts a container that speaks a known HTTP contract — not a framework. So the only thing the Python SDK has to do is turn your function into that contract. The package is bedrock-agentcore, and the wrapper is BedrockAgentCoreApp.

Here is a complete, runnable agent. Count the load-bearing lines:

from bedrock_agentcore.runtime import BedrockAgentCoreApp   # 1. import
from strands import Agent

app = BedrockAgentCoreApp()                                 # 2. instantiate
agent = Agent()

@app.entrypoint                                             # 3. decorate one function
def invoke(payload):
    result = agent(payload.get("prompt", "Hello"))
    return {"result": result.message}

if __name__ == "__main__":
    app.run()                                               # 4. serve

That's the "four lines to deploy" framing: (1) import BedrockAgentCoreApp, (2) app = BedrockAgentCoreApp(), (3) decorate a function with @app.entrypoint, (4) app.run(). Everything between the decorator and the return is your code — Strands here, but it could be LangGraph, CrewAI, or no framework at all. The decorator is the seam between AWS's managed HTTP server and your agent object.

Install it the usual way (Python ≥ 3.10):

pip install bedrock-agentcore

The import path is from bedrock_agentcore.runtime import BedrockAgentCoreApp. You'll see some examples use the shorter from bedrock_agentcore import BedrockAgentCoreApp — both resolve to the same class; prefer the explicit .runtime path.

BedrockAgentCoreApp is a thin Starlette/Uvicorn ASGI wrapper. It does not add an agent framework, an orchestration loop, or any opinion about your model. Its entire job is to translate your decorated function into the HTTP service contract that AgentCore Runtime expects, so AWS can route traffic to your container.

Concretely, the SDK wires up:

• POST /invocations — the primary endpoint. Your @app.entrypoint function runs here. Input is JSON; output is JSON (or a stream — see below).
• GET /ping — the health check the platform polls.
• /ws (optional WebSocket) on the same port.
• Session headers — it reads and echoes the HTTP session header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id so related invocations land on the same microVM.
• Streaming — an async generator entrypoint is automatically served as Server-Sent Events (text/event-stream).
• Async task tracking — @app.async_task / app.add_async_task(...) keep the session alive while background work runs.

The contract it implements is fixed: Host 0.0.0.0, Port 8080, Platform ARM64 for the HTTP protocol. You do not invent these — the SDK and the platform agree on them so your local server and the cloud runtime are byte-for-byte the same surface.

Because it's just an ASGI app, there's no magic to fear: app.run() starts Uvicorn, binds the port, and serves your two endpoints.

Your entrypoint receives the request body as a payload dict — the parsed JSON from the POST /invocations call. The convention across the AWS samples is a prompt key, read defensively:

@app.entrypoint
def invoke(payload):
    user_prompt = payload.get("prompt", "Hello")
    result = agent(user_prompt)
    return {"result": result.message}

The payload is your schema — prompt is a convention, not a requirement. You can send and read any JSON shape your agent expects.

The optional second argument: RequestContext. Add a second parameter and the SDK injects request metadata that isn't part of the body:

@app.entrypoint
def invoke(payload, context):
    session_id = context.session_id                       # the runtime session ID
    auth_header = context.request_headers.get("authorization")  # e.g. a bearer token
    result = agent(payload.get("prompt", "Hello"))
    return {"result": result.message, "session": session_id}

RequestContext exposes:

Returning a result. Return a JSON-serializable object — the SDK serializes it as the application/json response body. The samples use {"result": ...}; the raw HTTP contract documents shapes like {"response": "...", "status": "success"}. Either is fine as long as it's JSON your caller can parse.

Streaming is one decorator change. Make the entrypoint an async generator and the SDK automatically serves Content-Type: text/event-stream; every yield becomes one SSE data: event:

@app.entrypoint
async def handler(request: dict):
    agent = Agent()
    async for event in agent.stream_async(request.get("prompt", "")):
        yield event        # each yield -> one `data: {...}` SSE line

No manual SSE framing, no Content-Type juggling — the wrapper detects the generator and switches transport for you.

The GET /ping health contract. The platform polls /ping to decide whether your container is alive and whether to keep a session warm. The SDK answers it by default, but you can customize it:

from bedrock_agentcore.runtime import BedrockAgentCoreApp, PingStatus

app = BedrockAgentCoreApp()

@app.ping
def health():
    return PingStatus.HEALTHY        # or PingStatus.HEALTHY_BUSY

GET /ping must return HTTP 200 with a body like:

{ "status": "Healthy", "time_of_last_update": 1715000000 }

status is Healthy (ready) or HealthyBusy (busy with async work — this keeps the session alive past the idle timeout). time_of_last_update is a Unix-seconds timestamp and is REQUIRED: if you omit it, the idle timeout fires even while you're reporting HealthyBusy, and the platform kills the session mid-task.

app.run() starts the Uvicorn server. Locally it serves on http://localhost:8080; in a container it binds 0.0.0.0:8080 (the address AgentCore Runtime routes to). You can pass port= to change the local port if 8080 is taken.

The killer feature for development: the server you run locally implements the exact same HTTP contract as the deployed cloud runtime. So you test the real contract with plain curl — no AWS, no deploy, no auth:

# Terminal 1: run the agent
python my_agent.py

# Terminal 2: hit the primary endpoint
curl -X POST http://localhost:8080/invocations \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"What is the weather?"}'

# And the health endpoint the platform polls
curl http://localhost:8080/ping

A healthy /ping returns something like {"status": "Healthy", "time_of_last_update": 1715000000} with HTTP 200, and /invocations returns your JSON, e.g. {"result": "..."}.

One arch caveat for packaging. Runtime executes on AWS Graviton (ARM64). The deploy toolchains (CodeZip and the CLIs) handle the architecture for you, but if you hand-build a container yourself it MUST be linux/arm64:

docker buildx build --platform linux/arm64 -t my-agent .

A wrong-arch (amd64) image is one of the most common deploy failures — it runs fine on your laptop and silently fails in the cloud. Local curl testing happens on your machine's native arch and is unaffected; the ARM64 requirement bites at deploy time.

Once you've validated the contract locally, the cloud invocation is the same request through a different door. After deploy you get an agent runtime ARN, and you call the data-plane InvokeAgentRuntime API (boto3 client name bedrock-agentcore, method invoke_agent_runtime) with SigV4 auth:

import json, uuid, boto3

client = boto3.client("bedrock-agentcore")              # data plane
resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-XXXX",
    runtimeSessionId=str(uuid.uuid4()),                 # >= 33 chars; reuse for context/affinity
    payload=json.dumps({"prompt": "Tell me a joke"}).encode(),
    qualifier="DEFAULT",                                 # endpoint alias
)
print(json.loads("".join(c.decode("utf-8") for c in resp.get("response", []))))

Notice the symmetry with the local curl: the body you sent as -d '{"prompt":"..."}' is exactly the payload here. The new parts are AWS-side concerns — the ARN, the runtimeSessionId (commonly cited as needing at least 33 characters — a UUID's 36 fits; confirm the current minimum in the InvokeAgentRuntime API reference), and the qualifier selecting an endpoint alias such as DEFAULT.

One gotcha to file away: if your agent uses OAuth inbound auth, you cannot use the AWS SDK to call InvokeAgentRuntime — you make a raw HTTPS request with the bearer token instead. SigV4-authenticated agents use the boto3 client above.