All chapters
  1. Start hereOne agent asks. Another answers. The rest is the contract between them
  2. Foundations · 1One model, one tool, two agents: who is who, and who is responsible
  3. Foundations · 2Message passing: sender, recipient, payload, address and correlation
  4. Foundations · 3Topologies: central orchestrator, peer-to-peer and hierarchy
  5. Mechanics · 4Request and reply, or a task: synchronous versus asynchronous exchange
  6. Mechanics · 5Contracts: messages, artifacts, typed schemas, errors and versions
  7. Mechanics · 6The task lifecycle: submitted, working, input-required, completed, failed, canceled
  8. Mechanics · 7Discovery: Agent Cards, skills and how an agent says what it can do
  9. Protocol · 8A2A: the Agent2Agent protocol, part by part
  10. Protocol · 9A2A versus MCP: delegating to an agent versus calling a tool
  11. Protocol · 10Handoff, delegation or shared state: three ways to work together
  12. Production · 11How updates arrive: streaming, push notifications, callbacks, polling and queues
  13. Production · 12Security: identity, delegated scopes, trust across domains, authorization
  14. Production · 13Reliability: retries, idempotency, order, timeouts and compensation
  15. Production · 14Observability: one trace across three agents
  16. Reference · 15Frameworks: A2A SDKs, LangGraph, AutoGen, CrewAI and plain code
  17. Reference · 16Advanced: consensus claims, coordination failure, cost and isolation
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Foundations · 2

Message passing: sender, recipient, payload, address and correlation

The five parts every message needs, the envelope that carries them, and the id that lets a reply find the request it answers.

What you will understand
Five parts
Every message needs a sender, a recipient, an address, a payload and a correlation.
Envelope and payload
The fields around the content, and why they must not live inside it.
Five ids, five jobs
message_id, correlation_id, task_id, run_id, trace_id: what each one answers, and what goes wrong when two are merged.

The coordinator in the middle of the example has sent two requests in the same second of the same run. One asks the assessment agent for the evidence of SUB-1004. A moment later, another asks the underwriting agent for a recommendation on a different submission. Then a reply arrives. It says "completed" and carries an artifact. Which request does it answer?

The first version of the team's code answered that question by looking at the payload: if it contains evidence, it must be the answer to the evidence request. That worked until two evidence requests were open at the same time, one for each of two submissions, and the replies came back in the opposite order. The coordinator attached the evidence of one building to the other building's recommendation.

Nothing was wrong with either agent. The message was missing one field: a label on the request that the reply repeats. This page is about that label and the four other parts every message needs.

The five parts of a message#

A message carries five kinds of information. Each one answers a question the recipient, or the sender later, will ask.

The sender is the agent that wrote the message. For example, intake-agent. The recipient needs it to know whom to answer and whether to trust the request.

The recipient is the agent the message is for. For example, assessment-agent. It says who should act on the message.

The address is where the recipient can be reached: the name the transport uses to deliver the message. For example, the name assessment-agent on the example's message bus, or a URL such as https://agents.insurer.example/assessment in a deployment. Recipient and address are close but not the same: the recipient is who, the address is where. One agent can move to a new address; its name stays.

The payload is the content the recipient works on. For example, {"submission_id": "SUB-1004", "need": ["roof_assessment", "guidance", "similar_decisions"]}. Everything else is there so that the payload reaches the right agent and its answer finds its way back.

The correlation is the label that ties a reply to its request. A correlation id is an id the caller puts on a request and the callee copies onto every reply, so the caller knows which question an answer belongs to. For example, the request msg-0003 carries correlation_id: msg-0003; the reply msg-0004 carries correlation_id: msg-0003 too.

Plain English. A letter has an envelope and a letter inside. The envelope says who sent it, who it is for and where to deliver it, and in business mail it carries "Your ref." and "Our ref.". The letter inside is the payload. The post office reads only the envelope.

Envelope and payload#

The fields around the payload are called the envelope: everything that says who, to whom, which exchange, which run, and with which credentials. The payload is what the recipient's work is about. The split matters for three reasons.

The message bus, a router or a security check can act on the envelope without understanding the payload. In the example the bus delivers by to, drops a duplicate by message_id, and the receiver checks the token in auth with the same code whatever the payload means.

Payloads differ by schema; envelopes do not. Every message in the example, request, status, artifact, question, cancel or error, has the same thirteen envelope fields around its payload. Code that routes, logs or traces messages is written once.

And the ids in the envelope are trustworthy only if the payload cannot fake them. If the reply's correlation were somewhere inside the artifact, a callee that copies text from a retrieved document into its artifact could, by accident or on purpose, claim to answer a request it never saw.

This is the envelope of the example, from examples/uw-agents/messages.py. It is this site's teaching design, not the wire format of the A2A protocol; A2A maps each field to its counterpart there.

TYPES = ("task.request", "task.status", "task.artifact", "task.input", "task.cancel", "error")
FIELDS = ("message_id", "correlation_id", "type", "from", "to", "run_id", "task_id", "attempt_number",
          "seq", "schema", "deadline_ms", "trace", "auth", "payload")

The insurance example: one request, one reply#

Click through the real evidence request of case UW-403 and its first reply. Then remove the correlation id from the reply and read what the caller can no longer do. The agents here are scripted stand-ins, so the lab shows how the mechanism works, not how good any model is.

FieldPlain meaningValue in the UW-403 evidence request
message_idMakes this one message uniquemsg-0003
correlation_idTies every reply to this requestmsg-0003
typeWhat kind of messagetask.request
fromThe sendercoordinator
toThe recipient's address on the busassessment-agent
run_idThe execution of the workflow this belongs torun-7f3a
task_idThe delegated work; assigned by the calleenull (the first reply brings task-a1)
attempt_numberWhich try this is1
seqOrder of the callee's messages about a task0
schemaName and version of the payload's shapeevidence.request/v1
deadline_msHow long the caller waits for a final answer30000 (simulated)
traceTrace context: trace id, this step, its parent32 and 16 hex characters
authWho acts, for whom, with which scopes, for which recipientcoordinator for broker@brokerage.example, evidence:read, audience assessment-agent
payloadThe contentSUB-1004, the evidence needed, the submission

The first reply, msg-0004, is a task.status that says working. It copies correlation_id: msg-0003 and introduces task_id: task-a1. From then on the caller can refer to the work by its task id.

Five ids, five jobs#

Five ids appear in every run of the example. They look alike, and the most common bug in a multi-agent system is to let one of them do another's job. This table is the reference the rest of the site uses.

Diagram: Five ids on one exchange · UW-403, evidence request

Time runs down the page. Each message has its own message_id. Every reply repeats the request's correlation_id. The callee names the work with a task_id in its first reply. All of them carry the same run_id and the same trace_id.

  1. Coordinator (the caller) to Assessment agent (the callee): msg-0003 · corr msg-0003 · task none. The request. Its correlation_id is its own message_id. It has no task id yet: the callee assigns one.
  2. Assessment agent (the callee) to Coordinator (the caller): msg-0004 · corr msg-0003 · task-a1 · working. The first reply: a new message_id, the request's correlation_id, and the new task id.
  3. Assessment agent (the callee): tool calls, 570 ms. The callee works. The caller holds only the correlation and the task id.
  4. Assessment agent (the callee) to Coordinator (the caller): msg-0005 · corr msg-0003 · task-a1 · artifact. The result. Same correlation, same task, a higher seq. The caller finds its open request and closes it.
IdExampleOne perJobQuestion it answers
message_idmsg-0007messageMakes one message unique"Have I already processed this exact message?"
correlation_idmsg-0003request and its repliesEquals the request's message_id; every reply carries it"Which of my requests does this reply answer?"
task_idtask-a1piece of delegated workAssigned by the callee when it accepts the work"What is the state of that work? Cancel it. Here is your answer."
run_idrun-7f3aexecution of the whole workflow for a submissionGroups every message and task of one execution"Show me everything that happened for this quote request this time."
trace_id32 hex charactersrun (on this site)Joins the timed steps of all agents into one timeline"Which step caused which, and where did the time go?"

Four more identifiers travel with them and must stay apart too. submission_id (SUB-1004) names the business object; there can be several runs for one submission. attempt_number says which try of a step this is; a retry is attempt 2 inside the same run, never a new run. idempotency_key (run-7f3a:SUB-1004:rec) names one intended write, so that two tries store one row. span_id names one timed step inside a trace. Each gets its own chapter: Reliability for attempts and keys, Tracing for traces and spans.

Common confusion. "We already have a request id." Usually that one id is used as message id, correlation id and trace id at once. It works until the first retry: the retry needs a new message id (it is a new message), the same correlation (it answers the same need), and a new span in the same trace. One id cannot say all three.

An executable demonstration#

The two functions that create messages in the example make the rules concrete. new_request gives a request its own message_id and sets its correlation_id to the same value. reply_to copies the request's correlation_id, run_id and trace context, and swaps sender and recipient. Both are in examples/uw-agents/messages.py. This short script, run from the example folder, builds one request and its first reply and checks them with envelope_problems:

from messages import MessageIds, new_request, reply_to, envelope_problems

ids = MessageIds()
auth = {"principal": "intake-agent", "on_behalf_of": "broker@brokerage.example", "scopes": ["evidence:read"], "audience": "assessment-agent"}
req = new_request(ids, "intake-agent", "assessment-agent", "run-7f3a", "evidence.request/v1",
                  {"submission_id": "SUB-1004", "need": ["roof_assessment"]}, auth, deadline_ms=30000)
rep = reply_to(req, ids, "task.status", "task.status/v1", {"state": "working"}, task_id="task-a1", seq=1,
               auth={**auth, "principal": "assessment-agent", "audience": "intake-agent"})
for m in (req, rep):
    print(m["type"], m["from"], "->", m["to"], "message_id", m["message_id"], "correlation_id", m["correlation_id"],
          "task_id", m["task_id"], "seq", m["seq"])
print("problems:", envelope_problems(rep))
broken = {k: v for k, v in rep.items() if k != "correlation_id"}
print("problems without correlation_id:", envelope_problems(broken))
task.request intake-agent -> assessment-agent message_id msg-0001 correlation_id msg-0001 task_id None seq 0
task.status assessment-agent -> intake-agent message_id msg-0002 correlation_id msg-0001 task_id task-a1 seq 1
problems: []
problems without correlation_id: ['missing field: correlation_id']

The run proves three things. The request's correlation is its own id. The reply has a new message_id but the request's correlation_id. And a reply without its correlation is caught as a malformed envelope before any agent acts on it. When a correlated reply arrives, the caller looks the request up in its table of open requests (Agent._on_reply in agents.py); a reply that matches nothing is logged as unmatched.

A failure mode: the reply that cannot find its request#

Go back to the coordinator with two open evidence requests. With correlation, each reply names its request, and the evidence of SUB-1004 goes to SUB-1004. Without it, the coordinator has three bad options. It can match by payload, which fails when two payloads look alike, as in the opening story. It can match by arrival order, which fails when the second request is faster. Or it can allow only one open request at a time, which turns a parallel system into a queue.

The failure is silent. Nothing throws. The recommendation for one building is written with another building's roof age, and it passes every schema check because the artifact is valid; it is only attached to the wrong request. A careful reviewer catches it only by noticing that evidence_ids in the recommendation point to a different submission.

The same bug appears in a subtler form when ids are reused. If a retry sent the original message_id again, a receiver that drops duplicates would drop the retry. If a reply carried the run_id where the correlation_id should be, every reply in the run would match the first open request. Reliability uses the separate ids to make retries and duplicates safe; it only works because they are separate here.

How the A2A protocol carries the same parts#

A2A, the Agent2Agent protocol, is an open standard for messages between agents. It has its own names for these parts: a message has its own id, belongs to a context that groups related work (close to this site's run_id), can refer to a task by id, and carries its content as parts. How each of this site's envelope fields maps to A2A's names, read from the specification, is on A2A. Libraries carry these ids for you to different degrees; Frameworks says which, from their own documentation.

Before AI. In a Kafka-based system, the record key decides the partition, a header carries a correlation id, and the consumer group's offset says what has been processed. In JMS, JMSMessageID and JMSCorrelationID play exactly the roles of message_id and correlation_id here, and a reply-to destination plays the role of from. None of this is new; agent systems tend to forget it because the first demo has one request at a time.
What this is not. This page is about the parts of one message. The structure of a trace (spans, parents, timelines) is introduced on Tracing and owned in depth by observe.sammuthu.com. The typed shape of a payload, its validation and its evolution, belongs to schema.sammuthu.com; Contracts covers only what two agents must agree on.

Checklist: a reviewer's questions about a message format#

The same idea for a coding agent. A planning agent asks a test agent to run the suite on two branches at once. Both replies say "3 failures". Only the correlation id tells the planning agent which branch has which failures; matching by content would attach the failures of one branch to the pull request of the other.

Who assigns which idCaller-assigned and callee-assigned ids, and why it matters

The caller assigns message_id and correlation_id: it needs them before anything is sent, to recognize the answer. The callee assigns task_id: only it knows whether it accepted the work, and it may assign one task to a request it then rejects, as the example does, so the refusal has something to point at. run_id is assigned by whoever starts the workflow (the intake agent), and every other agent copies it. trace_id starts with the first span of the run and travels in the trace context.

An alternative design lets the caller propose the task id. That removes one round trip before the caller can cancel or query, and lets a retry reuse the same task id, which makes deduplication of the work easier. The cost is trust: the callee must check that the proposed id is not already used by another caller. Both designs exist in practice; what matters is that the contract says which one is in force.

Versioning the envelope itselfThe schema field names the payload; who names the envelope?

Every payload in the example names its schema and version (evidence.request/v1). The envelope has no version field: all thirteen fields and the payload slot are fixed, and envelope_problems rejects an unknown one. That is right for a teaching example and fragile in production, where a new envelope field (a tenant id, a priority, a new trace format) will be added while old agents still run.

Two common answers: version the envelope in the transport (a header, a path, a protocol version negotiated at connection time), or make the envelope tolerant (ignore unknown fields, require only a small core). The A2A specification takes a position on protocol versions that the A2A page reports. Whatever the choice, an envelope change is a change to every agent at once, which is a strong reason to keep the envelope small and put everything else in the payload.

Ids and orderingWhat the ids can and cannot say about order

The example's message ids count up (msg-0001, msg-0002), which tempts code to sort by them. That only holds inside one process with one counter. Across agents on different machines, ids are generated independently and carry no order. Order inside one task is what seq is for: the callee numbers its own messages about one task, so the caller can recognize a late working after completed (Reliability, case UW-411). Order across agents comes from the trace: a span's parent says what caused it, which is stronger than any timestamp.

In one breath#

A message is an envelope and a payload. The envelope names the sender, the recipient and its address, and carries the ids; the payload is the content. A reply finds its request because it repeats the request's correlation id. Five ids do five jobs, message_id, correlation_id, task_id, run_id and trace_id, and merging any two of them produces bugs that never throw.

Next: with one exchange understood, the question is how several exchanges are arranged. Topologies routes the same workflow through a central orchestrator, a peer chain and a hierarchy, and counts what each costs.