Tasks: state that outlives the request

Tasks: state that outlives the request

A message is one turn: a role (ROLE_USER or ROLE_AGENT), an id, and parts (text, raw bytes, a URL or JSON data; exactly one kind per part). A task is what the agent creates when the work is more than one reply. It has a server-generated id, a context id that groups related tasks, a status, a history, and artifacts (the results).

• SUBMITTED and WORKING are the two ordinary ones.
• INPUT_REQUIRED means the agent needs something from you to continue. You answer with a message to the same task id.
• AUTH_REQUIRED means the agent needs a credential, usually for something at another service. The specification is careful here (section 7.6.4): the state is not itself authorization. In the example the agent hands over a link and gets the credential out of band, through a callback from the place where the person agreed. The client's job is to show the person the link, never to invent a credential.
• COMPLETED, FAILED, CANCELED, REJECTED are final. A task in a final state cannot be reopened; a follow-up is a new task in the same context. REJECTED means the agent declined before starting.

My choice: the specification lists the states but gives no transition table. The one in model.py is my reading, and a test checks that final states have no exits and that an executor trying an illegal move gets an error and not a silent change. Another implementer might allow WORKING to go back to SUBMITTED; say so if you rely on it.

Messages, artifacts, context

• Results are artifacts, not the last message. A venue shortlist arrives as an artifact in chunks (text and a JSON data part); each chunk says whether it appends to an earlier one. A final status message explains, but the data is in the artifact.
• Context groups tasks: "Same again but for 2 days" in the context of an earlier request lets the agent reuse the city and headcount. A context belongs to the principal who started it. If Bob names Alice's context id, the clean server answers InvalidParams. With the defect context_hijack, Bob's request is quietly answered with Alice's remembered brief (Lisbon, 120 people). The check exists because the failure is invisible in a happy-path test.
• A message to a task that is still working is added to its history in this example (my choice; the agent may ignore it, and a real agent might re-plan).
• Listing tasks is paged with an opaque token and sorted by the time of the last status change, newest first. Tests confirm that every page size from 1 to 50 visits every task exactly once, that a stale token still works after new tasks arrive, and that bad parameters give InvalidParams.

Two bindings, one set of operations

The specification defines the operations once (SendMessage, SendStreamingMessage, GetTask, ListTasks, CancelTask, SubscribeToTask, push-notification configuration, GetExtendedAgentCard) and then three bindings. The example implements two:

The check Q1 sends the same sequence through both and compares the results; most bugs that appear in only one binding are mapping mistakes.

Errors: nine codes, and six of them are HTTP 400

The specification's error table (section 5.4) gives each error a JSON-RPC code, a status string and an HTTP status. Six of the nine share HTTP 400, so on HTTP+JSON the status alone cannot tell "this task cannot be cancelled" from "this agent does not support push". The distinguishing part is the reason in ErrorInfo (TASK_NOT_CANCELABLE, PUSH_NOTIFICATION_NOT_SUPPORTED, and so on) with the domain a2a-protocol.org. The test file checks every row against the table and checks the round-trip from each binding back to the error name.

TABLE = {"TaskNotFoundError": (-32001, "NOT_FOUND", 404),
         "TaskNotCancelableError": (-32002, "FAILED_PRECONDITION", 400), ...}

def reason_of(name):               # TaskNotFoundError -> TASK_NOT_FOUND
    return re.sub(r"(?<!^)(?=[A-Z])", "_", name.removesuffix("Error")).upper()

Where the specification disagrees with itself: its examples show different HTTP error bodies in different places. I followed the table and the ErrorInfo rule, and I put a JSON-RPC version error in an HTTP 200 (it is a JSON-RPC response, so the transport worked). A strict reading might differ.

A rule that is easy to miss: say nothing about what you do not show

Section 13.1 asks for every operation to be scoped to the caller and never to reveal that a resource exists. In the example, asking for a task that belongs to someone else gives the same TaskNotFound as asking for one that does not exist. The defect forbidden_vs_missing returns "forbidden" for the first, which tells an attacker which ids are real; check A4 catches it.

Finding out that a long job finished

The venue agent has a "thorough search" that takes 20 virtual seconds. There are three ways to learn it is done, and I measured each.

The trade-off is the usual one: polling costs requests (or lateness), streaming needs an open connection for the whole job, and push needs a public receiver and a way to trust what arrives.

Streaming has two details that matter. The first event is the full task (a client that subscribes to a running task gets a snapshot of what exists, including artifacts so far, and then changes), and a dropped connection is repaired by subscribing again. The test cuts a stream after two events, resubscribes, and gets the final state and the artifacts.

Push notifications are the dangerous one, because the server will make an HTTP request to an address the client gave it. That is a server-side request forgery (SSRF) opening. The specification asks (section 13.2) for the server to guard the URL. The example resolves the name once, refuses private, loopback and link-local addresses, refuses non-HTTPS, and connects to the address it checked (so the name cannot change between check and use). Three honeypots (10.0.0.5, 169.254.169.254, 127.0.0.1) record any hit; the tests assert there are none, including when an agent's executor tries to fetch a URL it found in a message.

Three more push details:

• Credentials travel with the notification (a Bearer credential, and a token header). My choice: the specification's 1.0 text does not say where the extra token is sent; I used the 0.3 header X-A2A-Notification-Token. And configuration is redacted on reads: a client can list its configs and see the scheme, never the secret.
• A race. Webhook events can arrive before the reply to the send call, so a receiver cannot be told "expect task X" up front. The example's receiver instead binds a credential to a task on first use and refuses the same credential for a different task. A receiver written the obvious way, which must already know the task id, got 15 delivery attempts, all answered 404.
• Retries. A failing receiver gets retried three times and then dropped; an unreachable one must not fail the task. (One planted defect, no_push_retry, escapes my suite; see section 9.)