Repository navigation
[DRAFT] A2A 1.1: protocol changes and implementation breakdown #1449
Replies: 2 comments 1 reply
I'd recommend to avoid coupling generation with task store version used for MVCC even if in practice they'll often be the same. In some cases forcing a sequence with no gaps can be limiting for task store implementations. So I'd keep an internal (never exposed to clients) task version + add a generation managed by the server (not agentExecutor implementation).
We requested to relax these requirements so that servers MAY replay events or emit a snapshot, so that implementations are not forced to keep an event log (a2aproject/A2A#2411). # New class attribute; executors that don't set it keep QUEUE.
input_policy: ClassVar[InputPolicy] = InputPolicy.QUEUEI'd make live input a server option instead of an executor class attribute, and default to rejection instead of QUEUE. A class attribute has to be forwarded by every wrapper (called out for handler = DefaultRequestHandlerV2(agent_executor=executor, ..., live_input=True)I also think rejection is a better default because an executor that hasn't opted in is unlikely to be checking inputs, so:
# Takes every input that has already arrived, without waiting; empty if none.
def pending(self) -> list[ClientInput]: ...It covers agents that check between steps, but there's no simple way to stop a streaming llm reply when new input arrives. I guess an option is to race tasks by hand, which is very inconvenient: reply = asyncio.create_task(self.stream_reply(msg, updater))
nxt = asyncio.create_task(anext(aiter(context.inputs)))
done, _ = await asyncio.wait({reply, nxt}, return_when=asyncio.FIRST_COMPLETED)
...In Go I'd expose it through replyCtx, stop := inputs.CancelOnInput(ctx) // canceled when input arrives, the input stays queued
err := a.streamReply(replyCtx, ec, msg, yield)
stop()Python equivalent could be a cancel scope, smth like: async with context.inputs.interrupt_on_input(): # cancels the block on new input, the input stays in the inbox
await self.stream_reply(msg, updater)
Meaning that with N replicas without sticky routing a follow-up succeeds with prob 1/N, and retries don't really improve the odds. There's no good sticky key because the task id is in the request body, and a new task's id is assigned by whichever replica creates it. Conditional follow-ups are affected the same way. There should be an extension point for routing inputs to the replica that runs the task. In a2a-go a replica accepting a message writes to a workqueue.Queue, and the queue implementation decides where work runs. So a routing queue can forward follow-ups to the node running the execution. #1395 introduces It's a large topic, and we can have a separate discussion of conditional follow-ups and bidi in cluster mode 🙂 |
|
Two notes from working the task-state surface in this SDK recently (fixed #1331/#1345; #1346 pending re-review) — one supports the decoupling point, one is an implementation-level caution for 1.1. 1. Assign Task-state writes all funnel through This also supports @yarolegovich's decoupling suggestion: with 2. On 5.1 — I'd like to claim the version-negotiation fix as a standalone issue + PR. Scope as sketched in the document: |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
1. Task generation
1.1
generationon tasks and eventsA2A 1.1 gives every task a version number,
generation(#1810). The server increases it by one on each change to the task and puts the new value on the event that reports the change. Clients use it to order events, to notice when they missed one, and as the basis for long-polling (1.2), conditional sends (1.3) and resuming a stream (1.4).The Python SDK already has most of this as an opt-in feature. In cluster mode,
VersionedTaskStoreattaches aTaskVersionto every stored task, andTaskEventStreamdelivers the events written after a given version to other replicas. 1.1 support is planned for a2a-python 2.0, which makes the versioned store the default and addsgenerationas a field the server manages.TaskVersionstays internal and is used only for compare-and-swap, so stores aren't forced to keep a gap-free counter.Proto changes (Task, Artifact and events):
spec 3.2.7:
spec 3.2.7:
On the wire, a
SubscribeToTaskstream where another client answers anINPUT_REQUIREDprompt:A
1.0subscriber on the same task does not receive themessageUpdate(section 2.2). It sees3 → 5, recognizes the gap, and callsGetTaskto catch up.Proposed SDK implementation
Today
VersionedDatabaseTaskStorealready saves with a compare-and-swap on an integer version and appends the event totask_eventsin the same transaction, andDatabaseTaskEventStreamreplays that log after a given version. Without a versioned store there is no version and no event log.In 2.0 this can become the only path. The store version stays internal: it never reaches clients, and a store can use any value that orders writes, such as a counter, a commit timestamp or an etag.
generationis a separate field that the server sets before each save that changes the task:A save that loses the compare-and-swap writes nothing, so generations stay gap-free without any requirement on the store's version. Saves that change nothing a client sees advance only the version.
VersionedDatabaseTaskStorekeeps itstask_versionstable and adds agenerationcolumn to the tasks row and totask_events, so the event log can be read from a client's generation (sections 1.2 and 1.4). The migration fillsgenerationfrom the current version.TaskEventStream.subscribegets a second cursor,after_generation, next to the existingafterversion.InMemoryTaskStorebecomes a versioned store too, with a per-task lock and an in-memory event log, so a single-process server behaves the same way as a cluster.A few writes break the one-change-one-event rule today: a task whose agent starts with a status update is created by two saves, and a cancel from another replica is written without going through
TaskManager. In 2.0 each of these produces one event and advancesgenerationonce. Saves that change nothing a client sees still happen, but they advance only the internal version.1.2 Long-polling
GetTaskA client that polls a task can now ask the server to wait until the task changes, instead of polling in a loop. It passes the last
generationit saw inGetTask, and the server answers once the task has moved past it (#1810).Proto changes (a2a.proto):
spec 3.2.7:
On the wire, a client that last saw generation 3:
The server holds the request until the next change, then answers (fields trimmed):
{ "id": "task-abc", "status": { "state": "TASK_STATE_WORKING" }, "generation": "4" }Proposed SDK implementation
Long-polling needs no new mechanism. Waiting until the task passes generation G is the same as waiting for the first event after G, and
TaskEventStream.subscribe(task_id, after_generation=G)already yields exactly those events.1.3 Conditional sends:
ifGenerationMatchWhen two clients reply to the same task, one of them can overwrite the other's input without knowing it. A client can now send a follow-up with "only if the task is still at generation N". If the task has moved on, the server rejects the message with the new
TaskGenerationMismatchError: JSON-RPC-32010, gRPCABORTED, HTTP409(spec 5.4, #1810).Proto changes (a2a.proto):
spec 3.2.2:
On the wire, a client replies to the task it last saw at generation 3:
{ "message": { "messageId": "msg-7", "taskId": "task-abc", "role": "ROLE_USER", "parts": [{ "text": "Approve option B." }] }, "configuration": { "ifGenerationMatch": "3" } }Another client got there first and the task is at generation 5, so the server rejects the reply (spec 11.6, trimmed):
Proposed SDK implementation
Today a follow-up message is written lazily inside
ActiveTaskwhen the agent emits its first event, where an error fails the whole task. It can be written in_setup_active_taskinstead, which already loads the task before any response starts, as one compare-and-swap write:Say the task is at generation 5 and the client sends
ifGenerationMatch=5. If nothing changed, (D) saves the message as generation 6, and the agent's events follow as 7, 8 and so on. If another client's message already moved the task to 6, (C) returnsTaskGenerationMismatchErrorand nothing is saved. If the agent writes generation 6 between (A) and (D), the save in (D) fails and (E) returns the same error. If the conflict came from an internal save that leftgenerationat 5, (E) sees the expected generation and retries instead of returning a mismatch.The error reaches the client through the existing error mapping, and the task itself is not failed.
Client:
1.4 Resuming a subscription
When a stream drops, the client can reconnect with the last
generationit saw, and the server sends only what happened after it instead of a full snapshot (#2153). The field lives onSubscribeToTaskRequest, so it works both forSubscribeToTaskand for thesubscribeopening of a live stream (section 3.3).Proto changes (a2a.proto):
spec 3.1.12:
These rules are written for live streams. For plain
SubscribeToTask, the proto comment leaves out the fallback, and spec 3.1.6 still requires aTaskas the first event.On the wire, a client that saw generation 5 before the connection dropped:
Proposed SDK implementation
_subscribe_remotealready sends a snapshot and then reads the event log after the snapshot's version. Resume is the same read without the snapshot, starting after the client's generation. That loop can be extracted, with a generation cursor next to the version cursor:Then
on_subscribe_to_taskgets one new branch after the terminal check:When the field is unset, or the server can't replay (no event log, or a generation the task hasn't reached), the existing branches send a snapshot as the spec requires. The REST dispatcher also needs to parse
?lastSeenGeneration=onGET /tasks/{id}:subscribe, ason_get_taskalready does for its query parameters.RestTransport.subscribeswitches fromPOSTtoGET, since spec 5.3 now listsGET /tasks/{id}:subscribeto match the proto (#2068), and retries withPOSTon a405from servers that follow the 1.0 spec text.Client:
2. Task timeline
2.1
timelinereplaceshistoryTask.timelinerecords client messages and agent status updates in generation order, while artifacts stay inTask.artifactswithstart_generationandend_generationbounds (ADR-002; #2084, #2129).Task.historyand the threehistory_lengthfields are marked[deprecated = true]for removal in2.0(spec 3.2.4).Proto changes (Task, TimelineEntry, GetTaskRequest):
spec 3.2.8:
spec 3.2.8:
On the wire, a
GetTaskresponse (messageId,contextIdandtaskIdleft out of the messages):{ "id": "task-123", "generation": "7", // the task has changed 7 times "status": { "state": "TASK_STATE_COMPLETED", "message": { "role": "ROLE_AGENT", "parts": [{ "text": "Done." }] } }, "timeline": [ // client message { "generation": "1", "message": { "role": "ROLE_USER", "parts": [{ "text": "Summarize Q3" }] } }, // agent status update { "generation": "2", "status": { "state": "TASK_STATE_WORKING" } }, // no entries for 3 and 4: those changes are the artifact chunks below { "generation": "5", "status": { "state": "TASK_STATE_INPUT_REQUIRED", "message": { "role": "ROLE_AGENT", "parts": [{ "text": "Which region?" }] } } }, { "generation": "6", "message": { "role": "ROLE_USER", "parts": [{ "text": "EMEA" }] } }, { "generation": "7", "status": { "state": "TASK_STATE_COMPLETED", "message": { "role": "ROLE_AGENT", "parts": [{ "text": "Done." }] } } } ], "artifacts": [ // first chunk at 3, last chunk at 4, so it sits between timeline entries 2 and 5 { "artifactId": "a-1", "parts": [{ "text": "# Q3\n" }, { "text": "Up 4%.\n" }], "startGeneration": "3", "endGeneration": "4" } ], "history": [ ... ] // unchanged from 1.0 }Proposed SDK implementation
TaskManager.save_task_eventalready applies each agent event to a copy of the task before saving it, and that save is the single write from section 1.1. The timeline and the artifact bounds are filled in at the same place, using the generation that write will get:end_generationis set only by a chunk withlast_chunk=True. The spec defines it as the generation at which the artifact completed, but does not tie it tolast_chunkor say what happens to an artifact that is still open when the task reaches a terminal state, so the SDK leaves it unset in that case.2.2
TaskMessageUpdateEventTaskMessageUpdateEvent(StreamResponse.message_update) notifies subscribers when a message is appended to a task (#2153).Proto changes (TaskMessageUpdateEvent, StreamResponse):
spec 3.2.8:
On the wire, one SSE event for a
1.1subscriber (JSON-RPC):{ "jsonrpc": "2.0", "id": 5, "result": { "messageUpdate": { "taskId": "task-123", "contextId": "ctx-7", "message": { "messageId": "m-2", "role": "ROLE_USER", "parts": [{ "text": "EMEA" }] }, "generation": "6" } } }Proposed SDK implementation
The implementation is already in section 1.3: its single save stores the follow-up message and the
TaskMessageUpdateEvent.A
ServerCallContext.protocol_versionfield, filled by each transport from the request'sA2A-Version, needs to be added, along with a check inActiveTask.subscribeand_tail_eventsthat skipsTaskMessageUpdateEventfor versions below1.1.3. Streaming
3.1 Unknown payloads must be skipped
Later
1.xversions can add new kinds of stream events, stream requests and timeline entries (#2153, #2129). Code that receives a kind it doesn't know has to carry on instead of failing.spec 3.2.3:
spec 3.2.3:
For example, a client reads a stream that contains an event kind added after its SDK was released:
Proposed SDK implementation
Today the client doesn't skip such events. On JSON-RPC, REST and gRPC alike, it drops the part it doesn't understand and hands the app an empty
StreamResponse.The fix is a small check in
BaseClient._process_stream, which all three transports go through, before interceptors and plugins see the event:On the server, two places raise
ValueErroron an unknown event kind and break the stream: the converter that turns events into v0.3 responses (to_compat_stream_response), and the clusterDatabaseTaskEventStream, which reads events written by other replicas. Both should skip the event instead. An unknown request on a live stream is rejected withINVALID_ARGUMENT, as described in section 3.3.3.2 Interrupted states no longer end streams
In
1.0, a stream ended as soon as the task asked the user for input or authorization.dev-1.1changes this:INPUT_REQUIREDandAUTH_REQUIREDare now non-terminal states, and reaching one SHOULD NOT close the stream on its own. Only a terminal state MUST close it (#2270). A client can keep reading the same stream while the user answers and see the agent carry on. A blockingSendMessageworks differently: it still returns as soon as the task reaches a terminal or an interrupted state (spec 3.2.2).spec 3.1.2:
spec 4.1.3:
Proposed SDK implementation
Today the SDK's three streaming paths end a stream at different points.
SendStreamingMessageends when the agent's turn ends. ASubscribeToTaskserved by the replica that runs the agent stays open through interrupted states, while one served from another replica's event log stops at them.For
1.1clients, all three should stay open until the task reaches a terminal state. For1.0and0.3clients they keep the v1.0.1 rule and close at an interrupted state, so the localSubscribeToTaskstarts closing there too.Both loops that end streams get the same check:
ActiveTask.subscribe, which serves subscribers on the same replica, and_tail_events, which reads the event log for other replicas and resumed streams. After yielding each event:A
1.1client that callsSendStreamingMessagethen keeps receiving events after the agent's turn ends, until the task finishes, while an older client still sees the stream end with the turn. TheSendLiveMessagedownlink in section 3.3 follows the same rule.On the client side, a
1.1stream no longer ends when the agent asks for input, so code that waited for the end of the stream should look at the task state instead.An opt-in
ClientConfig.stop_on_interruptedflag can be added to end the client's stream at an interrupted state, so apps that relied on the old behavior keep working without code changes.3.3
SendLiveMessageSendLiveMessageis a bidirectional streaming RPC gated byAgentCard.capabilities.streaming(spec 3.3.4, #2153). The first request binds the stream to one task, and individual uplink requests can be rejected in-band withStreamError.Proto changes (A2AService, StreamRequest, StreamError):
spec 3.1.12:
On the wire, a gRPC stream where the client adds input while the agent works (payloads trimmed):
If the agent isn't taking input at that moment, msg-2 is declined instead. Nothing is saved, and only the sender sees the error:
Proposed SDK implementation
Today
AgentExecutor.execute()gets one message and can't receive more while it runs. A follow-up sent mid-turn waits inActiveTask._request_queueand runs as the next turn. That stays the behavior for unary and streamingSendMessage. ForSendLiveMessage, the handler gets alive_inputoption:The handler reads its own setting, so wrappers such as
PluginAgentExecutorhave nothing to forward.live_inputonly changes what happens to a live uplink while a turn runs. ASendMessagefollow-up still waits for the current turn and runs as the next one, and a live uplink that arrives between turns starts a turn either way, so existing executors need no changes.live_input=Trueonly helps an executor that readscontext.inputs; input it never reads is carried over and starts the next turn.pending()suits agents that check between steps. An agent that streams one long reply can wrap it ininterrupt_on_input()instead. The block is cancelled as soon as input is in the inbox, including input that arrived just before the block started, and the input stays there to be read afterwards. With a closed inbox (live_input=False, or afterclose()) the scope never fires, so agents can use it unconditionally. A cancellation from outside, such as a task cancel, passes through the scope.An agent that stops its reply when the user sends something new:
On the server, each
SendLiveMessagecall gets aLiveSession. Its uplink requests go through an admission step that either declines a request, which sends aStreamErrorto that connection only, or accepts it and saves the message with amessageUpdate. An accepted message starts a turn if none is running, or goes to the running turn'scontext.inputswhenlive_inputis on. Unary and streamingSendMessagekeep today's path through_request_queue. The downlink sends aTasksnapshot first, then every task event until a terminal state, along with this connection's errors.The gRPC method hands the stream to the handler, which creates one
LiveSessionper call:LiveSessionbinds the stream on the first request and reads the uplink:Admission decides and saves while holding a per-task lock, so a turn can't start or end in between:
ActiveTask._run_produceropens an inbox for each turn and, whenexecute()returns, hands unread input to the next turn, both underadmission_lock:_start_pending_turnonly puts the nextRequestContexton_request_queue, so it never waits while holding the lock. Unread live input becomes one turn, with the first input ascontext.messageand the rest carried over intocontext.inputs. A terminal task runs nothing, and each pending input's sender getsStreamError(FAILED_PRECONDITION).StreamErrorgoes only to the connection that sent the request, never to other subscribers or push webhooks:INVALID_ARGUMENT: a latersubscribe, an unknown payload kind, or a request for another task.UNAVAILABLE: a turn is running andlive_inputis off, or another replica holds the task's execution lease (#1395).ABORTED:ifGenerationMatchdoesn't match.FAILED_PRECONDITION: the task is already terminal, or it ended before the agent read the input. In that case the message is in the timeline, but the agent never saw it.With the execution lease from #1395, one replica runs a task's turns. A gRPC stream stays on one replica, so
live_inputworks when that replica runs the turn, and input sent to another replica mid-turn getsUNAVAILABLE.Client: a
client.send_live_message(...)method can be added, named after the RPC likesend_message:Like
on_message_send_streamandon_subscribe_to_task, the newon_send_live_messagehandler gets@validate(capabilities.streaming), so agents that don't advertise streaming returnUnsupportedOperationError(spec 3.3.4).client.send_live_message(...)raises before connecting in that case, since there is no non-streaming fallback.SendLiveMessagehas no binding definitions in spec sections 9–11 yet, and open issue #2415 notes that HTTP lacks a way to tell a short-lived uplinkPOST /message:livecall from a new downlink stream or routeStreamErroracross connections (uplink ack media types and rejection statuses are also undefined). Because spec 3.3.4 and spec 5.1 in effect require every1.1streaming interface to supportSendLiveMessage, gRPC support can ship first, once #2411 settles, with1.1advertised on HTTP interfaces only after#2415and the HTTP/JSON-RPC bindings land.4. Client input and delivery
4.1 Client-written artifacts
When
AgentCard.capabilities.userArtifactsistrue, clients MAY sendTaskArtifactUpdateEventitems inSendMessageRequest.artifactUpdatesoverSendMessage,SendStreamingMessage, orSendLiveMessage(#2322).Unset
Artifact.rolemeans an agent artifact (ROLE_AGENT).Sending
artifactUpdateswithout the capability returnsUnsupportedOperationErrororStreamError(spec 3.3.4).Proto changes (Artifact, AgentCapabilities, SendMessageRequest):
spec 3.2.1:
On the wire (creating a task with an input artifact):
Proposed SDK implementation
Today the request path assumes
params.messageis always present._setup_active_taskreads the task and context IDs from it, andRequestContextwrites generated IDs back into it, so an artifacts-only request would get an emptyMessageand start a new task.The client input is written in
_setup_active_task, next to the message write from section 1.3:_save_client_artifactfills in a missingtask_idandcontext_id, rejects an update that names a different task, setsartifact.role = ROLE_USER, ignores the client'sgeneration, and saves the update the same waysave_task_eventsaves agent artifacts (section 2.1).The agent sees the request through
RequestContext, which needs two changes:RequestContext.messagereturnsNonewhen the request has no message. Today it returns an emptyMessage, because proto3 gives a default value for an unset field, so the agent can't tell a missing message from an empty one. Executors of agents that setuser_artifactsneed aNonecheck.RequestContext.artifact_updatesreturns the updates that came with this request, withroleand the IDs already set by the server.Client:
BaseClient.send_messageneeds a check that refusesartifact_updatesunless the agent card setsuser_artifacts, like the existingextended_agent_cardcheck in the transports, so1.0and0.3servers never receive them.4.2 Push notification
protocolVersionTaskPushNotificationConfiggets aprotocol_versionfield: the A2A version the server uses when it delivers notifications to that webhook (#2153).Proto changes (TaskPushNotificationConfig):
On the wire, a client creates a config without
protocolVersion:The server stores and returns it with the version of the creating request:
{ "taskId": "task-123", "id": "cfg-1", "url": "https://client.example.com/webhook", "token": "opaque-token", "protocolVersion": "1.1" }Proposed SDK implementation
Today
normalize_push_notification_configcopies the client's config and sets onlytask_idand a defaultid. It needs the request's version as a new argument, so it can fill in an unsetprotocol_version:Both places that create configs pass the version:
CreateTaskPushNotificationConfigandSendMessageConfiguration.task_push_notification_config. Delivery doesn't change in 1.1: spec 4.3.3 lists the same four payload kinds (task,message,statusUpdate,artifactUpdate) for every version.4.3 Agent Card media type (
application/a2a-agent-card+json)dev-1.1definesapplication/a2a-agent-card+json(UTF-8, no parameters) to identify a JSONAgentCardindependently of protocol bindings (spec 8.1, #2380). The spec defines the type and its IANA registration template (spec 14.1.2), but doesn't require servers to serve it or clients to request it.Request:
Response:
Proposed SDK implementation
create_agent_card_routes): the public card endpoint (/.well-known/agent-card.json) picks the response type from the request'sAcceptheader. When the client asks forapplication/a2a-agent-card+json, the response uses that type. Otherwise (application/json,*/*, or noAccept, which is what every client sends today) it staysapplication/json. The JSON body is the same either way. The response also getsVary: Accept, so HTTP caches keep the two variants apart.A2ACardResolver): sendsAccept: application/a2a-agent-card+json, application/json;q=0.9by default. This asks for the new type and still accepts plain JSON from servers that don't support it./extendedAgentCardkeepsapplication/a2a+json. It is theGetExtendedAgentCardoperation of the REST binding, served like every other operation, and spec 14.1 separates the two types:application/a2a+jsonfor protocol messages, andapplication/a2a-agent-card+jsonfor Agent Card documents used for discovery.5. Existing SDK issues to fix
5.1 Protocol version negotiation
spec 3.6.2:
Today the SDK follows this only in part:
ClientFactorypicks an interface with exactly1.0first, ignoring card order, and otherwise takes the first interface with any higher version, even a future major version such as2.0that it can't speak. Every request sendsA2A-Version: 1.0, whichever interface it picked.1.0server acceptsA2A-Version: 1.1and silently ignoresifGenerationMatch. The gRPC handler doesn't check the version at all, and neither records it.Proposed SDK implementation
ClientFactoryselects the first interface in card order (spec 8.2.2) whose version the SDK supports (0.3,1.0or1.1), and the existingA2A-Versionheader anda2a-versiongRPC metadata carry that interface'sMajor.Minorversion instead of the fixed1.0.validate_versioncomparesMajor.Minoragainst the versions the card declares for that interface and stores the accepted version in a newServerCallContext.protocol_versionfield. The gRPC handler gets the same check ona2a-versionmetadata.6. Not in 1.1 yet
#2399 (
TaskViewonGetTaskandListTasks)Replaces all three
timeline_lengthfields with aTaskViewenum onGetTaskRequestandListTasksRequest.TASK_VIEW_FULLreturns every field, andTASK_VIEW_METADATAleaves outartifacts,history,timeline, and possibly futureTaskfields.GetTaskdefaults to the full view;ListTaskswithviewunset omitstimeline. In the SDK, a view helper and SQL column deferral inDatabaseTaskStore.listwould cover it.#2426 (Timestamps across the task model)
Open with one approving review and no gitvote; it subsumes #2423. It adds server-set timestamps to
Task(createdAt,updatedAt),TimelineEntry,Artifact,TaskStatusUpdateEventandTaskMessageUpdateEvent, deprecatesTaskStatus.timestampandListTasksRequest.status_timestamp_after, and changesListTasksto SHOULD sort bycreatedAtdescending.TaskManagercan stamp these alongsidegeneration.#2310 (Sender and creator attribution)
Adds
Message.senderplusArtifact.creatorandArtifact.contributorsfor multi-actor tasks. ItsArtifactfield10currently collides withArtifact.updated_at = 10in #2426, and its text refers toTimelineEntry(Artifact)items, which don't exist.All reactions