Skip to content
BrPy

Agent-to-Agent (A2A) Protocol: Comprehensive Technical Guide

The open Agent2Agent (A2A) protocol on AWS: agent cards, JSON-RPC methods, tasks and messages, Strands A2A servers and clients, and hosting A2A agents on Amazon Bedrock AgentCore Runtime.

A2A (Agent2Agent) is an open protocol that lets agents built with different frameworks, by different teams, discover one another and collaborate over HTTP. Google introduced it in April 2025; it is now developed as a Linux Foundation project. On AWS, A2A is supported by Amazon Bedrock AgentCore Runtime and by the Strands Agents SDK.

Verified against: bedrock-agentcore 1.26.0 and strands-agents 1.64.0 (checked 2026-11-19), with the a2a extras installed. The wire examples follow A2A protocol version 0.3, which those SDKs use by default.

Specification: https://a2a-protocol.org/ Python SDK: a2a-sdk (installed by the a2a extras of Strands and AgentCore)

Bedrock Agents (Classic) does not implement A2A. Its multi-agent collaboration uses a built-in supervisor/collaborator mechanism, and invoke_agent has no A2A parameters. Earlier versions of this page described an invented “A2A message envelope” for Bedrock Agents; that has been removed.


  1. Introduction to A2A Protocol
  2. Core Concepts
  3. Protocol Specification
  4. Building an A2A Server with Strands
  5. Hosting A2A Agents on AgentCore Runtime
  6. Calling A2A Agents
  7. Other Frameworks
  8. Security
  9. Best Practices

A2A complements MCP. MCP connects an agent to tools and data; A2A connects an agent to other agents that have their own reasoning, state and long-running work.

BenefitDescription
Framework interoperabilityA Strands agent can delegate to a LangGraph or Google ADK agent without knowing how it is built
DiscoveryEach agent publishes an agent card describing its skills, endpoint and auth requirements
Long-running workWork is modelled as tasks with states, streaming updates and optional push notifications
Opaque agentsAgents share messages and artefacts, not internal memory, prompts or tools
Standard web stackJSON-RPC 2.0 over HTTPS, Server-Sent Events for streaming, standard auth schemes

Any framework with an a2a-sdk AgentExecutor can be served over A2A. Strands ships StrandsA2AExecutor; Google ADK and LangGraph have their own A2A integrations; AgentCore’s serve_a2a hosts any of them.

  • A central assistant delegating to department-owned agents
  • Cross-organisation workflows where each party runs its own agent
  • Gradual migration: wrap an existing agent in A2A and call it from new code

An agent card is a JSON document served at /.well-known/agent-card.json (A2A 0.3; earlier drafts used /.well-known/agent.json). An example as served from AgentCore Runtime:

{
"name": "Research Agent",
"description": "Researches a topic and returns sourced bullet points.",
"version": "1.0.0",
"url": "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/<url-encoded-runtime-arn>/invocations/",
"protocolVersion": "0.3.0",
"preferredTransport": "JSONRPC",
"capabilities": { "streaming": true },
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"skills": [
{
"id": "research",
"name": "Topic research",
"description": "Finds and summarises sources on a topic",
"tags": ["research"]
}
]
}

Cards can also declare securitySchemes / security (for example OAuth 2.0 bearer tokens) so that clients know how to authenticate.

A message is a turn from a user (the calling agent or app) or an agent, made of parts:

{
"role": "user",
"messageId": "6f1b2c1e-1d1a-4d3e-9c1e-4c8a4b2b9e10",
"parts": [
{ "kind": "text", "text": "Summarise the attached report" },
{ "kind": "file", "file": { "uri": "https://example.com/report.pdf", "mimeType": "application/pdf" } },
{ "kind": "data", "data": { "audience": "board", "maxWords": 200 } }
]
}
ObjectPurpose
MessageA single turn (role, parts, messageId, optional contextId / taskId)
TaskA unit of work with an id, contextId, status (state + optional message), history and artifacts
ArtifactAn output produced by the task (artifactId, name, parts)
Status / artifact update eventsStreamed progress (status-update, artifact-update) during message/stream

Task states: submitted, working, input-required, auth-required, completed, canceled, failed, rejected, unknown.


Requests are JSON-RPC 2.0 over HTTP POST to the agent’s URL.

FieldMeaning
jsonrpcAlways "2.0"
idRequest ID, echoed in the response
methodOne of the methods below
paramsMethod parameters; for message/send a message object with role, parts and messageId
FieldMeaning
params.message.contextIdGroups related tasks into one conversation
params.message.taskIdContinue an existing task (for example after input-required)
params.configuratione.g. acceptedOutputModes, blocking, historyLength, pushNotificationConfig
params.metadataFree-form metadata

Methods (A2A 0.3):

MethodPurpose
message/sendSend a message; returns a Task or a Message
message/streamSame, but streams task status and artefact updates over SSE
tasks/getFetch a task’s current state, history and artefacts
tasks/cancelCancel a running task
tasks/resubscribeRe-attach to a task’s event stream
tasks/pushNotificationConfig/set · get · list · deleteManage webhook push notifications for long tasks
agent/getAuthenticatedExtendedCardFetch a richer card after authenticating
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{ "kind": "text", "text": "What is 101 * 11?" }],
"messageId": "12345678-1234-1234-1234-123456789012"
}
}
}
{
"jsonrpc": "2.0",
"id": "req-001",
"result": {
"kind": "task",
"id": "task-7c1",
"contextId": "ctx-42",
"status": { "state": "completed" },
"artifacts": [
{
"artifactId": "a-1",
"name": "agent_response",
"parts": [{ "kind": "text", "text": "101 × 11 = 1111" }]
}
]
}
}

For long-running tasks, a client can register a webhook with tasks/pushNotificationConfig/set; the server then POSTs task updates to it. Errors use standard JSON-RPC error objects (code, message, optional data); A2A reserves codes such as -32001 (task not found) and -32002 (task not cancelable).


Terminal window
pip install "strands-agents[a2a]==1.64.0"
from strands import Agent, tool
from strands.multiagent.a2a import A2AServer
@tool
def add_numbers(a: int, b: int) -> int:
"""Return the sum of two numbers.
Args:
a: First number.
b: Second number.
"""
return a + b
agent = Agent(
model="us.anthropic.claude-sonnet-5-5",
name="Calculator Agent",
description="Performs arithmetic.",
tools=[add_numbers],
)
# Serves JSON-RPC at / and the agent card at /.well-known/agent-card.json
A2AServer(agent=agent, host="0.0.0.0", port=9000).serve()

Test it:

Terminal window
curl -s http://localhost:9000/.well-known/agent-card.json | jq .
curl -s -X POST http://localhost:9000/ -H "Content-Type: application/json" -d '{
"jsonrpc": "2.0", "id": "1", "method": "message/send",
"params": {"message": {"role": "user", "messageId": "m-1",
"parts": [{"kind": "text", "text": "what is 101 * 11?"}]}}
}' | jq .

A2AServer builds the agent card from the agent’s name, description and tools; pass skills=[...] (a list of a2a.types.AgentSkill) to describe skills explicitly, and http_url= when the server sits behind a proxy so the card advertises the public URL.


AgentCore Runtime acts as a transparent proxy for A2A: JSON-RPC payloads sent with InvokeAgentRuntime are passed to your container unchanged, while AgentCore adds session isolation and SigV4 or OAuth authentication.

Container contract for A2A: listen on 0.0.0.0:9000, serve JSON-RPC at / (POST), the agent card at /.well-known/agent-card.json (GET) and health at /ping; build for ARM64. serve_a2a from the AgentCore SDK does all of this:

# pip install "bedrock-agentcore[a2a]" "strands-agents[a2a]"
from bedrock_agentcore.runtime import serve_a2a
from strands import Agent
from strands.multiagent.a2a import StrandsA2AExecutor
agent = Agent(
model="us.anthropic.claude-sonnet-5-5",
name="Research Agent",
description="Researches a topic and returns sourced bullet points.",
)
if __name__ == "__main__":
serve_a2a(StrandsA2AExecutor(agent))

Deploy with the AgentCore CLI. The a2a-python-strands template creates a Strands agent that speaks A2A, and the runtime is registered with protocol: A2A (port 9000). To serve your own code, such as the serve_a2a file above, use agentcore add runtime --name researcher --language python --protocol A2A and put the file in app/researcher/ as main.py:

Terminal window
agentcore create --name A2AProject --template a2a-python-strands
cd A2AProject
agentcore dev # run locally; --mode browser opens the Agent Inspector
agentcore deploy

Or, with boto3, set the protocol on the runtime:

import boto3
control = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
control.create_agent_runtime(
agentRuntimeName="research_agent",
agentRuntimeArtifact={"containerConfiguration": {"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/research-agent:latest"}},
roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
networkConfiguration={"networkMode": "PUBLIC"},
protocolConfiguration={"serverProtocol": "A2A"},
)

The data plane also exposes the card through the API (bedrock-agentcore get_agent_card), so callers with IAM access can discover an agent without hand-building URLs.

bedrock-agentcore also offers an a2a-v1 extra for the newer A2A v1 protocol; it is mutually exclusive with the a2a extra, and Strands currently targets the 0.3 SDK.


A2AAgent wraps a remote A2A agent so it can be called directly, used as a tool, or placed in a Strands graph:

from strands import Agent
from strands.agent.a2a_agent import A2AAgent
researcher = A2AAgent(
endpoint="http://localhost:9000/",
name="researcher",
description="Researches a topic and returns sourced bullet points.",
)
writer = Agent(
model="us.anthropic.claude-sonnet-5-5",
system_prompt="Write clear briefings. Ask the researcher for facts first.",
tools=[researcher],
)
writer("Write a one-paragraph briefing on grid-scale battery storage.")

For agents that should discover peers at run time, strands-agents-tools provides A2AClientToolProvider(known_agent_urls=[...]), which gives the model tools to list agent cards and send messages.

With boto3 (AgentCore-hosted agent, SigV4)

Section titled “With boto3 (AgentCore-hosted agent, SigV4)”
import json
import uuid
import boto3
agentcore = boto3.client("bedrock-agentcore", region_name="us-west-2")
request = {
"jsonrpc": "2.0",
"id": "req-001",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "Research heat-pump adoption in the UK"}],
"messageId": str(uuid.uuid4()),
}
},
}
response = agentcore.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/research_agent-abc123",
runtimeSessionId=str(uuid.uuid4()),
payload=json.dumps(request),
)
result = json.loads(response["response"].read())
for artifact in result["result"].get("artifacts", []):
for part in artifact["parts"]:
if part["kind"] == "text":
print(part["text"])

When the runtime has a JWT authorizer, generic A2A clients call the runtime’s HTTPS URL directly with Authorization: Bearer <token> and an X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header; this is how agents in other clouds or frameworks reach an AgentCore-hosted agent.


FrameworkServing over A2ACalling A2A agents
StrandsA2AServer, or StrandsA2AExecutor + serve_a2a on AgentCoreA2AAgent, A2AClientToolProvider
Google ADKADK’s A2A integration (exposes an ADK agent as an A2A server)ADK remote A2A agents
LangGraph / LangChainWrap the graph in an a2a-sdk AgentExecutor; AgentCore CLI scaffolds thisa2a-sdk client
Anything elseImplement a2a.server.agent_execution.AgentExecutor and serve with a2a-sdk (or serve_a2a)a2a-sdk ClientFactory

Check each framework’s own documentation for current class names; A2A integrations outside Strands and AgentCore are not covered by this guide’s verification.


  • Authenticate every call. On AgentCore, A2A runtimes accept SigV4 (IAM) or OAuth 2.0 bearer tokens via a custom JWT authorizer. Advertise the scheme in the agent card’s securitySchemes.
  • Treat remote agents as untrusted input. Messages and artefacts from another agent can carry prompt injection; don’t let them trigger privileged tools without checks, and keep remote agents out of your agent’s system prompt.
  • Least privilege per agent. Each AgentCore runtime has its own execution role; don’t share one broad role across agents.
  • Pass identity explicitly. Propagate end-user identity through AgentCore Identity (OAuth on-behalf-of / token exchange) rather than embedding user IDs in message text.
  • TLS only. AgentCore endpoints are HTTPS; self-hosted A2A servers should be too.

  1. Write good agent cards. Clear description and skills are what a calling model uses to decide whether to delegate.
  2. Use tasks for long work. Return a task quickly and stream updates (message/stream) or use push notifications instead of holding a request open.
  3. Keep contextId stable for a conversation so the remote agent can keep context; AgentCore’s session header gives each conversation its own microVM.
  4. Bound delegation. Set timeouts on clients (A2AAgent(timeout=...)) and limits on graphs or swarms that include remote agents.
  5. Observe across agents. Propagate W3C trace context (traceparent) so AgentCore Observability can stitch spans from both sides.
  6. Pin protocol versions. A2A is still evolving (0.3 and v1 coexist); pin a2a-sdk with your framework and test before upgrading.

Related guides: AgentCore · Strands Agents · Advanced multi-agent patterns