At 300 milliseconds into case UW-409, the broker writes back: "please withdraw the quote request; the client has found cover elsewhere". The intake agent sends a cancel. At that moment the assessment agent is in the middle of its work: it has called the roof-data provider and is waiting for the guidance search.
Three questions follow, and each needs an exact answer. Can a task that is already running be canceled? What happens to the guidance result that arrives 190 milliseconds after the cancel? And a minute later, when the broker's withdrawal is processed a second time by mistake, what should a cancel on a task that is already canceled do?
If the team answers these in code, case by case, each agent will answer them differently. If it writes them down once, as states and the moves allowed between them, every agent answers them the same way. That written-down answer is the task lifecycle.
A task is a state machine#
A task is a piece of delegated work that has an id and a state, and that may outlive one request. For example, task-a1: "collect the evidence for SUB-1004", owned by the assessment agent. The id comes from the callee when it accepts the work.
A task state is where that work stands at a moment. For example, working means the callee is doing it; completed means the result is ready.
A state machine is a list of states plus the moves allowed between them. For example, "from working a task may move to completed, but from completed it may move nowhere". Anything not on the list is refused. That is all it is, and it is enough to answer the three questions above.
Plain English. A parcel tracker. Accepted, in transit, waiting for you to pay customs, delivered, returned. A delivered parcel does not go back in transit. If customs asks for payment, the parcel waits, and the same parcel continues when you pay.
The states#
The example uses eight states. They follow the names of the A2A protocol, version 1.0.0, read from its specification today; the site's own spec says "accepted" for the first one, and A2A calls it submitted, so this site does too.
| State | Meaning | Kind |
|---|---|---|
submitted | The callee has accepted the request and given it a task id; work has not started | start |
working | The callee is doing the work | active |
input-required | The callee needs something from the caller to go on | interrupted |
auth-required | The callee needs further authorization to go on | interrupted |
completed | Finished; the result is in an artifact | terminal |
failed | Finished with an error | terminal |
canceled | Stopped at the caller's request before it finished | terminal |
rejected | The callee decided not to do it | terminal |
Two groups matter. An interrupted state is one where the task waits for the caller, not the other way round: input-required and auth-required. A terminal state is one the task never leaves: completed, failed, canceled and rejected. Once terminal, always terminal. That one rule answers the second and third questions of the opening story.
Diagram: The task lifecycle · start, active, interrupted, terminal
Read left to right. A task starts submitted, becomes working, may stop in an interrupted state to wait for the caller, and ends in exactly one terminal state, which it never leaves. A cancel or a failure can end it from any non-terminal state.
- Start
- submitted: The callee accepted the request and named the work. It may start it, reject it, or it may be canceled.
- Active
- working: The callee is doing the work. From here it may finish, fail, be canceled, or stop to ask.
- Interrupted
- input-required: The callee needs something from the caller. The same task resumes when the answer arrives.
- auth-required: The callee needs further authorization to go on. Resumes like input-required.
- Terminal
- completed: Finished; the artifact holds the result.
- failed: Finished with an error. On the caller's side also reached when the deadline passes.
- canceled: Stopped at the caller's request. A late result is discarded; a second cancel is refused.
- rejected: The callee decided not to do it, with a typed error. In this example only from submitted.
These are the allowed moves, verbatim from examples/uw-agents/tasks.py:
ALLOWED: dict[str, tuple[str, ...]] = {
"submitted": ("working", "rejected", "canceled", "failed"),
"working": ("input-required", "auth-required", "completed", "failed", "canceled"),
"input-required": ("working", "canceled", "failed"),
"auth-required": ("working", "canceled", "failed"),
"completed": (), "failed": (), "canceled": (), "rejected": (),
}
The smallest primitive: one function that refuses#
Every state change in the example goes through one function, tasks.transition. It refuses two kinds of move, each with a named code: any move out of a terminal state (TASK_TERMINAL, or TASK_NOT_CANCELABLE when the move was a cancel), and any move the table does not list (TRANSITION_NOT_ALLOWED).
def transition(task: Task, event: str, at_ms: int = 0) -> Refusal | None:
"""Move a task its owner holds. Returns None when the move was made, or the Refusal."""
target = EVENTS[event]
if task.state in TERMINAL:
code = "TASK_NOT_CANCELABLE" if event == "cancel" else "TASK_TERMINAL"
return Refusal(code, f"{task.task_id} is {task.state}; a terminal state never moves")
if target not in ALLOWED[task.state]:
return Refusal("TRANSITION_NOT_ALLOWED", f"{task.task_id}: {task.state} to {target} is not an allowed move")
task.history.append({"at_ms": at_ms, "event": event, "from": task.state, "to": target})
task.state = target
return None
Drive one task yourself below. Only the legal moves are offered; switch on "Show illegal moves too" to try a forbidden one and read the refusal. Another switch shows the A2A names. The lab runs the same state machine in JavaScript, checked against the Python by the site's tests.
| From | May move to | Refused, with the code |
|---|---|---|
submitted | working, rejected, canceled, failed | input-required directly: TRANSITION_NOT_ALLOWED |
working | input-required, auth-required, completed, failed, canceled | back to submitted: TRANSITION_NOT_ALLOWED |
input-required, auth-required | working, canceled, failed | completed directly: TRANSITION_NOT_ALLOWED |
completed, failed, canceled, rejected | nothing | any move: TASK_TERMINAL; a cancel: TASK_NOT_CANCELABLE |
The insurance example: a question, and a cancel#
A question back. Input-required is the state in which a task stops because the callee needs something from the caller, and resumes, as the same task, when the answer arrives. In UW-402 the roof age is unknown. The assessment agent moves task-a1 from working to input-required at 270 ms (simulated) and names what it needs. The intake agent asks the broker. Fifteen simulated minutes later the answer arrives as a task.input message that names task-a1, and the task moves back to working and then to completed. One task, one id, one history. The caller's deadline clock stops while the task is interrupted, because the wait is on the caller's side.
A cancel. Cancellation is the caller's request to stop a task before it finishes. Here is case UW-409 in the orchestrator topology. The agents here are scripted stand-ins, so these results show how the mechanism works, not how good any model is.
/opt/homebrew/bin/python3 run_case.py --case UW-409 --dry-run
UW-409 · topology orchestrator · run run-1f09 · 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 assessment-agent → coordinator task.status working msg-0004 corr msg-0003 task task-a1 try 1
300 intake-agent → coordinator task.cancel - msg-0005 corr msg-0005 task task-c1 try 1
320 coordinator → intake-agent task.status canceled msg-0006 corr msg-0001 task task-c1 try 1
320 coordinator → assessment-agent task.cancel - msg-0007 corr msg-0007 task task-a1 try 1
340 assessment-agent → coordinator task.status canceled msg-0008 corr msg-0003 task task-a1 try 1
510 · discarded assessment-agent a tool answered after the cancel; the result is dropped
60000 intake-agent → coordinator task.cancel - msg-0009 corr msg-0009 task task-c1 try 1
60020 coordinator → intake-agent error TASK_NOT_CANCELABLE msg-0010 corr msg-0009 task task-c1 try 1
60040 · refused coordinator → intake-agent msg-0010 TASK_NOT_CANCELABLE: task-c1 is canceled; a terminal state never moves
messages: 10 sent · 10 delivered · 0 duplicates dropped · 0 stale updates ignored · 0 deadlines fired
tasks (caller's view): workflow canceled · evidence canceled · recommendation None
recommendation: none
tool calls: get_roof_assessment 1 · search_guidance 1
rows stored: 0 · human_decision: none (no person has decided yet)
trace: 1 trace_id · 29 spans · last message at 60040 ms · run ends at 60040 ms (simulated)
expected vs actual: PASS (11 of 11 checks)
The three questions of the opening, answered by the log. A running task can be canceled: the coordinator cancels its own workflow task task-c1 and passes the cancel down to task-a1, which moves to canceled at 340 ms. The guidance result that arrives at 510 ms is discarded: the task is terminal, so the late result has nowhere to go. The second cancel at 60,000 ms is refused with TASK_NOT_CANCELABLE, a named error, not silence and not a crash. No row is stored and no recommendation is written.
Notice also what cancel did not undo. The roof-data provider was called once and the guidance index once (tool calls: get_roof_assessment 1 · search_guidance 1). Those calls happened. Cancel stops future work; it does not reverse past work. When past work has effects that must be reversed, that is compensation, on Reliability.
Two views of one task#
There are two records of every task, and they can differ for a moment. The owner (the callee) holds the task itself: Task in tasks.py, with its true state and history. The caller holds its view of it: Call, built from the status messages it has received. Messages can be lost or arrive late, so the caller's view may skip a state, lag behind, or receive an old update after a new one.
The caller protects its view with two guards in tasks.apply_update. An update whose sequence number is not higher than the last one applied is stale and ignored. And once the caller's view is terminal, it never moves. Case UW-411 delivers a working update after completed; with the guards, the caller keeps completed. Without them (run_case.py --case UW-411 --no-seq), the caller ends up believing a finished task is still working. Reliability covers ordering in depth.
A failure mode: states without rules#
A team that tracks a status string but not the allowed moves will see each of these sooner or later. A late working overwrites completed, and a dashboard shows a finished quote as still running. A cancel on a completed task "succeeds", the caller reports the request as withdrawn, and the recommendation the underwriter already sees belongs to a request the broker believes was canceled. A task stuck in input-required with no deadline and no reminder waits forever because the question went to a mailbox no one reads. And two tasks exist for one piece of work because the answer to a question was sent as a new request instead of an input to the waiting task.
Each of these is prevented by one line of the table or one guard: terminal states never move, stale updates are ignored, questions are answered on the same task id.
Production pitfall. "Cancel" in a user interface promises more than the protocol can deliver. The broker sees "withdrawn"; in fact two tool calls ran and, in a real system, may have cost money or left records. Say in the contract what cancel guarantees (no further work, a terminal state) and what it does not (reversal).
How the A2A protocol defines the lifecycle#
The A2A specification, version 1.0.0, read today, defines a TaskState enumeration with TASK_STATE_SUBMITTED, TASK_STATE_WORKING, TASK_STATE_INPUT_REQUIRED, TASK_STATE_AUTH_REQUIRED, TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_CANCELED, TASK_STATE_REJECTED and TASK_STATE_UNSPECIFIED. It calls completed, failed, canceled and rejected terminal, and input-required and auth-required interrupted. It says a task in a terminal state cannot accept further messages, and that canceling a task that is not cancelable returns TaskNotCancelableError. The example maps its states to these names in tasks.py:A2A_STATE. The allowed-move table above is this example's own design; the specification read here does not give one in this form. The protocol's operations for getting, listing and canceling tasks are on A2A.
What this is not. A task lifecycle is the state of one piece of delegated work, seen across two agents. The state of a whole workflow (which steps have run, which come next, under which condition) is orchestration and belongs to orchestrate.sammuthu.com. Saving a task's progress so it survives a restart belongs to memory.sammuthu.com.
Checklist: a lifecycle review#
- Is there one written table of states and allowed moves, shared by every agent?
- Are terminal states really terminal, in the owner's code and in the caller's view?
- Does every refused move return a named error?
- Is a question back an interrupted state on the same task, answered by a message that names the task?
- Does the caller's deadline stop while the task waits for the caller?
- Does the caller ignore stale updates (a sequence number per task)?
- Does the contract say what cancel guarantees and what it does not?
- Is a late result after a cancel discarded, and logged?
The same idea for a coding agent. A planning agent asks a test agent to run the suite. The test agent finds that one test needs a secret it does not have and moves to auth-required. The planning agent grants a narrower token and the same task resumes. Later the developer closes the pull request; the planning agent cancels the task, and the test run stops, but the three test jobs already started in CI have run. CI does not know about the agents' task states, and the cancel does not reach it unless someone wires it there; shipping concerns like this belong to diff-to-deploy.sammuthu.com.
When may a task be rejected?This example allows it only from submitted; the specification describes more
In the example, rejected is reachable only from submitted: the callee decides at the door, after validation and authorization, and never halfway. The A2A specification read today describes rejected as the agent deciding not to perform the task, which can happen at creation or later once the agent decides not to proceed. Both are defensible. Rejecting only at the door makes rejected mean "never started", which is simple to reason about and safe to retry elsewhere. Allowing it later lets an agent stop work it discovers it should not do, at the price that a rejected task may have done some work. If you allow the second, say so in the contract, and treat a late rejection like a failure for compensation.
Where the task table livesA state machine is only as durable as its storage
The example keeps tasks in memory, which is enough for a simulation. In production the owner's task table must survive a restart, or every restart turns working tasks into tasks that never finish, and callers into deadline handlers. The usual design is a row per task with its state and a version number, updated with a compare-and-set on the version, so two workers cannot both move the same task. The caller's view needs the same care if the caller must survive a restart while waiting fifteen minutes for a broker.
Durable task state is saved execution state; its design belongs to memory.sammuthu.com. The lifecycle only defines which states the stored row may hold and which moves are legal.
Cancel is a request, not a commandRaces, partial work and what the caller may assume
A cancel races with completion. If the callee finishes at the same moment the cancel arrives, one of them wins, and the loser gets a refusal: either the cancel is refused with TASK_NOT_CANCELABLE, or a late completion finds the task canceled and is discarded. Both are correct outcomes; the caller must handle both. What the caller may not assume is that a successful cancel means no work happened. It means no further work will be started under this task.
Cancel also has to travel. In the example the coordinator cancels its own task and forwards the cancel to every unfinished child (Agent.forward_cancel). A child that never answered has no task id yet; the coordinator forgets it locally, and if it answers later, the answer is unmatched. In a deep hierarchy, a cancel that is not forwarded leaves orphan work running below.
In one breath#
A task is a piece of delegated work with an id and a state. It moves through a small state machine, submitted, working, possibly input-required, and ends in one terminal state, completed, failed, canceled or rejected, which never moves again. A question back pauses the same task until the caller answers; cancel stops future work but undoes nothing, and a cancel on a finished task is refused by name.
Next: everything so far assumed the caller knew whom to ask. Discovery is about how a caller finds an agent and learns what it accepts, and why what an agent says about itself is a claim, not a guarantee.