Protocols: HTTP, MCP, A2A & AG-UI

AgentCore Runtime is framework- and protocol-agnostic: it doesn't care whether your agent is Strands, LangGraph, or hand-rolled, and it speaks four different wire contracts. The catch is that a single Runtime declares exactly one protocol mode, and AWS routes the container's listening port to match it. You don't run all four at once in one container — you pick the contract that fits the consumer.

Think of the protocol as the shape of the conversation at the container boundary, independent of the agent logic inside:

• HTTP — a request/response (or streaming) REST surface for apps and the AWS SDK. The default for "invoke my agent."
• MCP — your container is a Model Context Protocol server; clients call it as a tool provider over JSON-RPC.
• A2A — your container is an Agent-to-Agent peer that other agents discover and call, also JSON-RPC.
• AG-UI — an interactive event stream for rendering an agent's progress in a UI.

The protocol choice drives three concrete things: which port the container must listen on, which path it mounts the handler at, and what message format travels on the wire. Auth (SigV4 or OAuth 2.0) and the session model layer on top.

Here is the full comparison. Memorize the port-to-protocol mapping — a container listening on the wrong port for its declared mode simply won't receive traffic.

A few things to notice immediately:

• HTTP and AG-UI share port 8080. HTTP is the general-purpose request/response surface (plus optional streaming); AG-UI is the same port but oriented at interactive UI event streams.
• MCP and A2A both speak JSON-RPC, but they answer different questions. MCP exposes tools ("what can you do for me?"); A2A exposes an agent ("who are you and how do I delegate to you?").
• Discovery differs sharply. MCP clients enumerate tools via tool listing; A2A peers fetch a structured Agent Card from /.well-known/agent.json. HTTP and AG-UI have no built-in discovery contract.
• Auth is uniform across all four: every protocol accepts either AWS SigV4 (IAM-signed requests) or OAuth 2.0 (JWT bearer tokens). What differs is the failure response and the session header, covered later in this lesson.

Source for this contract: the Runtime service contract documentation (runtime-service-contract.html).

HTTP is the contract you get from BedrockAgentCoreApp and the one the AWS SDK's InvokeAgentRuntime data-plane call targets. The container runs on host 0.0.0.0, port 8080, platform ARM64.

Endpoints:

• POST /invocations — the primary entrypoint. Input is JSON; the response is either JSON (Content-Type: application/json, e.g. {"response":"...","status":"success"}) or Server-Sent Events (Content-Type: text/event-stream, with lines of the form data: {...}) when you stream.
• GET /ping — health check. Returns HTTP 200 with body {"status": "<Healthy|HealthyBusy>", "time_of_last_update": <unix_ts>}.
• /ws — optional WebSocket on the same port 8080, established via an HTTP-Upgrade handshake (101); carries text and binary; the session is bound via the X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header.

You can exercise the exact cloud contract locally with curl — there is nothing AWS-specific about the wire format:

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

Auth response semantics differ by auth mode — this is the cleanest way to tell, from a 4xx alone, how an agent is protected:

# OAuth-protected agent, missing/invalid token:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"

# SigV4 (IAM)-protected agent, unauthorized caller:
HTTP/1.1 403 Forbidden
ACCESS_DENIED            # note: NO WWW-Authenticate header

An OAuth agent returns 401 + a WWW-Authenticate: Bearer … header pointing at its protected-resource metadata; a SigV4 agent returns 403 + ACCESS_DENIED with no WWW-Authenticate.

When you declare the MCP protocol, your container becomes a Model Context Protocol server that MCP clients call as a tool provider. The contract is specific:

• Port 8000, single endpoint POST /mcp, messages are JSON-RPC.
• Transport must be streamable-http. This is non-negotiable — the older stdio transport is for local processes, not a hosted Runtime; SSE-only transport is not the contract here.
• Default to stateless mode: stateless_http=True. Stateless is the right default for a horizontally-scaled, session-isolated Runtime where any microVM can answer any request.
• The platform always injects and returns an Mcp-Session-Id. Your server must accept the platform-generated ID — it must not reject or override it. This is the single most common mistake when porting a local MCP server: a server that insists on minting its own session ID will fight the platform.

The minimal hosted MCP server, using the official mcp SDK's FastMCP:

from mcp.server.fastmcp import FastMCP

# Bind 0.0.0.0; stateless is the Runtime default.
mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    # streamable-http is REQUIRED; served at /mcp on port 8000.
    mcp.run(transport="streamable-http")

When do you need stateful mode (stateless_http=False)? Only when the MCP interaction is genuinely multi-turn at the protocol level — specifically the two MCP capabilities that require the server to hold a live session and call back to the client:

• Elicitation — the server pauses a tool call to prompt the client (and through it, the user) for additional input mid-flight.
• Sampling — the server asks the client's LLM to generate a completion on its behalf.

If you use neither, stay stateless. Stateful mode trades scale-out simplicity for the ability to keep a conversation pinned, so reach for it only when elicitation or sampling forces your hand.

The Agent-to-Agent (A2A) protocol turns your Runtime into a peer that other agents discover and delegate to — the multi-agent building block. The contract:

• Port 9000, mounted at / (root), messages are JSON-RPC 2.0.
• Discovery via Agent Cards served at /.well-known/agent.json — a structured document describing the agent's identity, skills, and how to call it. This is the A2A analog of MCP's tool listing.

The SDK ships a helper, serve_a2a, in the bedrock-agentcore[a2a] extra. Install the extra, wrap your framework's executor, and call serve_a2a — it wires up the Agent Card, the JSON-RPC surface, and /ping for you:

pip install 'bedrock-agentcore[a2a]'

from strands import Agent
from strands.a2a import StrandsA2AExecutor
from bedrock_agentcore.runtime import serve_a2a

agent = Agent(
    model="us.anthropic.claude-sonnet-4-20250514",
    system_prompt="You are a helpful assistant.",
)

# Serves /.well-known/agent.json + JSON-RPC + /ping on port 9000.
serve_a2a(StrandsA2AExecutor(agent), port=9000)

That single serve_a2a call replaces the boilerplate of hand-building the Agent Card endpoint and the JSON-RPC router. Note the model ID in the example is illustrative — claude-sonnet-4-20250514 is now a legacy ID; pin a current model ID from the live model catalog rather than copying this one verbatim.

The practical pattern: deploy reusable specialist agents as A2A Runtimes, publish their Agent Cards, and let an orchestrator agent discover and call them as peers — composability without hard-coding endpoints.

AG-UI (Agent-to-User-Interface) is the protocol for interactive UI rendering. It shares port 8080 with HTTP and mounts at /invocations (SSE) plus the optional /ws WebSocket. The wire format is event streams — a sequence of UI-oriented events (tool calls, partial outputs, state updates) that a front end consumes over SSE or WebSocket to render an agent's progress live. Where plain HTTP streaming gives you raw data: chunks, AG-UI is structured for driving a UI surface.

Discovery — three different stories:

Auth — uniform options, different mechanics. Every protocol accepts SigV4 (IAM-signed requests, e.g. via InvokeAgentRuntime) or OAuth 2.0 (a JWT bearer token). The differences show up at the edges:

• Failure response: an OAuth agent answers an unauthenticated call with 401 + WWW-Authenticate: Bearer …; a SigV4 agent answers an unauthorized call with 403 + ACCESS_DENIED and no WWW-Authenticate header.
• Session header by protocol — the identifier that pins a caller to a microVM differs:

MCP is the odd one out: it uses the MCP-native Mcp-Session-Id header (the one the platform generates and you must accept), while the other three share the X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header.