Cheat sheets

A2A and Agent Communication Protocols

MCP, A2A, ACP, ANP and FIPA-ACL side by side. Agent Cards, tasks, wire names and failures. A2A 1.0.1.

  • Concepts and terms
  • Tasks and commands
  • Annotated code
  • Diagrams
  • Comparisons
  • Defaults and numbers
  • Troubleshooting
  • Questions and tips

Source

Four protocols side by side#

FactorMCPA2AACPANP
Primary useAgent to ToolAgent to AgentAgent to AgentAgent to Agent
Spec formatJSON-RPCJSON-RPC / REST / gRPCOpenAPI 3.1 (REST)JSON-RPC
DiscoveryTool listing/.well-known/agent-card.jsonGET /agents, /.well-known/agent.yml/.well-known/agent-descriptions
IdentityImplicit (local)Security schemes (OAuth, mTLS)Server-levelW3C DID (did:wba) with E2EE
Audit trailN/ABasic (task history)TrajectoryMetadataNot formally specified
StreamingN/ASSESSETransport-agnostic
Unique featureTool schemasAgent Cards + SkillsTrajectory audit trailMeta-protocol negotiation
StatusStableStable (v1.0)Merging into A2AActive development

A2A call over HTTP+JSON#

discovermessagecreate tasktaskclientClient agentsends A2A-Version: 1.0storeAgent Card/.well-known/agent-card.jsonprocessPOST /message:sendreturnImmediatelystoreTaskStorestate + artifactsprocessGET /tasks/{id}until a terminal statediscovermessagecreate tasktaskclientClient agentsends A2A-Version:1.0storeAgent Card/.well-known/agent-card.jsonprocessPOST /message:sendreturnImmediatelystoreTaskStorestate + artifactsprocessGET /tasks/{id}until a terminalstate

Agent Card and Message shape#

{"name": "research-agent", "version": "1.2.0",
"supportedInterfaces": [{"url": "<url>", // pick the first binding you speak
"protocolBinding": "JSONRPC", "protocolVersion": "1.0"}],
"capabilities": {"streaming": true, "pushNotifications": true},
"securitySchemes": {"bearer": {"httpAuthSecurityScheme": {"scheme": "Bearer"}}},
"securityRequirements": [{"schemes": {"bearer": {"list": []}}}],
"defaultInputModes": ["text/plain"], // media types
"skills": [{"id": "summarize_paper", "tags": ["research"]}]}
{"messageId": "msg-001", "role": "ROLE_USER", // or ROLE_AGENT
"parts": [{"text": "Summarize this paper."}, // one content field per Part
{"raw": "...", "filename": "paper.pdf", "mediaType": "application/pdf"},
{"data": {"targetLength": "3 paragraphs"}}]} // no kind field

FIPA-ACL heritage#

Modern specFIPA analogKeepsDrops
MCP tools/callrequestintent, correlation idsemantics, ontology
MCP resources/readquery-refintent, correlation idformal semantics
A2A Task lifecyclecontract-net + request-whenasync lifecyclecompleteness guarantees
A2A streaming eventssubscribe/notifyasync pushtyped-predicate subscription
NLIPnatural-language contentLLM-nativeschema

Troubleshooting#

SymptomCauseFix
JSON-RPC error -32009Missing or wrong A2A-VersionSend A2A-Version: 1.0
JSON-RPC error -32601Unknown method nameUse PascalCase names such as SendMessage
HTTP 400 VERSION_NOT_SUPPORTEDHTTP+JSON call without the headerAdd the header to every request
HTTP 404 TASK_NOT_FOUNDUnknown task id on GET /tasks/{id}Use the id from the task reply
Updates after completion lostTask is immutable once terminalCheck terminal state before you yield
Garbage after a card updateSchema drift between versionsVersion skills and output schemas
Same word, wrong actionSemantic drift without ontologyJSON Schema on content, typed artifacts
50 agents hit GET /agentsDiscovery thundering herdCache Agent Cards with TTL

Use X when#

MCP
you want to invoke a specific tool. Agent to tool.
A2A
you want to delegate a whole task to another agent.
A2A + ACP patterns
you need audit trails for compliance.
ANP + A2A
agents are outside your org and share no infrastructure.
A2A + message broker
external agents on shared infrastructure.
Direct RPC
latency-sensitive micro-calls. A2A's lifecycle is async.
No protocol
agents do not need to talk to each other.

Task lifecycle with a pause#

1Clientsends SendMessage with no taskId. The servercreates the Task.2Serversets TASK_STATE_SUBMITTED, thenTASK_STATE_WORKING.3Serverdata is missing. It setsTASK_STATE_INPUT_REQUIRED with a ROLE_AGENTmessage.4Clientsends a new message with the same taskId and adata part.5Servergoes back to TASK_STATE_WORKING and adds anArtifact.6Serversets TASK_STATE_COMPLETED. Terminal states areimmutable.7Clienta follow-up creates a new task within the samecontextId.

A2A tasks on the wire#

TaskCode
Discover an agentGET /.well-known/agent-card.json
Send and wait (JSON-RPC)"method": "SendMessage"
Send, return at once (HTTP+JSON)POST /message:send with configuration.returnImmediately
Poll a taskGetTask or GET /tasks/{id}
Stream a task over SSESendStreamingMessage or POST /message:stream
Reattach to a running taskSubscribeToTask or /tasks/{id}:subscribe
Cancel or list tasksCancelTask, ListTasks
Run the demo server and clientpython3 code/main.py

Defaults and numbers#

SettingDefaultNote
A2A_VERSION"1.0"Send A2A-Version: 1.0 on every request
No A2A-Version header0.3The server reads the request as version 0.3
returnImmediatelyFalseSendMessage blocks until terminal or interrupted
A2A_MEDIA_TYPE"application/a2a+json"Content type of the HTTP+JSON binding
PORT8765Lesson 16.12 demo server
ANP negotiationmax 10 roundsThen timeout

Abbreviations#

A2A
Agent2Agent. Peer protocol with Agent Cards and tasks.
ACP
Agent Communication Protocol. REST runs with TrajectoryMetadata.
ANP
Agent Network Protocol. did:wba identity and HPKE E2EE.
DID
Decentralized Identifier. W3C identity on the agent's own domain.
NLIP
Ecma Natural Language Interaction Protocol. Natural-language content type.
FIPA
Foundation for Intelligent Physical Agents. Standardized ACL in 2000.
ACL
Agent Communication Language. Performative plus content plus metadata.
KQML
Knowledge Query and Manipulation Language (1993). FIPA's predecessor.

Questions#

What does the caller see in A2A?
Task state and artifacts. The called agent's internals stay opaque.
How do I stop duplicate tasks on retry?
Deduplicate on the client's messageId.
How is an Agent Card signed?
A JWS in signatures over the RFC 8785 canonical JSON, without signatures.
What does ACP add?
Each part can carry tool_name, tool_input and tool_output metadata.
DID fetch fails. Open or closed?
Fail closed with the principle of least trust.
Which FIPA protocols are worth porting?
Contract Net, Subscribe/Notify and Request-When.