# Delivery lifecycle Source: https://docs.ideharmony.com/a2a/delivery-lifecycle Most multi-agent tooling collapses everything between "sent" and "done" into a single cheerful "delivered". Harmony does not, because the gap between those two states is where all the confusion lives. ## The problem this solves When you send a message to another agent, several different things can be true, and they look identical from the outside: - The text reached the agent's harness, but no model turn started. - The text is sitting in a queue behind other work. - The text is staged in the composer and needs one more keypress. - The agent is genuinely working on it. A tool that reports all four as "delivered" is not reporting; it is guessing. ## The shape of it
A2A delivery statesA message you send reaches one of six reported states. Only received_and_started means a turn began. Queued_behind means it is in the harness queue with a measured depth. Received_not_started means the text arrived with no work signal. Needs_enter means it is staged in the composer and will never run until submitted. Idle means the agent is at an empty prompt, which may mean your message never arrived. Unknown means the evidence was insufficient and Harmony declined to guess.You senda2a messageClassifierevidence onlyreceived_and_started — STARTEDqueued_behind — not started, depth Nreceived_not_started — no work signalneeds_enter — staged, never submittedidle — empty promptunknown — insufficient evidenceONLYTHIS
Five of the six states mean work has not begun. Only received_and_started sets started to true.
## The states Harmony actually reports These are the delivery states in the shipping source, not a generic lifecycle: | State | Means | Started? | Queued? | |---|---|---|---| | `received_and_started` | The agent is working on a turn | Yes | No | | `queued_behind` | Accepted into the harness queue, with N ahead | No | Yes | | `received_not_started` | Text delivered, no work signal yet | No | No | | `idle` | At the prompt, queue empty | No | No | | `needs_enter` | Staged in the composer, needs another Enter | No | No | | `unknown` | Could not be determined | No | No | Alongside the state, a delivery status carries a **queue depth** (how many prompts are pending — `0` means empty, absent means unmeasured) and a human-readable summary line. > [!IMPORTANT] > `started` is true **only** when the state is `received_and_started`. Nothing > else in this table means work began. In particular, `queued_behind` and > `received_not_started` are both "not started" — they simply fail differently. ## Never claim a start without evidence The classifier is deliberately conservative. It derives state from observable evidence — screen content, detector status, and measured queue depth — and it reports `unknown` rather than guessing when the evidence is absent. This is why you will sometimes see `unknown`. That is the system declining to invent a status, and it is more useful than a confident wrong answer. ## `needs_enter` deserves special attention `needs_enter` means the message reached the agent's composer but was never submitted. Everything looks fine — the text is there, the agent is alive — and nothing will ever happen. This is the single most common "why is my agent ignoring me" cause, and it is precisely the state that a generic "delivered" would hide. ## Queue depth changes what a state means `queued_behind` with a depth of 1 and a depth of 40 are very different situations. Read the depth before deciding whether to wait or to intervene. > [!NOTE] > A queue draining slowly is not a failure. Sending the same message again > because nothing appeared to happen usually makes it worse — you end up with > the request queued twice. ## Task state is a separate question Delivery state describes whether a message reached an agent and whether work began. It does not describe whether the work is any good, or whether the task finished. A durable task carries its own state, and completion of a task is not implied by successful delivery of the message that requested it. Check both: ```powershell harmony tasks list ``` ## Reading it correctly | You see | Conclude | Do | |---|---|---| | `received_and_started` | Work is in progress | Wait | | `queued_behind`, depth 2 | Not started, will start soon | Wait | | `queued_behind`, depth 40 | Not started, may not start soon | Investigate the queue | | `received_not_started` | Arrived, no work signal | Give it a moment, then check the agent | | `needs_enter` | Stuck in the composer | Submit it | | `idle` | Agent is free | Your message may not have arrived at all | | `unknown` | No evidence either way | Look at the agent directly | ## Related - [A2A overview](/docs/a2a) - [Channels](/docs/a2a/channels) - [Tasks, plans, and runs](/docs/concepts/tasks-plans-and-runs) - [Known limitations](/docs/reference/known-limitations)