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
Mechanics · 4

Request and reply, or a task: synchronous versus asynchronous exchange

Waiting on the line works for a fast answer. Work that takes minutes needs a task: an id now, the result later. Deadlines, blocking and when each fits.

What you will understand
Two ways to ask
Wait on the line for the answer, or take a ticket: an id now, the result later.
The deadline
Every request needs a time after which the caller stops waiting, and a plan for what happens then.
When each fits
Short, bounded work suits a blocking call. Work that can take minutes, or ask back, needs a task.

On most days the assessment agent answers in about half a second. The intake team wrote its first version the way it writes every HTTP call: send the request, wait for the reply, with a timeout of 30 seconds. It worked for weeks.

Then two things happened in the same week. The roof-data provider had a slow day, and some evidence requests took three minutes. And case UW-402 arrived: no roof age on the application, no record at the provider. The assessment agent needed the broker to say how old the roof was, and the broker answered fifteen minutes later. Both times the intake agent's timeout fired at 30 seconds. It reported the request as failed. The evidence work, which was still running, finished a few minutes later and its result went nowhere.

The fix is not a longer timeout. A caller that holds a connection open for fifteen minutes is wasting a connection and a thread, and still has no place to receive the broker's question. The fix is a different way of asking.

Two ways to ask#

A request/reply exchange is one request followed by one or more replies that carry its correlation id. For example, "collect the evidence for SUB-1004" and, later, "here is the evidence". The question on this page is what the caller does between the two.

In a synchronous exchange the caller waits for the reply before it does anything else. For example, a function call, or an HTTP request where the response carries the result. The waiting is called a blocking call: the caller's thread, connection or loop is held until the answer arrives or the wait is abandoned.

In an asynchronous exchange the caller sends the request and goes on with other work; the result arrives later, by a separate message. For example, ordering at a restaurant counter and getting a buzzer: you sit down, and the buzzer tells you when the food is ready.

A task protocol is the asynchronous exchange with a name for the work. The callee answers at once with a task id ("I have accepted this; it is task-a1") and later sends the state and the result of that task. The caller can ask for the status, send an answer to a question, or cancel, always by naming the task. The ticket is the task id.

Plain English. A phone call is synchronous: you stay on the line. A dry cleaner is a task protocol: you hand over the shirt, you get a ticket, you come back later, and if they need to ask whether a stain may be treated, they call the number on the ticket.
Before AI. An HTTP endpoint that answers 202 Accepted with a Location header for a status resource is a task protocol. So is a job queue in a Spring application that returns a job id and lets the client poll /jobs/{id}. Agents need this pattern more often than ordinary services, because their work is longer and less predictable, and because they may stop to ask.

The deadline#

Both ways of asking need a deadline: the point in time after which the caller stops waiting for a final answer and does something else. For example, "if the evidence is not complete 30 seconds after I asked, I give up on this request". A deadline belongs to the caller. It is not a promise by the callee; it is the caller's decision about how long the answer is worth waiting for.

What a deadline is not: a timeout on the connection, and a reason to assume the work did not happen. When a deadline passes, the callee may still be working, or may have finished and lost the reply on the way. What the caller does next (retry, give up, mark the case for a person) is the subject of Reliability; on this page the deadline is only the concept.

In the example every request carries its deadline in the envelope as deadline_ms, and the caller starts its own clock when it sends. These are the values, from examples/uw-agents/agents.py:

DEADLINE_MS = {"evidence.request/v1": 30_000, "recommendation.request/v1": 10_000}   # per request, caller side

The smallest primitive: an id now, the result later#

The example uses a task protocol for every request, even the ones that finish in under a second. Every request gets a first reply, task.status with working and the new task id, within one hop of arriving. The result comes later in a task.artifact with the same correlation id. The caller keeps a record of each request it sent, and that record, not a blocked thread, is what waits.

This is Agent.call from agents.py, verbatim. It narrows the caller's token to the one scope the request needs, sends the request, remembers it, and starts the deadline clock:

def call(self, bus: Any, to: str, schema: str, payload: dict[str, Any], parent: Task | None,
         on_behalf_of: str | None, attempt: int = 1) -> Call:
    """Send a request and keep the caller's view of it. The token is narrowed to the one scope it needs."""
    scope = REQUIRED_SCOPE[schema]
    auth = attenuate({**self.token, "on_behalf_of": on_behalf_of}, [scope], audience=to)
    deadline = self.deadlines.get(schema)
    msg = new_request(bus.ids, self.address, to, bus.run_id, schema, payload, auth, deadline, attempt_number=attempt)
    c = Call(correlation_id=msg["message_id"], kind=KIND_OF[schema], caller=self.address, callee=to, request=msg,
             parent_task_id=parent.task_id if parent else None, attempt_number=attempt)
    self.calls[c.correlation_id] = c
    bus.send(msg, parent.span if parent else self.root)
    bus.set_deadline(self, c.correlation_id, deadline)
    return c

Nothing in call waits. It returns a Call, the caller's view of the callee's task. When replies arrive, Agent._on_reply finds the Call by correlation id and updates it. One detail matters for UW-402: when the callee says input-required, the caller stops the deadline clock (the task is waiting for the caller, not the other way round), and forward_input restarts it when the answer is sent.

The insurance example: one fast case, one slow, one silent#

Three cases show the range. The agents here are scripted stand-ins, so these results show how the mechanism works, not how good any model is.

CaseWhat the callee doesWhat the caller sees (orchestrator topology, simulated)
UW-401Finishes the evidence in about 570 msworking at 90 ms, the artifact at 660 ms; the run ends at 786 ms
UW-402Asks for the roof age; the broker answers 15 minutes laterworking, then input-required at 270 ms; the clock stops; the answer at 900,310 ms resumes the same task; the run ends at 900,866 ms
UW-412Never answersNo status at all; the deadline fires at 30,070 ms, attempt 2 at the same moment, its deadline at 60,070 ms; then the caller goes on without the evidence

UW-402 is the case a blocking call cannot serve: fifteen minutes on the line, and no place to put a question. UW-412 is the case a deadline exists for. Here is its log:

/opt/homebrew/bin/python3 run_case.py --case UW-412 --dry-run
UW-412 · topology orchestrator · run run-b712 · agents: scripted stand-ins (no model called)
  time ms  from                 to                 type          state           ids
       50  intake-agent       → coordinator        task.request  -               msg-0001 corr msg-0001 task -        try 1
       70  coordinator        → intake-agent       task.status   working         msg-0002 corr msg-0001 task task-c1  try 1
       70  coordinator        → assessment-agent   task.request  -               msg-0003 corr msg-0003 task -        try 1
       90  · ignored           coordinator → assessment-agent           msg-0003  assessment-agent is silent: it receives the message and never answers
    30070  · deadline          coordinator                              msg-0003  coordinator: no final answer to msg-0003 in time
    30070  coordinator        → assessment-agent   task.request  -               msg-0004 corr msg-0004 task -        try 2
    30070  · retry             coordinator → assessment-agent           msg-0004  attempt 2 replaces msg-0003
    30090  · ignored           coordinator → assessment-agent           msg-0004  assessment-agent is silent: it receives the message and never answers
    60070  · deadline          coordinator                              msg-0004  coordinator: no final answer to msg-0004 in time
    60070  · compensation      coordinator                                DEADLINE_EXCEEDED: the case goes to the underwriter marked evidence unavailable
    60070  coordinator        → underwriting-agent task.request  -               msg-0005 corr msg-0005 task -        try 1
    60090  underwriting-agent → coordinator        task.status   working         msg-0006 corr msg-0005 task task-u1  try 1
    60136  underwriting-agent → coordinator        task.artifact completed       msg-0007 corr msg-0005 task task-u1  try 1
    60156  coordinator        → intake-agent       task.artifact completed       msg-0008 corr msg-0001 task task-c1  try 1
messages: 8 sent · 6 delivered · 0 duplicates dropped · 0 stale updates ignored · 2 deadlines fired
tasks (caller's view): workflow completed · evidence failed · recommendation completed
recommendation: escalate · citations - · missing roof_assessment, guidance, similar_decisions · evidence unavailable · routed to the underwriter · stated_confidence 0.2
tool calls: check_eligibility 1 · record_recommendation 1
rows stored: 1 · human_decision: none (no person has decided yet)
trace: 1 trace_id · 21 spans · last message at 60176 ms · run ends at 60176 ms (simulated)
expected vs actual: PASS (11 of 11 checks)

Two deadlines, one retry, and the case still reaches a person: the recommendation is escalate, marked evidence unavailable, with low stated confidence. The caller never blocked a thread for those sixty seconds; it held a record and a timer.

The exchange lab#

Set how long the work takes, how long a blocking call may wait, and how often the caller polls the task. The lab is a model: arithmetic over illustrative timings (20 ms per hop, a task deadline of 15 minutes), not a run of the example and not a measurement of any system.

Work takesBlocking call, 30 s timeoutTask, polled every 10 s
2 sResult at 2.04 s; caller blocked 2.04 sTask id at 40 ms; result known at the first poll, 10.02 s
3 minTimes out at 30 s; 3 minutes of the callee's work wastedResult after 19 polls; caller blocked only for the polls themselves
20 minTimes out at 30 sPasses the 15-minute task deadline; the caller cancels and decides what to do with the case

Diagram: A task protocol on UW-402 · an id now, a question, the result later

Time runs down the page. The caller gets a task id within one hop and never holds a connection. The callee asks a question; the caller stops its deadline clock, gets the answer from the broker, and sends it on the same task. The result arrives fifteen simulated minutes after the request.

  1. Coordinator (caller) to Assessment agent (callee): evidence request, deadline 30 s. The request carries deadline_ms 30000. The caller starts its clock.
  2. Assessment agent (callee) to Coordinator (caller): working · task-a1. The ticket: a task id within one hop.
  3. Assessment agent (callee) to Coordinator (caller): input-required: roof age?. The task waits for the caller. The caller stops the deadline clock.
  4. Coordinator (caller) to Broker (via intake): ask the broker. The question travels up to the intake agent, which asks the broker.
  5. Broker (via intake) to Coordinator (caller): 12 years. The answer arrives fifteen simulated minutes later.
  6. Coordinator (caller) to Assessment agent (callee): task.input on task-a1. The answer names the same task. The caller restarts its deadline clock.
  7. Assessment agent (callee) to Coordinator (caller): artifact · completed. The same task finishes. Nothing was started twice.

A failure mode: the timeout that lies#

The opening story contains the most common failure of synchronous calls between agents. The caller's timeout fires; the caller concludes "failed"; the callee is still working and finishes. Now the system holds two contradicting facts: the caller's record says failed, the callee's task says completed. If the caller retries, the work is done twice. If it reports failure to the broker, the broker resubmits, and the work is done three times.

A blocking timeout cannot tell three situations apart: the request never arrived, the work is still running, or the work finished and the reply was lost. A task protocol does not remove the ambiguity, but it gives the caller tools to resolve it: it has a task id it can ask about, a status it can poll, and a cancel it can send. The callee, for its part, has a state it can report. Task lifecycle defines those states and Reliability makes a retry safe when the ambiguity remains.

Production pitfall. A gateway, a load balancer or a serverless platform in front of an agent often has its own request timeout, shorter than the caller's. The caller sets 30 seconds, the platform cuts the connection at 10, and nobody planned for it. With a task protocol the first reply comes back in milliseconds, so infrastructure timeouts stop mattering for long work.

How the A2A protocol offers both#

The A2A protocol, an open standard for messages between agents, supports both styles. A client sends a message; the remote agent may answer with a message directly or with a task that the client then follows. The specification also defines ways to learn about a running task: asking for it, subscribing to a stream of updates, or registering for push notifications. The operation names and the states, read from the specification, are on A2A; how the updates arrive is compared on Updates. Libraries differ in whether they hide the task behind a blocking call; Frameworks reports what each one documents.

What this is not. This page introduces the deadline as a concept. Retries, backoff, idempotency and what to undo after a timeout belong to Reliability on this site, and to reliable.sammuthu.com as a discipline for the whole system.

Checklist: is this exchange the right kind?#

The same idea for a coding agent. "Format this file" is a blocking call: a second, no questions. "Run the full test suite and tell me what fails" is a task: it may take twenty minutes, and the test agent may come back asking whether a flaky test should be retried. A planning agent that waits on the line for the second one will hit a timeout in CI long before the suite ends.

The hybrid: wait a little, then take a ticketReturn the result if it is quick, a task id if it is not

Many systems do both on one request: the callee holds the connection for a short time, and if the work finishes, it returns the result directly; if not, it returns the task id. Fast cases stay fast, slow cases do not block. The cost is two code paths in every caller, and a contract that says which answer shapes are possible. The A2A protocol's send operation has a related option, which the A2A page describes from the specification.

The example does not use the hybrid. Every request gets a task, which makes every exchange look the same in the logs and the trace, at the price of three messages for work that could have taken one.

Deadlines across hopsA child's deadline must fit inside its parent's

In the hierarchy topology the supervisor gives the assessment lead 90,000 ms, and the lead gives each of its own requests 30,000 ms with one retry. The parent's deadline is chosen to cover the child's attempts (two attempts of 30 seconds and the work around them). If the parent's deadline were shorter than the child's, the parent would give up while the child still retries, and the child's result would arrive at a caller that no longer waits.

The general rule: pass the remaining time down, not a fixed number. A caller with 20 seconds left should not grant a callee 30. Some RPC systems carry the deadline in the request for this reason, so every hop can compute what is left. The example carries deadline_ms in the envelope but each caller sets its own fixed value; propagating the remainder is a design improvement a production system would make.

What a task protocol costsState on both sides, and a status message per change

A task protocol moves waiting from a thread into data. The callee must keep a task table that survives as long as the task; the caller must keep a record per open request and a timer. Both must be cleaned up: a task table that grows forever is a memory leak with a business name. Status messages add traffic: three messages per delegation in the example instead of two.

In exchange the system can hold thousands of open requests with no thread per request, survive a restart if the tables are durable, and answer "where is this request?" by reading data. For agents, whose work is long and whose callers are often other agents with their own deadlines, that exchange is almost always worth it.

In one breath#

A caller can wait on the line for the answer or take a ticket. Waiting suits short, bounded work; work that can take minutes or stop to ask a question needs a task, an id now and the result later. Either way the caller owns a deadline, and when it passes, the caller knows only that it stopped waiting, not that the work stopped.

Next: an id now and a result later only works if both sides agree on what the result looks like. Contracts is about that agreement: the request schema, the artifact, named errors and versions.