What changed since the Draft
The themes of the Draft all still stand: prompts that don’t own the turn, updates patched by ID, structured diffs, flexible permission requests, and extensible enums. Everything below is new since then.The prompt lifecycle, filled in
The Draft said that asession/prompt response acknowledges the prompt and doesn’t end the turn. Implementing that raised questions the Draft didn’t answer.
The response now returns the messageId of the user message the Agent inserted into the conversation. If you get a response, the message is in. If you get a JSON-RPC error, it isn’t.
Clients can send a prompt in any state, and an Agent can’t reject one only because it is busy. It inserts the prompt right away, or holds it and inserts it later in the order received. The response to a held prompt stays pending until the Agent inserts it. Whether a prompt inserted during active work steers that work or starts the next round is up to the Agent, for now. Steering and queueing definitions are coming!
When work fails after the prompt was inserted, the Agent ends it with an idle state_update whose stop reason is error. The update can carry a JSON-RPC error object, so a Client can react to the code as it would for an error response.
The prompt lifecycle page now defines every state transition too.
Background work
Once a session can beidle while work continues, a Client needs to know what is still running. State updates now carry a background list that names the terminals, tool calls, and subagents running independently of the foreground work. A Client uses it to tell whether a session is quiet, and what closing the session would stop.
Tool calls gain a paused status for suspended work. A tool call or terminal can also advertise capabilities.cancel, and then the Client can stop that one item with tool_call/cancel or terminal/cancel, while session/cancel still stops the foreground work as a whole.
You can read more about this in the Background Work RFD.
Subagents in the baseline
Agents can expose the subagents they delegate work to as child sessions. Each child has its ownsessionId, and its messages, plans, and tool calls arrive as ordinary session updates. The Agent announces a child with subagent_update on the parent session, and reports messages between sessions with session_message.
Subagents are stable in v1 too, where Clients opt in with a capability. In v2 there is no capability. Every Client handles child sessions, even if it chooses not to show them in a view of their own.
Reconnecting without guessing
Connections drop, and they will drop more often once remote transports arrive. A Client that reconnects can now tell whether a replay was complete and whether its last prompt went through.replay_completemarks the end of the history replay a Client requests withsession/resume. Everything the Agent sends for the session between the request and the marker is history, and live updates wait until after it. If the resume fails before the marker arrives, the Client knows the replay was truncated.idempotencyKeyonsession/promptidentifies retries of one submission. A Client that never got a response sends the prompt again with the same key. While the Agent retains the key, it returns the originalmessageIdand doesn’t insert a second message.- Retry classes say, for every method, whether it is safe to send again and what a second copy does.
A stricter wire format
v2 is also stricter about what goes on the wire, so that two implementations written from the spec agree.- JSON-RPC batches are gone, as in MCP. A request ID is a string or an integer, never
null. - Three error rules that v1 only recommended are now required:
-32601for a method the receiver doesn’t implement or didn’t advertise,-32002for a session that doesn’t exist or isn’t active on the connection, and-32600for a request sent before initialization completes. A new-32022rejectsinitializewhen the Agent supports no version at or below the one requested, and lists the versions it does support. - The top-level
_metaof an upsert is a patch, like every other field. Omitted leaves the stored metadata unchanged,nullclears it, and an object updates it key by key.statusoncompaction_updatebecame a patch field too, so every upsert keyed by an ID requires only that ID.
Features in both versions
New features kept shipping through the RFD process while v2 was in Draft. Since July we have stabilized eight of them in both v1 and v2: elicitation, terminal authentication, tool call names, session notices, session compaction, client-provided system prompts, plan operations, and subagent sessions. Where a v1 Client opts in to one of these with a capability, v2 often needs none. Notices, compaction updates, plan operations, and subagents are all part of the v2 baseline.If you implemented the Draft
If you built against the July Draft, these are the changes most likely to break you:- The
session/promptresponse has a requiredmessageId. - An Agent no longer rejects a prompt because work is active. It inserts the prompt or holds it.
- The
session/newandsession/resumeresponses carry the session’savailableCommandsnext to itsconfigOptions. - A
session/resumewith replay ends withreplay_complete. - Every Client handles
subagent_updateand child sessions. _metaon an upsert is a patch, batches are gone, and request IDs can’t benull.- Each command has a
typediscriminator, and elicitation string properties no longer havepattern.
Preview status
v2 is a Preview. We think v2 is ready to build on, and we will aim to avoid large breaking changes from here, but it is not frozen. If your implementation finds a problem, I would rather fix it now than carry it into the stable release. Agents can serve v2 to any Client that asks for it. Version negotiation still decides what each connection speaks, so a v1 Client sees no difference. Clients choose when to ask, and we suggest keeping that choice opt-in for your users while Preview feedback comes in. Adding v2 support still should not mean dropping v1. v1-only Agents and Clients will be common for some time. The Rust and TypeScript SDKs now have protocol routers that negotiate the version and send each connection to your v1 or v2 implementation, and the migration guide shows how to support both side by side. Not everything you may be waiting for is in this Preview. Remote transports aren’t, and neither is steering and queueing of prompts. We designed v2 with both in mind, but we didn’t tie them to this release. They add methods and capabilities without changing existing messages, so they can land later without another breaking change.Where to start
- Read the v2 protocol docs and the migration guide, which has before and after examples and checklists for Agents, Clients, and SDKs.
- Pick an SDK. Rust has v2 behind the
unstable_protocol_v2feature, and TypeScript has it under@agentclientprotocol/sdk/experimental/v2. Both are updated with each schema release. Kotlin and Python have v2 APIs too, and we are working on bringing them up to the latest schema. - Read a working implementation. The Claude and Codex adapters both serve v2 next to v1.
- Test your Agent with the TCK, which has an opt-in v2 suite.
- SDK authors can generate from the v2 JSON schemas, published in the repository releases tagged
schema-v2.0.0-beta.N. - The v2 RFD collection records the decisions behind the larger changes.