From 4cfe9c52a1b1c8bba1a19559d7d14c1183a3ca81 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 8 Jul 2026 17:36:07 +0200 Subject: [PATCH 1/2] docs: announce ACP v2 draft --- docs/announcements/acp-v2-draft.mdx | 79 +++++++++++++++++++++++++++++ docs/docs.json | 3 +- docs/updates.mdx | 9 ++++ 3 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/announcements/acp-v2-draft.mdx diff --git a/docs/announcements/acp-v2-draft.mdx b/docs/announcements/acp-v2-draft.mdx new file mode 100644 index 000000000..efb3fb5df --- /dev/null +++ b/docs/announcements/acp-v2-draft.mdx @@ -0,0 +1,79 @@ +--- +title: ACP v2 is available in Draft +sidebarTitle: ACP v2 Draft +description: The ACP v2 protocol documentation and schema are published in draft form for review and testing. +--- + +import { Author } from "/snippets/author.jsx"; + +**Published:** July 8, 2026 + +Today is a day the ACP team has been working towards for months, and we are excited to share the **first Draft of version 2 of the Agent Client Protocol**. + +Since releasing v1, we have been able to leverage the future-compatible nature of the protocol and our [RFD process](/rfds) to ship **15+ RFDs** and their related features. A huge thank you to everyone who made this possible, and also proof that we can evolve the protocol rapidly without needing to have huge migrations every few months. With agents, things are evolving rapidly, and we need to be able to evolve with it. + +However, it has also become clear that **some** breaking changes would not only be nice, but unlock entire new use cases and features that are hard to express in v1 of the protocol. v2 is all about making it possible to express more session states, consolidating on patterns we have found useful as we've evolved the protocol, and overall making everything more consistent. + +There are a lot of features we still want to add (see our [RFDs](/rfds)), and if you don't see it here, it is likely because we can still add it later via the RFD process, and possibly even in v1. The spirit of v2 was to make the necessary changes to remove any unnecessary constraints on how we can express the concept of an agentic session. + +I am always driven by our core design goal that as much freedom as possible should be given to both Agents and Clients in terms of how they are able to implement features on top of the protocol, and the goal of the protocol is to agree on the semantically meaningful bits we need in order to do so. Ideally, in v2, we are able to get out of your way and more flexibly represent your creative ideas for how we can all leverage agents in new ways. + +## The Big Themes of v2 + +### Moving beyond the turn + +Agents are pushing the boundaries of what is possible, and are pushing more and more work into the background. ACP v1 kind of assumed most of this work would happen after a user-initiated message. While the ACP v1 spec didn't _prohibit_ session/updates from coming outside of the turn, it was a common point of confusion. + +Either way, if we want to allow for expressing queueing, steering, or receiving updates in general from work that isn't necessarily initiated by the user, we need to make it clearer that the prompt doesn't own the lifecycle. Now `session/updates` can proceed freely at any point in the session, and a prompt response is the indication that the message was acknowledged by the agent. The agent will replay the user message where it inserted it, which also makes it easier for both replay and the potential for multiple clients observing the same session, both of which were awkward with the request/response assumptions before. + +You can read more about this in the [new prompt lifecycle RFD](/rfds/v2/prompt). + +### Updates are upserts + +Messages, tool calls, and plans are patched by stable IDs with uniform semantics: omitted fields stay unchanged, `null` clears, values replace, and chunks append. Message IDs are now required, and whole-message updates join the existing streaming chunks. + +In doing so we've also allowed for streaming tool call content, and the ability to send non-streaming messages (or replacements in the case of redactions or other flows). + +### Diff Overhaul + +The `oldText`/`newText` diff is replaced by structured file changes (add, delete, modify, move, copy, plus binary and non-text cases) with optional renderable `git_patch` text. + +### More flexible permission requests + +Permission prompts carry their own required `title` and optional `description`, with an extensible `subject` union instead of a hard-wired tool call. This also opens to the door to supporting permission requests for things other than tool calls. + +### Forward compatibility by default + +One of the big goals in v1 was to also make ACP extensible, which has been hugely successful, and v2 now makes it possible to extend at just about every layer you can think of to allow for more experimentation or extension points when building tooling on top. + +Enum-like values and tagged unions across the schema accept unknown variants, with a `_` prefix reserved for implementation-specific extensions. This builds on the successful pattern we added for session config options and embeds it right in the schema. This makes sure new features don't cause older client and agents to choke on unknown nested data, and provides patterns for extending even more parts of the protocol where needed. + +## Draft status + +**v2 is a Draft**. I personally went through every single line of the schema at least once, if not more, and I think it is in a solid state to start testing. **However, various pieces can, and will, change before stabilization.** That is the point of the draft stage: to receive feedback before we make this stable. + +As you start implementing it, gate it behind the version negotiation AND feature flags. Don't ship it by default in production until we are closer to stabilization. If we're lucky, not much will need to change. But we also want to avoid causing pain for users while we all navigate implementing the necessary changes. + +Adding v2 support should not mean dropping v1. v1-only peers will remain common for some time, so implementers should support both versions side by side. + +If you maintain an Agent, Client, or SDK, the [migration guide](/protocol/v2/migration) walks through every change with before/after wire examples and per-role checklists. + +## Where to start + +- Read the [v2 protocol docs](/protocol/v2/overview) and the [migration guide](/protocol/v2/migration). +- SDK authors can generate against the v2 JSON schemas, published in the repository alongside v1. +- The [v2 RFD collection](/rfds/v2/overview) records the key decisions behind the larger changes. + +## We want your feedback + +This is exactly the moment where feedback has the most leverage. If something in v2 doesn't work for your implementation, tell us before it stabilizes: open an issue or discussion on [GitHub](https://github.com/agentclientprotocol/agent-client-protocol), or engage with the individual RFDs through the [RFD process](/rfds/about). + +I know there are a lot of changes, some big, many small. But I firmly believe the changes provide a much better foundation for us to build on. It incorporates all of the learnings we've gained in the past year, consolidates on some common patterns, and allows for much more flexibility as we all build our agentic future together. + +Overall, I am astounded by how many of you have been using ACP to build your agents, clients, and just about anything else you can imagine. It is a big tent, and every new use case or app that adopts it brings me joy. Your creativity keeps us going, and I am excited to see what you all can do with v2. + + diff --git a/docs/docs.json b/docs/docs.json index 40584c3fa..a89bb06bf 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -116,7 +116,7 @@ { "group": "v2", "tag": "Draft", - "hidden": true, + "expanded": true, "pages": [ "protocol/v2/overview", "protocol/v2/migration", @@ -266,6 +266,7 @@ { "group": "Announcements", "pages": [ + "announcements/acp-v2-draft", "announcements/logout-method-stabilized", "announcements/session-close-stabilized", "announcements/session-resume-stabilized", diff --git a/docs/updates.mdx b/docs/updates.mdx index b4d7f1471..c1c81e274 100644 --- a/docs/updates.mdx +++ b/docs/updates.mdx @@ -6,6 +6,15 @@ rss: true This page is for larger ACP announcements and project updates. For lifecycle changes to Requests for Dialog, see [RFD Updates](/rfds/updates). + +## ACP v2 is Available in Draft + +The ACP v2 protocol documentation and schema are now published in Draft form. + +[Read the full announcement](/announcements/acp-v2-draft). + + + ## Logout Method is Stabilized From 00a2b9b8531cb98b947002b6a32b1f1eb7c94d8f Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Tue, 14 Jul 2026 15:22:32 +0200 Subject: [PATCH 2/2] Rework blog post --- docs/announcements/acp-v2-draft.mdx | 52 ++++++++++++++++------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/docs/announcements/acp-v2-draft.mdx b/docs/announcements/acp-v2-draft.mdx index efb3fb5df..a25938159 100644 --- a/docs/announcements/acp-v2-draft.mdx +++ b/docs/announcements/acp-v2-draft.mdx @@ -6,71 +6,77 @@ description: The ACP v2 protocol documentation and schema are published in draft import { Author } from "/snippets/author.jsx"; -**Published:** July 8, 2026 +**Published:** July 15, 2026 Today is a day the ACP team has been working towards for months, and we are excited to share the **first Draft of version 2 of the Agent Client Protocol**. -Since releasing v1, we have been able to leverage the future-compatible nature of the protocol and our [RFD process](/rfds) to ship **15+ RFDs** and their related features. A huge thank you to everyone who made this possible, and also proof that we can evolve the protocol rapidly without needing to have huge migrations every few months. With agents, things are evolving rapidly, and we need to be able to evolve with it. +Since releasing v1, we have been able to leverage the future-compatible nature of the protocol and our [RFD process](/rfds) to ship **15+ RFDs** and their related features. A huge thank you to everyone who made this possible, and also proof that we can evolve the protocol rapidly without needing to a huge migration every few months. -However, it has also become clear that **some** breaking changes would not only be nice, but unlock entire new use cases and features that are hard to express in v1 of the protocol. v2 is all about making it possible to express more session states, consolidating on patterns we have found useful as we've evolved the protocol, and overall making everything more consistent. +However, it also became clear while working with v1 that **some** breaking changes would unlock new use cases and features that are hard to express in the protocol as it is today. v2 is all about making it possible to express more session states, consolidating on patterns we have found useful, and overall making everything more consistent. -There are a lot of features we still want to add (see our [RFDs](/rfds)), and if you don't see it here, it is likely because we can still add it later via the RFD process, and possibly even in v1. The spirit of v2 was to make the necessary changes to remove any unnecessary constraints on how we can express the concept of an agentic session. +The goal was to avoid cramming as much as possible into a v2 and it never landing. So we are relying on our [RFD process](/rfds), that already worked so well in v1, to guide new features landing in both v1 and v2 as we move forward, and keep this release tightly focused on changing several core behaviors. If there is a new feature you really want, but don't see here, that doesn't mean it won't be added. We just wanted to decouple the release cadence for features that would remain optional or additive anyway. -I am always driven by our core design goal that as much freedom as possible should be given to both Agents and Clients in terms of how they are able to implement features on top of the protocol, and the goal of the protocol is to agree on the semantically meaningful bits we need in order to do so. Ideally, in v2, we are able to get out of your way and more flexibly represent your creative ideas for how we can all leverage agents in new ways. +Our core design goal remains to provide as much freedom as possible to both agents and clients in their implementations, and agree on the semantically meaningful parts we need in order to do so. v2 enables allows even more flexibility in how an agent is able to work during a session, and also paves the way for new client patterns as well. ## The Big Themes of v2 ### Moving beyond the turn -Agents are pushing the boundaries of what is possible, and are pushing more and more work into the background. ACP v1 kind of assumed most of this work would happen after a user-initiated message. While the ACP v1 spec didn't _prohibit_ session/updates from coming outside of the turn, it was a common point of confusion. +When we launched ACP v1, most agents happily emitted events only after a user-initiated message and usually stopped once they finished generating. But these days, agents are able to work longer and even orchestrate more and more work in the background. While the ACP v1 spec didn't _prohibit_ `session/updates` from coming outside of the turn, it was a common point of confusion for implementers, who usually wanted to guarantee interaction patterns around the idea of a user-initiated turn, but it is clear that enforcing this actually prevents useful behavior. An agent could be ready to receive new input while background events are happening, but it still wants to provide real-time updates for those as well. If we stick with a turn-focused orientation for prompts, neither sad is happy. -Either way, if we want to allow for expressing queueing, steering, or receiving updates in general from work that isn't necessarily initiated by the user, we need to make it clearer that the prompt doesn't own the lifecycle. Now `session/updates` can proceed freely at any point in the session, and a prompt response is the indication that the message was acknowledged by the agent. The agent will replay the user message where it inserted it, which also makes it easier for both replay and the potential for multiple clients observing the same session, both of which were awkward with the request/response assumptions before. +If we want to allow for queueing, steering, or receiving updates from work that isn't necessarily initiated by the user, we need to make it clearer that the prompt request/response doesn't own the entire lifecycle of work being done. Now `session/updates` can proceed freely at any point in the session, and a prompt response is the indication that the message was acknowledged by the agent, not the end of the turn. The agent will replay the user message where it inserted it, which also makes it easier for both replay and the potential for multiple clients observing the same session. The agent can indicate when it is "idle", or ready to receive new inputs, allowing the client to indicate readiness, and agents can continue to update the session state in the meantime. -You can read more about this in the [new prompt lifecycle RFD](/rfds/v2/prompt). +This is the biggest change in behavior in v2, but I think allows clients and agents to both represent new interactions and session states. You can read more about this in the [new prompt lifecycle RFD](/rfds/v2/prompt). -### Updates are upserts +### Updating Messages and Streaming Tool Calls -Messages, tool calls, and plans are patched by stable IDs with uniform semantics: omitted fields stay unchanged, `null` clears, values replace, and chunks append. Message IDs are now required, and whole-message updates join the existing streaming chunks. +Messages, tool calls, terminal output, and plans are patched by stable IDs with uniform semantics: omitted fields stay unchanged, `null` clears, values replace, and chunks append. Message IDs are required as well so that messages can not only stream, but also update and replace in case of redaction or other needs. -In doing so we've also allowed for streaming tool call content, and the ability to send non-streaming messages (or replacements in the case of redactions or other flows). +This was a pattern that was only available for tool calls before, but now is uniformly used across all session items to make things more consistent and flexible. + +We also applied the message streaming pattern to tool call content, so that tool calls can be streamed in without buffering and resending the entire content over and over. ### Diff Overhaul -The `oldText`/`newText` diff is replaced by structured file changes (add, delete, modify, move, copy, plus binary and non-text cases) with optional renderable `git_patch` text. +The `oldText`/`newText` diff is replaced by structured file changes. You can now express add, delete, modify, move, copy, plus binary and non-text cases. Some of these could be inferred in the old structure, but not all, so we've hopefully made it possible to report all changes the agent makes on the filesystem. + +The agent can also provide an optional `git_patch` for rendering the changes. This can be shown as is, but is also structured enough for clients to do nice diff rendering for text changes as well. ### More flexible permission requests -Permission prompts carry their own required `title` and optional `description`, with an extensible `subject` union instead of a hard-wired tool call. This also opens to the door to supporting permission requests for things other than tool calls. +Permission prompts carry their own required `title` and optional `description`, with an extensible `subject` instead of a hard-wired tool call. This also allows us to provide special permission requests for terminal commands or other objects in the future. And decoupling the `title` and `description` from the tool call's title and content makes it possible to provide more context to the user making the decision without accidentally overriding the tool call itself. ### Forward compatibility by default -One of the big goals in v1 was to also make ACP extensible, which has been hugely successful, and v2 now makes it possible to extend at just about every layer you can think of to allow for more experimentation or extension points when building tooling on top. +One of the big goals in v1 was to make ACP extensible, which has been hugely successful. So many of you have built amazing features using these mechanisms, several of which have been upstreamed to the protocol itself. + +v2 now makes it possible to extend at just about every layer you can think of to allow for more experimentation or extension points when building tooling on top. -Enum-like values and tagged unions across the schema accept unknown variants, with a `_` prefix reserved for implementation-specific extensions. This builds on the successful pattern we added for session config options and embeds it right in the schema. This makes sure new features don't cause older client and agents to choke on unknown nested data, and provides patterns for extending even more parts of the protocol where needed. +Enum-like values across the schema accept unknown variants with a `_` prefix for implementation-specific extensions. This builds on the successful pattern we added for session config options and embeds it right in the schema. This makes sure new features don't cause older client and agents to choke on unknown nested data, and provides patterns for extending even more parts of the protocol where needed. ## Draft status -**v2 is a Draft**. I personally went through every single line of the schema at least once, if not more, and I think it is in a solid state to start testing. **However, various pieces can, and will, change before stabilization.** That is the point of the draft stage: to receive feedback before we make this stable. +**v2 is a Draft**. I personally went through every single line of the schema at least once, if not more, and I think it is in a solid state to start testing. **However, various pieces can, and will, change before stabilization.** That is the point of the draft stage: to receive feedback before we stabilize it. -As you start implementing it, gate it behind the version negotiation AND feature flags. Don't ship it by default in production until we are closer to stabilization. If we're lucky, not much will need to change. But we also want to avoid causing pain for users while we all navigate implementing the necessary changes. +As you start implementing it, gate your implementation behind the version negotiation **AND** feature flags. Don't ship it by default in production until we are closer to stabilization. If we're lucky, not much will need to change between now and then. But we also want to avoid causing pain for users while we all navigate the necessary changes. -Adding v2 support should not mean dropping v1. v1-only peers will remain common for some time, so implementers should support both versions side by side. +Adding v2 support should not mean dropping v1. v1-only peers will remain common for some time, so implementers should support both versions side by side. We are working on making this easier to express in the various SDKs. -If you maintain an Agent, Client, or SDK, the [migration guide](/protocol/v2/migration) walks through every change with before/after wire examples and per-role checklists. +A majority of the types haven't changed between versions, but if you maintain an Agent, Client, or SDK, the [migration guide](/protocol/v2/migration) walks through the key changes you need to know with before/after examples. ## Where to start - Read the [v2 protocol docs](/protocol/v2/overview) and the [migration guide](/protocol/v2/migration). -- SDK authors can generate against the v2 JSON schemas, published in the repository alongside v1. +- SDK authors can generate against the v2 JSON schemas, published in the repository releases as `v2.0.0-alphaX` alongside v1. - The [v2 RFD collection](/rfds/v2/overview) records the key decisions behind the larger changes. ## We want your feedback -This is exactly the moment where feedback has the most leverage. If something in v2 doesn't work for your implementation, tell us before it stabilizes: open an issue or discussion on [GitHub](https://github.com/agentclientprotocol/agent-client-protocol), or engage with the individual RFDs through the [RFD process](/rfds/about). +This is exactly the moment where feedback has the most leverage. If something in v2 doesn't work for your implementation, tell us before it stabilizes: open an issue or discussion on [GitHub](https://github.com/agentclientprotocol/agent-client-protocol), or engage with the individual RFDs through the [RFD process](/rfds). -I know there are a lot of changes, some big, many small. But I firmly believe the changes provide a much better foundation for us to build on. It incorporates all of the learnings we've gained in the past year, consolidates on some common patterns, and allows for much more flexibility as we all build our agentic future together. +I firmly believe v2 provides a much better foundation for us to build on. It incorporates all of the learnings we've gained in the past year, consolidates on some common patterns, and allows for much more flexibility as we all build our agentic future together. -Overall, I am astounded by how many of you have been using ACP to build your agents, clients, and just about anything else you can imagine. It is a big tent, and every new use case or app that adopts it brings me joy. Your creativity keeps us going, and I am excited to see what you all can do with v2. +Overall, I am astounded by how many of you have been using ACP to build your agents, clients, and just about everything else you can imagine. It is a big tent, and every new use case or app that adopts it brings me joy. Your creativity keeps us going, and I am excited to see what you all can do with v2.