# Table of Contents - [ACP Registry is stabilized - Agent Client Protocol](#acp-registry-is-stabilized-agent-client-protocol) - [Implementation information for agents and clients - Agent Client Protocol](#implementation-information-for-agents-and-clients-agent-client-protocol) - [Sergey Ignatov joins ACP as Lead Maintainer - Agent Client Protocol](#sergey-ignatov-joins-acp-as-lead-maintainer-agent-client-protocol) - [Brand - Agent Client Protocol](#brand-agent-client-protocol) - [Session Config Options are stabilized - Agent Client Protocol](#session-config-options-are-stabilized-agent-client-protocol) - [Transports Working Group - Agent Client Protocol](#transports-working-group-agent-client-protocol) - [Session Info Update is stabilized - Agent Client Protocol](#session-info-update-is-stabilized-agent-client-protocol) - [Session List is stabilized - Agent Client Protocol](#session-list-is-stabilized-agent-client-protocol) - [Contributing - Agent Client Protocol](#contributing-agent-client-protocol) - [Contributor Communication - Agent Client Protocol](#contributor-communication-agent-client-protocol) - [Working and Interest Groups - Agent Client Protocol](#working-and-interest-groups-agent-client-protocol) - [Code of Conduct - Agent Client Protocol](#code-of-conduct-agent-client-protocol) - [Governance - Agent Client Protocol](#governance-agent-client-protocol) - [Publications - Agent Client Protocol](#publications-agent-client-protocol) - [Agents - Agent Client Protocol](#agents-agent-client-protocol) - [Architecture - Agent Client Protocol](#architecture-agent-client-protocol) - [Java - Agent Client Protocol](#java-agent-client-protocol) - [Kotlin - Agent Client Protocol](#kotlin-agent-client-protocol) - [Clients - Agent Client Protocol](#clients-agent-client-protocol) - [Updates - Agent Client Protocol](#updates-agent-client-protocol) - [TypeScript - Agent Client Protocol](#typescript-agent-client-protocol) - [Rust - Agent Client Protocol](#rust-agent-client-protocol) - [Community - Agent Client Protocol](#community-agent-client-protocol) - [Python - Agent Client Protocol](#python-agent-client-protocol) - [Introduction - Agent Client Protocol](#introduction-agent-client-protocol) - [Agent Plan - Agent Client Protocol](#agent-plan-agent-client-protocol) - [File System - Agent Client Protocol](#file-system-agent-client-protocol) - [Overview - Agent Client Protocol](#overview-agent-client-protocol) - [Extensibility - Agent Client Protocol](#extensibility-agent-client-protocol) - [Content - Agent Client Protocol](#content-agent-client-protocol) - [Slash Commands - Agent Client Protocol](#slash-commands-agent-client-protocol) - [ACP Registry - Agent Client Protocol](#acp-registry-agent-client-protocol) - [Initialization - Agent Client Protocol](#initialization-agent-client-protocol) - [Session List - Agent Client Protocol](#session-list-agent-client-protocol) - [Session Modes - Agent Client Protocol](#session-modes-agent-client-protocol) - [Transports - Agent Client Protocol](#transports-agent-client-protocol) - [Terminals - Agent Client Protocol](#terminals-agent-client-protocol) - [Prompt Turn - Agent Client Protocol](#prompt-turn-agent-client-protocol) - [Session Config Options - Agent Client Protocol](#session-config-options-agent-client-protocol) - [Introduce RFD Process - Agent Client Protocol](#introduce-rfd-process-agent-client-protocol) - [Represent deleted files in diff - Agent Client Protocol](#represent-deleted-files-in-diff-agent-client-protocol) - [Tool Calls - Agent Client Protocol](#tool-calls-agent-client-protocol) - [Session Setup - Agent Client Protocol](#session-setup-agent-client-protocol) - [Meta Field Propagation Conventions - Agent Client Protocol](#meta-field-propagation-conventions-agent-client-protocol) - [Requests for Dialog (RFDs) - Agent Client Protocol](#requests-for-dialog-rfds-agent-client-protocol) - [Authentication Methods - Agent Client Protocol](#authentication-methods-agent-client-protocol) - [Agent Telemetry Export - Agent Client Protocol](#agent-telemetry-export-agent-client-protocol) - [Logout Method - Agent Client Protocol](#logout-method-agent-client-protocol) - [Boolean Config Option Type - Agent Client Protocol](#boolean-config-option-type-agent-client-protocol) - [ACP Agent Registry - Agent Client Protocol](#acp-agent-registry-agent-client-protocol) - [Closing active sessions - Agent Client Protocol](#closing-active-sessions-agent-client-protocol) - [Session Delete - Agent Client Protocol](#session-delete-agent-client-protocol) - [Resuming of existing sessions - Agent Client Protocol](#resuming-of-existing-sessions-agent-client-protocol) - [Message ID - Agent Client Protocol](#message-id-agent-client-protocol) - [Forking of existing sessions - Agent Client Protocol](#forking-of-existing-sessions-agent-client-protocol) - [Request Cancellation Mechanism - Agent Client Protocol](#request-cancellation-mechanism-agent-client-protocol) - [Agent Extensions via ACP Proxies - Agent Client Protocol](#agent-extensions-via-acp-proxies-agent-client-protocol) - [Additional Workspace Roots for Session Lifecycle Requests - Agent Client Protocol](#additional-workspace-roots-for-session-lifecycle-requests-agent-client-protocol) - [Configurable LLM Providers - Agent Client Protocol](#configurable-llm-providers-agent-client-protocol) - [MCP-over-ACP: MCP Transport via ACP Channels - Agent Client Protocol](#mcp-over-acp-mcp-transport-via-acp-channels-agent-client-protocol) - [Session Usage and Context Status - Agent Client Protocol](#session-usage-and-context-status-agent-client-protocol) - [Session List - Agent Client Protocol](#session-list-agent-client-protocol) - [RFD Updates - Agent Client Protocol](#rfd-updates-agent-client-protocol) - [Streamable HTTP & WebSocket Transport - Agent Client Protocol](#streamable-http-websocket-transport-agent-client-protocol) - [Session Info Update - Agent Client Protocol](#session-info-update-agent-client-protocol) - [Session Config Options - Agent Client Protocol](#session-config-options-agent-client-protocol) - [Elicitation: Structured User Input - Agent Client Protocol](#elicitation-structured-user-input-agent-client-protocol) - [Next Edit Suggestions - Agent Client Protocol](#next-edit-suggestions-agent-client-protocol) - [Rust SDK based on SACP - Agent Client Protocol](#rust-sdk-based-on-sacp-agent-client-protocol) - [Schema - Agent Client Protocol](#schema-agent-client-protocol) --- # ACP Registry is stabilized - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/announcements/acp-agent-registry-stabilized#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Announcements ACP Registry is stabilized [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Published:** March 9, 2026 The ACP Registry RFD has moved to Completed and the initial version of the registry is stabilized. The registry gives ACP clients a standard way to discover, install, and configure compatible agents. It introduces a curated catalog and a shared manifest format so editors and other clients do not need to invent their own integration metadata. If you want to explore the shipped experience, start with [ACP Registry](https://agentclientprotocol.com/get-started/registry) . For the design history and rationale, see the [ACP Agent Registry RFD](https://agentclientprotocol.com/rfds/acp-agent-registry) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/announcements/transports-working-group) [Session Info Update stabilizedAnnouncement that the session\_info\_update notification is now part of the stable ACP protocol.\ \ Next](https://agentclientprotocol.com/announcements/session-info-update-stabilized) ⌘I --- # Implementation information for agents and clients - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/announcements/implementation-information#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Announcements Implementation information for agents and clients [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Published:** October 24, 2025 ACP now allows agents and clients to provide information about themselves to the other party during initialization. The [InitializeRequest](https://agentclientprotocol.com/protocol/schema#initializerequest) message now includes an optional clientInfo field, and the [InitializeResponse](https://agentclientprotocol.com/protocol/schema#initializeresponse) message includes an optional agentInfo field. This information can be used by clients to show users which agent is running and what version, by both sides to track usage metrics for which agents and clients are most popular among their users, and to help track down issues tied to particular implementation versions. This follows the existing pattern laid out in the [Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization) . This is being introduced as an optional field for now for backwards compatibility. It is possible it will be made required in a future version of the protocol, like MCP, so that both sides can count on this information being available. For the user-facing protocol guide, see [Implementation Information](https://agentclientprotocol.com/protocol/initialization#implementation-information) . Was this page helpful? YesNo [Previous\ \ Config options stabilizedAnnouncement that session-level configuration selectors are now part of the stable ACP protocol.](https://agentclientprotocol.com/announcements/session-config-options-stabilized) ⌘I --- # Sergey Ignatov joins ACP as Lead Maintainer - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/announcements/sergey-ignatov-lead-maintainer#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Announcements Sergey Ignatov joins ACP as Lead Maintainer [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Published:** February 18, 2026 It is with great pleasure that I announce that Sergey Ignatov, from JetBrains, will be joining me as a Lead Maintainer for ACP. Agus Zubiaga will remain a key part of the leadership group as a Core Maintainer. This is in recognition of Sergey’s many contributions to the protocol. We would not be where we are today without his efforts. In the past few months, Zed and JetBrains have been able to collaborate closely on the protocol, and it is time to reflect that fact more formally in our governance structure. I have enjoyed the chance to work with Sergey and the entire JetBrains team. There is still much work to be done, but with all of the agent and client teams working together, I am confident we can continue to make the ACP vision a reality: allowing you to collaborate with the agent or agents you love wherever you are already working. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/announcements/session-list-stabilized) [Config options stabilizedAnnouncement that session-level configuration selectors are now part of the stable ACP protocol.\ \ Next](https://agentclientprotocol.com/announcements/session-config-options-stabilized) ⌘I --- # Brand - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/brand#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Brand [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Following these guidelines helps maintain brand integrity while supporting ACP’s mission to standardize communication between code editors and coding agents. [Download all of the assets here](https://cdn.agentclientprotocol.com/acp-brand.zip) [​](https://agentclientprotocol.com/brand#logo) Logo ------------------------------------------------------- The ACP logo can be used with the “ACP” logomark with or without a gradient. We provide a vertical and horizontal variant for display flexibility. ![Agentic Client Protocol Logo](https://mintcdn.com/zed-685ed6d6/0gwpXYa47bQsPCSW/assets/acp-docs-logo.webp?w=2500&fit=max&auto=format&n=0gwpXYa47bQsPCSW&q=85&s=adc02618a11ae71fb7e75e8c7c8efab9) [​](https://agentclientprotocol.com/brand#logomark) Logomark --------------------------------------------------------------- The logomark has a variation that includes a slight gradient on the bottom right part of it. We don’t enforce the use of one version over the other, meaning you can choose to use either of them as you wish, as long as you respect using it in pure white or pure black. ![Agentic Client Protocol Logomark](https://mintcdn.com/zed-685ed6d6/0gwpXYa47bQsPCSW/assets/acp-docs-logo-mark.webp?w=2500&fit=max&auto=format&n=0gwpXYa47bQsPCSW&q=85&s=d39cbbe01181dc721f7c849759862e0c) Was this page helpful? YesNo ⌘I On this page * [Logo](https://agentclientprotocol.com/brand#logo) * [Logomark](https://agentclientprotocol.com/brand#logomark) --- # Session Config Options are stabilized - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/announcements/session-config-options-stabilized#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Announcements Session Config Options are stabilized [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Published:** February 4, 2026 The Session Config Options RFD has moved to Completed and is stabilized. Session Config Options give agents a flexible way to expose session-level configuration such as models, modes, reasoning levels, and other selectors. Instead of hard-coding a small set of protocol-level controls, clients can render the options an agent provides and keep them in sync as they change. The stable protocol documentation is available in [Session Config Options](https://agentclientprotocol.com/protocol/session-config-options) , and the design history remains in the [Session Config Options RFD](https://agentclientprotocol.com/rfds/session-config-options) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/announcements/sergey-ignatov-lead-maintainer) [Implementation informationProtocol update introducing optional implementation metadata during initialization.\ \ Next](https://agentclientprotocol.com/announcements/implementation-information) ⌘I --- # Transports Working Group - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/announcements/transports-working-group#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Announcements Transports Working Group [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Published:** April 22, 2026 I’m excited to announce that we have a new Transports working group! Remote Agent support is a key focus of ACP, and in order to make this more of a reality, we need to standardize all of the approaches to transports people have been trying. We have started work on a Draft RFD for how this could work both via WebSockets and HTTP. Anna Zhdan will be representing from the Core Maintainers along with Alex Hancock from the Goose team who has been spearheading the RFD effort. A big thanks to both of you for starting this and I look forward to seeing what is next! Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/updates) [ACP Registry stabilizedAnnouncement that the ACP Registry RFD has been completed and the registry is stabilized.\ \ Next](https://agentclientprotocol.com/announcements/acp-agent-registry-stabilized) ⌘I --- # Session Info Update is stabilized - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/announcements/session-info-update-stabilized#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Announcements Session Info Update is stabilized [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Published:** March 9, 2026 The Session Info Update RFD has moved to Completed and the session\_info\_update notification is stabilized. This lets agents push session metadata updates to clients in real time, including generated titles and related metadata, so session lists can stay current without polling. The stable protocol behavior is documented in [Session List](https://agentclientprotocol.com/protocol/session-list#updating-session-metadata) , and the design history remains in the [Session Info Update RFD](https://agentclientprotocol.com/rfds/session-info-update) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/announcements/acp-agent-registry-stabilized) [Session List stabilizedAnnouncement that the session/list method is now part of the stable ACP protocol.\ \ Next](https://agentclientprotocol.com/announcements/session-list-stabilized) ⌘I --- # Session List is stabilized - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/announcements/session-list-stabilized#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Announcements Session List is stabilized [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Published:** March 9, 2026 The Session List RFD has moved to Completed and the session/list method is stabilized. This gives clients a standard way to discover sessions known to an agent, making features like session history, session switching, and cleanup much easier to implement consistently across ACP clients. For the shipped protocol, see [Session List](https://agentclientprotocol.com/protocol/session-list) . For the design history, see the [Session List RFD](https://agentclientprotocol.com/rfds/session-list) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/announcements/session-info-update-stabilized) [Lead maintainer updateGovernance announcement about Sergey Ignatov joining ACP as a Lead Maintainer.\ \ Next](https://agentclientprotocol.com/announcements/sergey-ignatov-lead-maintainer) ⌘I --- # Contributing - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/community/contributing#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Contributing [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) We welcome contributions from the community! All contributors must adhere to our [Code of Conduct](https://agentclientprotocol.com/community/code-of-conduct) . For questions and discussions, please use GitHub Discussions. Was this page helpful? YesNo [Previous\ \ Working and Interest GroupsLearn about the two forms of collaborative groups within the Agent Client Protocol's governance structure - Working Groups and Interest Groups.](https://agentclientprotocol.com/community/working-interest-groups) ⌘I --- # Contributor Communication - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/community/communication#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Contributor Communication [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) This document explains how to communicate and collaborate within the Agent Client Protocol (ACP) project. [​](https://agentclientprotocol.com/community/communication#communication-channels) Communication Channels ------------------------------------------------------------------------------------------------------------- In short: * **[Zulip](https://agentclientprotocol.zulipchat.com/) **: For real-time or ad-hoc discussions. * **[RFDs](https://agentclientprotocol.com/rfds/about) **: For proposed changes to the specification. * **[GitHub Discussions](https://github.com/orgs/agentclientprotocol/discussions) **: For structured, longer-form discussions. * **[GitHub Issues](https://github.com/agentclientprotocol/agent-client-protocol/issues) **: For actionable tasks, bug reports, and feature requests. All communication is governed by our [Code of Conduct](https://agentclientprotocol.com/community/code-of-conduct) . We expect all participants to maintain respectful, professional, and inclusive interactions across all channels. ### [​](https://agentclientprotocol.com/community/communication#zulip) Zulip For real-time contributor discussion and collaboration. The server is designed around **ACP contributors** and is not intended to be a place for general ACP support. The Zulip server will have both public and private channels. [Join the Zulip here](https://agentclientprotocol.zulipchat.com/) . #### [​](https://agentclientprotocol.com/community/communication#public-channels-default) Public Channels (Default) * **Purpose**: Open community engagement, collaborative development, and transparent project coordination. * Primary use cases: * **Public SDK and tooling development** * **Community onboarding** and contribution guidance. * **Community feedback** and collaborative brainstorming. * Avoid: * ACP user support: participants are expected to read official documentation and start new GitHub Discussions for questions or support. * Service or product marketing: interactions on this Zulip are expected to be vendor-neutral and not used for brand-building or sales. Mentions of brands or products are discouraged outside of being used as examples or responses to conversations that start off focused on the specification. #### [​](https://agentclientprotocol.com/community/communication#private-channels-exceptions) Private channels (Exceptions) * **Purpose**: Confidential coordination and sensitive matters that cannot be discussed publicly. Access will be restricted to designated maintainers. * **Strict criteria for private use**: * **Security incidents** (CVEs, protocol vulnerabilities). * **People matters** (maintainer-related discussions, code of conduct policies). * Select channels will be configured to be **read-only**. This can be good for example for maintainer decision making. * Coordination requiring **immediate** or otherwise **focused response** with a limited audience. * **Transparency**: * **All technical and governance decisions** affecting the community **must be documented** in RFDs, GitHub Discussions and/or Issues. * **Some matters related to individual contributors** may remain private when appropriate (e.g., personal circumstances, disciplinary actions, or other sensitive individual matters). * Private channels are to be used as **temporary “incident rooms,”** not for routine development. Any significant discussion on Zulip leads to a potential decision or proposal must be moved to an RFD, GitHub Discussion, or GitHub Issue to create a persistent, searchable record. Proposals will then be promoted to full-fledged PRs with associated work items as needed. ### [​](https://agentclientprotocol.com/community/communication#rfds) RFDs Please refer to the [RFD process](https://agentclientprotocol.com/rfds/about) for how this is managed. This is the primary way to actually create changes to the protocol. Conversation about a given RFD can take place within the relevant PRs created to move the RFD forward. Or, a discussion within Zulip can be created in the `rfds` channel to discuss in real-time with other contributors. ### [​](https://agentclientprotocol.com/community/communication#github-discussions) GitHub Discussions For structured, long-form discussion and debate on project direction, features, improvements, and community topics. When to use: * Announcements and release communications * Community polls and consensus-building processes * Feature requests with context and rationale * If a particular repository does not have GitHub Discussions enabled, feel free to open a GitHub Issue instead. ### [​](https://agentclientprotocol.com/community/communication#github-issues) GitHub Issues For bug reports, feature tracking, and actionable development tasks. When to use: * Bug reports with reproducible steps * Documentation improvements with specific scope * CI/CD problems and infrastructure issues * Release tasks and milestone tracking ### [​](https://agentclientprotocol.com/community/communication#security-issues) Security Issues **Do not post security issues publicly.** Instead: 1. Contact lead and/or core maintainers, or [hi@zed.dev](mailto:hi@zed.dev) directly. 2. Follow responsible disclosure guidelines. Was this page helpful? YesNo [Code of Conduct\ \ Next](https://agentclientprotocol.com/community/code-of-conduct) ⌘I On this page * [Communication Channels](https://agentclientprotocol.com/community/communication#communication-channels) * [Zulip](https://agentclientprotocol.com/community/communication#zulip) * [Public Channels (Default)](https://agentclientprotocol.com/community/communication#public-channels-default) * [Private channels (Exceptions)](https://agentclientprotocol.com/community/communication#private-channels-exceptions) * [RFDs](https://agentclientprotocol.com/community/communication#rfds) * [GitHub Discussions](https://agentclientprotocol.com/community/communication#github-discussions) * [GitHub Issues](https://agentclientprotocol.com/community/communication#github-issues) * [Security Issues](https://agentclientprotocol.com/community/communication#security-issues) --- # Working and Interest Groups - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/community/working-interest-groups#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Working and Interest Groups [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Within the ACP contributor community we maintain two types of collaboration formats - **Interest** and **Working** groups. **Interest Groups** are responsible for identifying and articulating problems that ACP should address, primarily by facilitating open discussions within the community. In contrast, **Working Groups** focus on developing concrete solutions by collaboratively producing deliverables, such as RFDs or community-owned implementations of the specification. While input from Interest Groups can help justify the formation of a Working Group, it is not a strict requirement. Similarly, contributions from either Interest Groups or Working Groups are encouraged, but not mandatory, when submitting RFDs or other community proposals. We strongly encourage all contributors interested in working on a specific RFD to first collaborate within an Interest Group. This collaborative process helps ensure that the proposed RFD aligns with community needs and is the right direction for the protocol. Long-term projects in the ACP ecosystem, such as SDKs or other components are maintained by dedicated Working Groups. [​](https://agentclientprotocol.com/community/working-interest-groups#purpose) Purpose ----------------------------------------------------------------------------------------- These groups exist to: * **Facilitate high-signal spaces for focused discussions** - contributors who opt into notifications, expertise sharing, and regular meetings can engage with topics that are highly relevant to them, enabling meaningful contributions and opportunities to learn from others. * **Establish clear expectations and leadership roles** - guide collaborative efforts and ensure steady progress toward concrete deliverables that advance ACP evolution and adoption. [​](https://agentclientprotocol.com/community/working-interest-groups#mechanisms) Mechanisms ----------------------------------------------------------------------------------------------- [​](https://agentclientprotocol.com/community/working-interest-groups#meeting-calendar) Meeting Calendar ----------------------------------------------------------------------------------------------------------- All Interest Group and Working Group meetings are published on the public ACP community calendar (work in progress). Facilitators are responsible for posting their meeting schedules to this calendar in advance to ensure discoverability and enable broader community participation. ### [​](https://agentclientprotocol.com/community/working-interest-groups#interest-groups-igs) Interest Groups (IGs) **Goal:** Facilitate discussion and knowledge-sharing among ACP contributors who share interests in a specific ACP sub-topic or context. The primary focus is on identifying and gathering problems that may be worth addressing through RFDs or other community artifacts, while encouraging open exploration of protocol issues and opportunities. **Expectations**: * Regular conversations in the Interest Group Zulip channel * **AND/OR** a recurring live meeting regularly attended by Interest Group members * Meeting dates and times published in advance on the ACP community calendar when applicable, and tagged with their primary topic and interest group Zulip channel name * Notes publicly shared after meetings, and submitted to the [meetings repository](https://github.com/agentclientprotocol/meetings) **Lifecycle**: * Creation begins by proposing a new Interest Group to the core/lead maintainers with the template below * Majority positive vote by core maintainers over a 72h period approves creation of the group. * The creation of the group can be reversed at any time (e.g., after new information surfaces). Core and lead maintainers can veto. * Facilitator(s) and Maintainer(s) responsible for organizing IG into meeting expectations * Facilitator is an informal role responsible for shepherding or speaking for a group * Maintainer is an official representative from the ACP steering group. A maintainer is not required for every group, but can help advocate for specific changes or initiatives. * IG is retired only when Core or Lead Maintainers determine it’s no longer active and/or needed * Successful IGs do not have a time limit or expiration date - as long as they are active and maintained, they will remain available **Creation Template**: * Facilitator(s) * Maintainer(s) (optional) * IGs with potentially similar goals/discussions * How this IG differentiates itself from the related IGs * First topic you to discuss within the IG Participation in an Interest Group (IG) is not required to start a Working Group (WG) or to create a RFD. However, building consensus within IGs can be valuable when justifying the formation of a WG. Likewise, referencing support from IGs or WGs can strengthen a RFD and its chances of success. ### [​](https://agentclientprotocol.com/community/working-interest-groups#working-groups-wg) Working Groups (WG) **Goal:** Facilitate collaboration within the ACP community on a RFD, a themed series of RFDs, or an otherwise officially endorsed project. **Expectations**: * Meaningful progress towards at least one RFD or spec-related implementation **OR** hold maintenance responsibilities for a project (e.g., SDKs) * Facilitators are responsible for keeping track of progress and communicating status when appropriate * Meeting dates and times published in advance on the ACP community calendar when applicable, and tagged with their primary topic and working group Zulip channel name * Notes publicly shared after meetings, and submitted to the [meetings repository](https://github.com/agentclientprotocol/meetings) **Lifecycle**: * Creation begins by proposing a new Interest Group to the core/lead maintainers with the template below * Majority positive vote by core maintainers over a 72h period approves creation of the group. * The creation of the group can be reversed at any time (e.g., after new information surfaces). Core and lead maintainers can veto. * Facilitator(s) and Maintainer(s) responsible for organizing WG into meeting expectations * Facilitator is an informal role responsible for shepherding or speaking for a group * Maintainer is an official representative from the ACP steering group. A maintainer is not required for every group, but can help advocate for specific changes or initiatives * WG is retired when either: * Community moderators or Core and Lead Maintainers decide it is no longer active and/or needed * The WG no longer has an active Issue/PR for a month or more, or has completed all Issues/PRs it intended to pursue. **Creation Template**: * Facilitator(s) * Maintainer(s) (optional) * Explanation of interest/use cases, ideally originating from an IG discussion; however that is not a requirement * First Issue/PR/RFD that the WG will work on [​](https://agentclientprotocol.com/community/working-interest-groups#wg/ig-facilitators) WG/IG Facilitators --------------------------------------------------------------------------------------------------------------- A **Facilitator** role in a WG or IG does _not_ result in a [maintainership role](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/MAINTAINERS.md) across the ACP organization. It is an informal role into which anyone can self-nominate. A Facilitator is responsible for helping shepherd discussions and collaboration within an Interest or Working Group. Lead and Core Maintainers reserve the right to modify the list of Facilitators and Maintainers for any WG/IG at any time. [​](https://agentclientprotocol.com/community/working-interest-groups#faq) FAQ --------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/community/working-interest-groups#how-do-i-get-involved-contributing-to-acp) How do I get involved contributing to ACP? These IG and WG abstractions help provide an elegant on-ramp: 1. [Join the Zulip](https://agentclientprotocol.com/community/communication#zulip) and follow conversations in IGs relevant to you. Attend live calls. Participate. 2. Offer to facilitate calls. Contribute your use cases in RFD proposals and other work. 3. When you’re comfortable contributing to deliverables, jump in to contribute to WG work. 4. Active and valuable contributors will be nominated by WG maintainers as new maintainers. ### [​](https://agentclientprotocol.com/community/working-interest-groups#where-can-i-find-a-list-of-all-current-wgs-and-igs) Where can I find a list of all current WGs and IGs? On the [ACP Zulip Chat](https://agentclientprotocol.com/community/communication#zulip) there is a section of channels for each Working and Interest Group. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/community/governance) [ContributingHow to participate in the development of ACP\ \ Next](https://agentclientprotocol.com/community/contributing) ⌘I On this page * [Purpose](https://agentclientprotocol.com/community/working-interest-groups#purpose) * [Mechanisms](https://agentclientprotocol.com/community/working-interest-groups#mechanisms) * [Meeting Calendar](https://agentclientprotocol.com/community/working-interest-groups#meeting-calendar) * [Interest Groups (IGs)](https://agentclientprotocol.com/community/working-interest-groups#interest-groups-igs) * [Working Groups (WG)](https://agentclientprotocol.com/community/working-interest-groups#working-groups-wg) * [WG/IG Facilitators](https://agentclientprotocol.com/community/working-interest-groups#wg%2Fig-facilitators) * [FAQ](https://agentclientprotocol.com/community/working-interest-groups#faq) * [How do I get involved contributing to ACP?](https://agentclientprotocol.com/community/working-interest-groups#how-do-i-get-involved-contributing-to-acp) * [Where can I find a list of all current WGs and IGs?](https://agentclientprotocol.com/community/working-interest-groups#where-can-i-find-a-list-of-all-current-wgs-and-igs) --- # Code of Conduct - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/community/code-of-conduct#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Code of Conduct [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [​](https://agentclientprotocol.com/community/code-of-conduct#our-pledge) Our Pledge --------------------------------------------------------------------------------------- We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. [​](https://agentclientprotocol.com/community/code-of-conduct#our-standards) Our Standards --------------------------------------------------------------------------------------------- Examples of behavior that contributes to a positive environment for our community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience * Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment * Publishing others’ private information, such as a physical or email address, without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting [​](https://agentclientprotocol.com/community/code-of-conduct#enforcement-responsibilities) Enforcement Responsibilities --------------------------------------------------------------------------------------------------------------------------- Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. [​](https://agentclientprotocol.com/community/code-of-conduct#scope) Scope ----------------------------------------------------------------------------- This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. [​](https://agentclientprotocol.com/community/code-of-conduct#enforcement) Enforcement ----------------------------------------------------------------------------------------- Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [hi@zed.dev](mailto:hi@zed.dev) . All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. [​](https://agentclientprotocol.com/community/code-of-conduct#enforcement-guidelines) Enforcement Guidelines --------------------------------------------------------------------------------------------------------------- Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### [​](https://agentclientprotocol.com/community/code-of-conduct#1-correction) 1\. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### [​](https://agentclientprotocol.com/community/code-of-conduct#2-warning) 2\. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### [​](https://agentclientprotocol.com/community/code-of-conduct#3-temporary-ban) 3\. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### [​](https://agentclientprotocol.com/community/code-of-conduct#4-permanent-ban) 4\. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. [​](https://agentclientprotocol.com/community/code-of-conduct#attribution) Attribution ----------------------------------------------------------------------------------------- This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/) , version 2.0, available at [https://www.contributor-covenant.org/version/2/0/code\_of\_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html) . Community Impact Guidelines were inspired by [Mozilla’s code of conduct enforcement ladder](https://github.com/mozilla/diversity) . For answers to common questions about this code of conduct, see [the Contributor Covenant FAQ](https://www.contributor-covenant.org/faq) . For translations, see [Contributor Covenant Translations](https://www.contributor-covenant.org/translations) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/community/communication) [GovernanceHow the ACP project is governed\ \ Next](https://agentclientprotocol.com/community/governance) ⌘I On this page * [Our Pledge](https://agentclientprotocol.com/community/code-of-conduct#our-pledge) * [Our Standards](https://agentclientprotocol.com/community/code-of-conduct#our-standards) * [Enforcement Responsibilities](https://agentclientprotocol.com/community/code-of-conduct#enforcement-responsibilities) * [Scope](https://agentclientprotocol.com/community/code-of-conduct#scope) * [Enforcement](https://agentclientprotocol.com/community/code-of-conduct#enforcement) * [Enforcement Guidelines](https://agentclientprotocol.com/community/code-of-conduct#enforcement-guidelines) * [1\. Correction](https://agentclientprotocol.com/community/code-of-conduct#1-correction) * [2\. Warning](https://agentclientprotocol.com/community/code-of-conduct#2-warning) * [3\. Temporary Ban](https://agentclientprotocol.com/community/code-of-conduct#3-temporary-ban) * [4\. Permanent Ban](https://agentclientprotocol.com/community/code-of-conduct#4-permanent-ban) * [Attribution](https://agentclientprotocol.com/community/code-of-conduct#attribution) --- # Governance - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/community/governance#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Governance [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The following is an interim governance model to provide clearer roles and responsibilities between the various parties collaborating on ACP. ACP is jointly governed by Zed and JetBrains, who collaborate to ensure the protocol serves the broader ecosystem. We aim to operate transparently and make decisions in the best interests of ACP and its community, while working toward transitioning to an independent foundation. This document describes the governance model for the Agent Client Protocol (ACP). It defines the roles, responsibilities, and processes that guide how the project operates and makes decisions. [​](https://agentclientprotocol.com/community/governance#principles) Principles ---------------------------------------------------------------------------------- We aim to operate transparently and make decisions in the best interests of ACP and its community. [​](https://agentclientprotocol.com/community/governance#technical-governance) Technical Governance ------------------------------------------------------------------------------------------------------ The ACP project adopts a hierarchical structure, similar to MCP, Rust Foundation projects, and other open source projects: * A community of **contributors** who file issues, make pull requests, and contribute to the project. * A small set of **maintainers** drive components within the ACP project, such as SDKs, documentation, and others. * Contributors and maintainers are overseen by **core maintainers**, who drive the overall project direction. * The core maintainers have two **lead core maintainers** who are the catch-all decision makers. * Maintainers, core maintainers, and lead core maintainers form the **ACP steering group**. All maintainers are expected to have a strong bias towards ACP’s design philosophy. ### [​](https://agentclientprotocol.com/community/governance#channels) Channels Technical Governance is facilitated through shared [communication channels](https://agentclientprotocol.com/community/communication) of all **maintainers, core maintainers** and **lead maintainers**. Each maintainer group can choose additional communication channels, but all decisions and their supporting discussions must be recorded and made transparently available in one of the main communication channels. ### [​](https://agentclientprotocol.com/community/governance#contributors) Contributors Anyone who submits code, documentation or other improvements is counted as a contributor. Contributors do not have formal decision-making power, but are encouraged to participate in discussions about project direction and propose changes. ### [​](https://agentclientprotocol.com/community/governance#maintainers) Maintainers Maintainers are responsible for [Working or Interest Groups](https://agentclientprotocol.com/community/working-interest-groups) within the ACP project. These generally are independent repositories such as language-specific SDKs, but can also extend to subdirectories of a repository, such as the ACP documentation. Maintainers may adopt their own rules and procedures for making decisions. Maintainers are expected to make decisions for their respective projects independently, but can defer or escalate to the core maintainers when needed. Maintainers are responsible for the: * Thoughtful and productive engagement with community contributors, * Maintaining and improving their respective area of the ACP project, * Supporting documentation, roadmaps and other adjacent parts of the ACP project, * Present ideas from community to core. New maintainers are added by a consensus or majority vote of the current core maintainers, based on sustained and high-quality contributions to the project, alignment with its goals, and a demonstrated commitment to community standards. Prospective maintainers should have a track record of participation in discussions, issue triage, and code or documentation improvements. Maintainers have write and/or admin access to their respective repositories. A maintainer may step down at any time by notifying the other maintainers. In rare cases, a maintainer may be removed by a consensus or a two-thirds supermajority vote of the other maintainers if they are inactive for an extended period, violate the Code of Conduct, or act against the project’s interests. Maintainers can be removed by core maintainers or lead core maintainers at any time and without reason. ### [​](https://agentclientprotocol.com/community/governance#core-maintainers) Core Maintainers Core maintainers are contributors who have write access to ACP’s source code. They review and merge contributions, participate in project decision-making, and help to onboard and mentor new contributors. The core maintainers are expected to have a deep understanding of the Agent Client Protocol and its specification. Their responsibilities include: * Designing, reviewing and steering the evolution of the ACP specification, as well as all other parts of the ACP project, such as documentation, * Articulating a cohesive long-term vision for the project, * Mediating and resolving contentious issues with fairness and transparency, seeking consensus where possible while making decisive choices when necessary, * Appoint or remove maintainers, * Stewardship of the ACP project in the best interest of ACP. The core maintainers as a group have the power to veto any decisions made by maintainers by majority vote. The core maintainers have power to resolve disputes as they see fit. The core maintainers should publicly articulate their decision-making. The core group is responsible for adopting their own procedures for making decisions. New core maintainers are added by a consensus or majority vote of the current core and lead maintainers, based on sustained and high-quality contributions to the project, alignment with its goals, and a demonstrated commitment to community standards. Prospective maintainers should have a track record of participation in discussions, issue triage, and code or documentation improvements. Core maintainers generally have write and admin access to all ACP repositories, but should use the same contribution (usually pull-requests) mechanism as outside contributors. Exceptions can be made based on security considerations. A core maintainer may step down at any time by notifying the other core maintainers. In rare cases, a core maintainer may be removed by a consensus or a two-thirds supermajority vote of the other core maintainers if they are inactive for an extended period, violate the Code of Conduct, or act against the project’s interests. ### [​](https://agentclientprotocol.com/community/governance#lead-maintainers-bdfl) Lead Maintainers (BDFL) ACP has two lead maintainers: Ben Brandt (Zed Industries) and Sergey Ignatov (JetBrains). Lead Maintainers can veto any decision by core maintainers or maintainers. This model is also commonly known as Benevolent Dictator for Life (BDFL) in the open source community. The Lead Maintainers should publicly articulate their decision-making and give clear reasoning for their decisions. Lead maintainers are part of the core maintainer group. Lead Maintainers are administrators on all infrastructure for the ACP project where possible. This includes but is not restricted to all communication channels, GitHub organizations and repositories. The Lead Maintainers are the primary contacts, and responsible for: * Representing ACP in official matters. * Coordinating major decisions about project direction. * Signing off project expenses. A lead maintainer may step down by notifying the other lead maintainer(s). They may recommend a replacement, but it is the remaining lead maintainer(s) responsibility to select a replacement. If all lead maintainers step down, the core maintainers will select new lead maintainers by consensus or majority vote. ### [​](https://agentclientprotocol.com/community/governance#decision-process) Decision Process The core maintainer group meets every two weeks to discuss and vote on proposals, as well as discuss any topics needed. The [ACP RFD process](https://agentclientprotocol.com/rfds/about) and Zulip chat can be used to discuss and vote on smaller proposals as needed. [​](https://agentclientprotocol.com/community/governance#processes) Processes -------------------------------------------------------------------------------- Core and lead maintainers are responsible for all aspects of Agent Client Protocol, including documentation, issues, suggestions for content, and all other parts under the [ACP project](https://github.com/agentclientprotocol) . Maintainers are responsible for documentation, issues, and suggestions of content for their area of the ACP project, but are encouraged to partake in general maintenance of the ACP projects. Maintainers, core maintainers, and lead maintainers should use the same contribution process as external contributors, rather than making direct changes to repos. This provides insight into intent and opportunity for discussion. ### [​](https://agentclientprotocol.com/community/governance#working-and-interest-groups) Working and Interest Groups ACP collaboration and contributions are organized around two structures: [Working Groups and Interest Groups](https://agentclientprotocol.com/community/working-interest-groups) . Interest Groups are responsible for identifying and articulating problems that ACP should address, primarily by facilitating open discussions within the community. In contrast, Working Groups focus on developing concrete solutions by collaboratively producing deliverables, such as RFDs or community-owned implementations of the specification. While input from Interest Groups can help justify the formation of a Working Group, it is not a strict requirement. Similarly, contributions from either Interest Groups or Working Groups are encouraged, but not mandatory, when submitting RFDs or other community proposals. We strongly encourage all contributors interested in working on a specific RFD to first collaborate within an Interest Group. This collaborative process helps ensure that the proposed RFD aligns with protocol needs and is the right direction for its adopters. ### [​](https://agentclientprotocol.com/community/governance#governance-principles) Governance Principles All groups are self-governed while adhering to these core principles: 1. Clear contribution and decision-making processes 2. Open communication and transparent decisions They must: * Document their contribution process * Maintain transparent communication * Make decisions publicly (groups must publish meeting notes and proposals) Projects and working groups without specified processes default to: * GitHub pull requests and issues for contributions * A public channel in the official [ACP Contributor Zulip](https://agentclientprotocol.com/community/communication#zulip) ### [​](https://agentclientprotocol.com/community/governance#maintenance-responsibilities) Maintenance Responsibilities Components without dedicated maintainers (such as documentation) fall under core maintainer responsibility. These follow standard contribution guidelines through pull requests, with maintainers handling reviews and escalating to core maintainer review for any significant changes. Core maintainers and maintainers are encouraged to improve any part of the ACP project, regardless of formal maintenance assignments. [​](https://agentclientprotocol.com/community/governance#communication) Communication ---------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/community/governance#core-maintainer-meetings) Core Maintainer Meetings The core maintainer group meets on a bi-weekly basis to discuss proposals and the project. Notes on proposals should be made public. The meetings themselves are invite-only. If you have a topic for the Core Maintainers and want to be added to the agenda, let the core maintainers know what you want to discuss in advance in Zulip, and you will be invited to join the next meeting. ### [​](https://agentclientprotocol.com/community/governance#public-chat) Public Chat The ACP project maintains a [public Zulip Chat](https://agentclientprotocol.com/community/communication#zulip) with open chats for different groups. The ACP project may have private channels for certain communications. [​](https://agentclientprotocol.com/community/governance#nominating-confirming-and-removing-maintainers) Nominating, Confirming and Removing Maintainers ----------------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/community/governance#the-principles) The Principles * Membership in module maintainer groups is given to individuals on merit basis after they demonstrated strong expertise of their area of work through contributions, reviews, and discussions and are aligned with the overall ACP direction. * For membership in the maintainer group the individual has to demonstrate strong and continued alignment with the overall ACP principles. * No term limits for module maintainers or core maintainers * Light criteria of moving sub-project maintenance to ‘emeritus’ status if they don’t actively participate over long periods of time. Each maintainer group may define the inactive period that’s appropriate for their area. ### [​](https://agentclientprotocol.com/community/governance#nomination-and-removal) Nomination and Removal * Core Maintainers are responsible for adding and removing maintainers. They will take the consideration of existing maintainers into account. * The lead maintainers are responsible for adding and removing core maintainers. #### [​](https://agentclientprotocol.com/community/governance#nomination-process) Nomination Process If a Maintainer (or Core / Lead Maintainer) wishes to propose a nomination for the Core / Lead Maintainers’ consideration, they should follow the following process: 1. Collect evidence for the nomination. This will generally come in the form of a history of merged PRs on the repositories for which maintainership is being considered. 2. Discuss among maintainers of the relevant group(s) as to whether they would be supportive of approving the nomination. 3. DM a Core Maintainer to create a private channel in Zulip, in the format `nomination-{name}-{group}`. Add all core maintainers, lead maintainers, and co-maintainers on the relevant group. 4. Provide context for the individual under nomination. See below for suggestions on what to include here. 5. Create a Zulip topic and ask Core / Lead Maintainers to vote Yes / No on the nomination. Reaching consensus is encouraged though not required. 6. After Core / Lead Maintainers discuss and/or vote, if the nomination is favorable, relevant members with permissions to update GitHub and Zulip roles will add the nominee to the appropriate groups. The nominator should announce the new maintainership in the relevant Zulip channel. 7. The temporary Zulip channel will be deleted a week later. Suggestions for the kind of information to share with core maintainers when nominating someone: * GitHub profile link, LinkedIn profile link, Zulip username * For what group(s) are you nominating the individual for maintainership * Whether the group(s) agree that this person should be elevated to maintainership * Description of their contributions to date (including links to most substantial contributions) * Description of expected contributions moving forward (e.g. Are they eager to be a maintainer? Will they have capacity to do so?) * Other context about the individual (e.g. current employer, motivations behind ACP involvement) * Anything else you think may be relevant to consider for the nomination [​](https://agentclientprotocol.com/community/governance#current-maintainers) Current Maintainers ---------------------------------------------------------------------------------------------------- Refer to [the maintainer list](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/MAINTAINERS.md) . [​](https://agentclientprotocol.com/community/governance#security-policy-and-vulnerability-disclosure) Security Policy and Vulnerability Disclosure ------------------------------------------------------------------------------------------------------------------------------------------------------ * Zed will triage all potential security and vulnerability issues between the Zed team and other maintainers * Reports can be submitted to [security@zed.dev](mailto:security@zed.dev) [​](https://agentclientprotocol.com/community/governance#legal-licensing-and-contributor-terms) Legal, Licensing, and Contributor Terms ------------------------------------------------------------------------------------------------------------------------------------------ * All repositories in the ACP organization should be licensed under the Apache 2.0 License. * This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms: > By contributing to this project, you agree that your contributions will be licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) > . You affirm that you have the legal right to submit your work, that you are not including code you do not have rights to, and that you understand contributions are made without requiring a Contributor License Agreement (CLA). Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/community/code-of-conduct) [Working and Interest GroupsLearn about the two forms of collaborative groups within the Agent Client Protocol's governance structure - Working Groups and Interest Groups.\ \ Next](https://agentclientprotocol.com/community/working-interest-groups) ⌘I On this page * [Principles](https://agentclientprotocol.com/community/governance#principles) * [Technical Governance](https://agentclientprotocol.com/community/governance#technical-governance) * [Channels](https://agentclientprotocol.com/community/governance#channels) * [Contributors](https://agentclientprotocol.com/community/governance#contributors) * [Maintainers](https://agentclientprotocol.com/community/governance#maintainers) * [Core Maintainers](https://agentclientprotocol.com/community/governance#core-maintainers) * [Lead Maintainers (BDFL)](https://agentclientprotocol.com/community/governance#lead-maintainers-bdfl) * [Decision Process](https://agentclientprotocol.com/community/governance#decision-process) * [Processes](https://agentclientprotocol.com/community/governance#processes) * [Working and Interest Groups](https://agentclientprotocol.com/community/governance#working-and-interest-groups) * [Governance Principles](https://agentclientprotocol.com/community/governance#governance-principles) * [Maintenance Responsibilities](https://agentclientprotocol.com/community/governance#maintenance-responsibilities) * [Communication](https://agentclientprotocol.com/community/governance#communication) * [Core Maintainer Meetings](https://agentclientprotocol.com/community/governance#core-maintainer-meetings) * [Public Chat](https://agentclientprotocol.com/community/governance#public-chat) * [Nominating, Confirming and Removing Maintainers](https://agentclientprotocol.com/community/governance#nominating-confirming-and-removing-maintainers) * [The Principles](https://agentclientprotocol.com/community/governance#the-principles) * [Nomination and Removal](https://agentclientprotocol.com/community/governance#nomination-and-removal) * [Nomination Process](https://agentclientprotocol.com/community/governance#nomination-process) * [Current Maintainers](https://agentclientprotocol.com/community/governance#current-maintainers) * [Security Policy and Vulnerability Disclosure](https://agentclientprotocol.com/community/governance#security-policy-and-vulnerability-disclosure) * [Legal, Licensing, and Contributor Terms](https://agentclientprotocol.com/community/governance#legal-licensing-and-contributor-terms) --- # Publications - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/publications#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Publications [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [​](https://agentclientprotocol.com/publications#talks) Talks ---------------------------------------------------------------- AI Builders Berlin: Agents in the IDE ------------------------------------- November 26, 2025 · Ben Brandt OpenAI | Codex Meetup Berlin: Integrating Codex Into IntelliJ ------------------------------------------------------------- January 28, 2026 · Anna Zhdan AI Builders Amsterdam: AI Agents and IDEs ----------------------------------------- January 29, 2026 · Sergey Ignatov JUG Bern: Your AI Agent In Any Editor ------------------------------------- February 11, 2026 · Anna Zhdan Munich AI Tech Meetup @ JetBrains: Your AI Agent In Any Editor -------------------------------------------------------------- February 25, 2026 · Anna Zhdan London Agentic AI Meetup ------------------------ March 11, 2026 · Ben Brandt, Sergey Ignatov Copilot Developer Camp Shanghai: GitHub Copilot in JetBrains AI Assistant via ACP --------------------------------------------------------------------------------- March 21, 2026 · Jun Han GitHub Copilot Dev Days Shanghai: Agent Client Protocol in GitHub Copilot ------------------------------------------------------------------------- April 11, 2026 · Jun Han [​](https://agentclientprotocol.com/publications#videos) Videos ------------------------------------------------------------------ What Is the Agent Client Protocol — and Why JetBrains and Zed Are Building It Together -------------------------------------------------------------------------------------- Conversation with Ben Brandt, Sergey Ignatov, and Jan-Niklas Wortmann Agent Client Protocol in GitHub Copilot --------------------------------------- Jun Han Was this page helpful? YesNo ⌘I On this page * [Talks](https://agentclientprotocol.com/publications#talks) * [Videos](https://agentclientprotocol.com/publications#videos) --- # Agents - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/get-started/agents#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Get Started Agents [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The following agents can be used with an ACP Client: * [AgentPool](https://phil65.github.io/agentpool/advanced/acp-integration/) * [Augment Code](https://docs.augmentcode.com/cli/acp) * [AutoDev](https://github.com/phodal/auto-dev) * [Blackbox AI](https://docs.blackbox.ai/features/blackbox-cli/introduction) * [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview) (via [Zed’s SDK adapter](https://github.com/zed-industries/claude-agent-acp) ) * [Cline](https://cline.bot/) * [Codex CLI](https://developers.openai.com/codex/cli) (via [Zed’s adapter](https://github.com/zed-industries/codex-acp) ) * [Code Assistant](https://github.com/stippi/code-assistant?tab=readme-ov-file#configuration) * [crow-cli](https://crow-ai.dev/) * [Cursor](https://cursor.com/docs/cli/acp) * [Docker’s cagent](https://github.com/docker/cagent) * [fast-agent](https://fast-agent.ai/acp) * [Factory Droid](https://factory.ai/) * [fount](https://github.com/steve02081504/fount) * [Gemini CLI](https://github.com/google-gemini/gemini-cli) * [GitHub Copilot](https://github.com/features/copilot) (in [public preview](https://github.blog/changelog/2026-01-28-acp-support-in-copilot-cli-is-now-in-public-preview/) ) * [Goose](https://block.github.io/goose/docs/guides/acp-clients) * [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp) * [Junie by JetBrains](https://junie.jetbrains.com/) * [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) * [Kiro CLI](https://kiro.dev/docs/cli/acp/) * [Minion Code](https://github.com/femto/minion-code) * [Mistral Vibe](https://github.com/mistralai/mistral-vibe) * [OpenClaw](https://docs.openclaw.ai/cli/acp) * [OpenCode](https://github.com/sst/opencode) * [OpenHands](https://docs.openhands.dev/openhands/usage/run-openhands/acp) * [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) (via [pi-acp adapter](https://github.com/svkozak/pi-acp) ) * [Qoder CLI](https://docs.qoder.com/cli/acp) * [Qwen Code](https://github.com/QwenLM/qwen-code) * [Stakpak](https://github.com/stakpak/agent?tab=readme-ov-file#agent-client-protocol-acp) * [stdio Bus](https://github.com/stdiobus/stdiobus) * [VT Code](https://github.com/vinhnx/vtcode/blob/main/README.md#zed-ide-integration-agent-client-protocol) Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/get-started/architecture) [ClientsClients, frameworks, connectors, and related tools around the Agent Client Protocol.\ \ Next](https://agentclientprotocol.com/get-started/clients) ⌘I --- # Architecture - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/get-started/architecture#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Get Started Architecture [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The Agent Client Protocol defines a standard interface for communication between AI agents and client applications. The architecture is designed to be flexible, extensible, and platform-agnostic. [​](https://agentclientprotocol.com/get-started/architecture#design-philosophy) Design Philosophy ---------------------------------------------------------------------------------------------------- The protocol architecture follows several key principles: 1. **MCP-friendly**: The protocol is built on JSON-RPC, and re-uses MCP types where possible so that integrators don’t need to build yet-another representation for common data types. 2. **UX-first**: It is designed to solve the UX challenges of interacting with AI agents; ensuring there’s enough flexibility to render clearly the agents intent, but is no more abstract than it needs to be. 3. **Trusted**: ACP works when you’re using a code editor to talk to a model you trust. You still have controls over the agent’s tool calls, but the code editor gives the agent access to local files and MCP servers. [​](https://agentclientprotocol.com/get-started/architecture#setup) Setup ---------------------------------------------------------------------------- When the user tries to connect to an agent, the editor boots the agent sub-process on demand, and all communication happens over stdin/stdout. Each connection can support several concurrent sessions, so you can have multiple trains of thought going on at once. ![Server Client setup](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/images/server-client.svg?w=2500&fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=19b2d711567dfb170387c50ed5b7865c) ACP makes heavy use of JSON-RPC notifications to allow the agent to stream updates to the UI in real-time. It also uses JSON-RPC’s bidirectional requests to allow the agent to make requests of the code editor: for example to request permissions for a tool call. [​](https://agentclientprotocol.com/get-started/architecture#mcp) MCP ------------------------------------------------------------------------ Commonly the code editor will have user-configured MCP servers. When forwarding the prompt from the user, it passes configuration for these to the agent. This allows the agent to connect directly to the MCP server. ![MCP Server connection](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/images/mcp.svg?w=2500&fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=8d7e9d0b57c316821342b117e3789c41) The code editor may itself also wish to export MCP based tools. Instead of trying to run MCP and ACP on the same socket, the code editor can provide its own MCP server as configuration. As agents may only support MCP over stdio, the code editor can provide a small proxy that tunnels requests back to itself: ![MCP connection to self](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/images/mcp-proxy.svg?w=2500&fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=1ec11e0516d8061882ed520370a8248e) Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/get-started/introduction) [AgentsAgents implementing the Agent Client Protocol.\ \ Next](https://agentclientprotocol.com/get-started/agents) ⌘I On this page * [Design Philosophy](https://agentclientprotocol.com/get-started/architecture#design-philosophy) * [Setup](https://agentclientprotocol.com/get-started/architecture#setup) * [MCP](https://agentclientprotocol.com/get-started/architecture#mcp) --- # Java - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/libraries/java#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Libraries Java [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The [java-sdk](https://github.com/agentclientprotocol/java-sdk) provides Java models, JSON-RPC plumbing, and side-specific connection helpers for building ACP-compatible agents and clients. The repository includes runnable examples for client and agent implementations, plus Spring AI integrations, under [`examples/`](https://github.com/agentclientprotocol/java-sdk/tree/main/examples) . For dependency setup and API details, see the repository README and published Javadocs from the project. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/libraries/kotlin) [PythonPython library for the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/libraries/python) ⌘I --- # Kotlin - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/libraries/kotlin#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Libraries Kotlin [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The [kotlin-sdk](https://github.com/agentclientprotocol/kotlin-sdk) provides implementations of both sides of the Agent Client Protocol that you can use to build your own agent server or client. **It currently supports JVM, other targets are in progress.** To get started, add the repository to your build file: repositories { mavenCentral() } Add the dependency: dependencies { implementation("com.agentclientprotocol:acp:0.1.0-SNAPSHOT") } The [sample](https://github.com/agentclientprotocol/kotlin-sdk/tree/master/samples/kotlin-acp-client-sample) demonstrates how to implement both sides of the protocol. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/schema) [JavaJava library for the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/libraries/java) ⌘I --- # Clients - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/get-started/clients#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Get Started Clients [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The following projects implement ACP directly, connect ACP agents to other environments, or support adjacent coding-agent workflows. [​](https://agentclientprotocol.com/get-started/clients#editors-and-ides) Editors and IDEs --------------------------------------------------------------------------------------------- * [Chrome ACP](https://github.com/Areo-Joe/chrome-acp) (Chrome extension / PWA) * Emacs via [agent-shell.el](https://github.com/xenodium/agent-shell) * [JetBrains](https://www.jetbrains.com/help/ai-assistant/acp.html) * [neovim](https://neovim.io/) * through the [CodeCompanion](https://github.com/olimorris/codecompanion.nvim) plugin * through the [carlos-algms/agentic.nvim](https://github.com/carlos-algms/agentic.nvim) plugin * through the [yetone/avante.nvim](https://github.com/yetone/avante.nvim) plugin * [Obsidian](https://obsidian.md/) — through the [Agent Client](https://github.com/RAIT-09/obsidian-agent-client) plugin * [Unity Agent Client](https://github.com/nuskey8/UnityAgentClient) (Unity editor) * Visual Studio Code — through the [ACP Client](https://github.com/formulahendry/vscode-acp) extension * [Zed](https://zed.dev/docs/ai/external-agents) [​](https://agentclientprotocol.com/get-started/clients#clients-and-apps) Clients and apps --------------------------------------------------------------------------------------------- * [ACP UI](https://github.com/formulahendry/acp-ui) * [acpx (CLI)](https://github.com/openclaw/acpx) * [gemini-cli-desktop](https://github.com/Piebald-AI/gemini-cli-desktop) * [Agent Studio](https://github.com/sxhxliang/agent-studio) * [AionUi](https://github.com/iOfficeAI/AionUi) * [aizen](https://aizen.win/) * [DeepChat](https://github.com/ThinkInAIXYZ/deepchat) * [fabriqa.ai](https://fabriqa.ai/) * [Harnss](https://github.com/OpenSource03/harnss) * [iflow-cli](https://github.com/iflow-ai/iflow-cli) * [Jockey](https://github.com/recailai/jockey) — open-source multi-agent orchestrator (Tauri + Rust + SolidJS) that coordinates Claude Code, Gemini CLI, and Codex CLI via ACP * [Lody](https://lody.ai/) * [Minion Mind](https://minion-mind.nebulame.com/) — through the [Agent Client](https://github.com/RAIT-09/obsidian-agent-client) plugin * [Mitto](https://github.com/inercia/mitto) * [Nori CLI](https://github.com/tilework-tech/nori-cli) * [Ngent](https://github.com/beyond5959/ngent) * [RayClaw](https://github.com/rayclaw/rayclaw?tab=readme-ov-file#acp-agent-client-protocol) * [RLM Code](https://github.com/SuperagenticAI/rlm-code) * [Sidequery _(coming soon)_](https://sidequery.dev/) * [Tidewave](https://tidewave.ai/) * [Toad](https://www.batrachian.ai/) * [Web Browser with AI SDK](https://github.com/mcpc-tech/ai-elements-remix-template) (powered by [@mcpc/acp-ai-provider](https://github.com/mcpc-tech/mcpc/tree/main/packages/acp-ai-provider) ) [​](https://agentclientprotocol.com/get-started/clients#notebook-and-data-tools) Notebook and data tools ----------------------------------------------------------------------------------------------------------- * [agent-client-kernel](https://github.com/wiki3-ai/agent-client-kernel) (Jupyter notebooks) * DuckDB — through the [sidequery/duckdb-acp](https://github.com/sidequery/duckdb-acp) extension * [marimo notebook](https://github.com/marimo-team/marimo) [​](https://agentclientprotocol.com/get-started/clients#mobile-clients) Mobile clients ----------------------------------------------------------------------------------------- These mobile-first tools bring ACP and related coding-agent workflows to phones and tablets: * [Agmente](https://agmente.halliharp.com/) ([GitHub](https://github.com/rebornix/Agmente) ) (iOS) * [Ferngeist](https://github.com/arafatamim/Ferngeist) (Android) * [Happy](https://happy.engineering/) ([GitHub](https://github.com/slopus/happy) ) (iOS, Android, Web) * [Mobvibe](https://github.com/Eric-Song-Nop/mobvibe) (iOS, Android, Web) [​](https://agentclientprotocol.com/get-started/clients#messaging) Messaging ------------------------------------------------------------------------------- * [ACP Discord](https://github.com/broven/acp-discord) (Discord) * [duckdb-claude-slack](https://github.com/sidequery/duckdb-claude-slack) (Slack) * [Juan](https://github.com/DiscreteTom/juan) (Slack) * [OpenACP](https://github.com/Open-ACP/OpenACP) (Telegram, Discord, Slack) — self-hosted bridge for ACP agents; streams tool calls and responses in real time * [Telegram ACP Bot](https://github.com/mgaitan/telegram-acp-bot) (Telegram) — through the [`telegram-acp-bot`](https://github.com/mgaitan/telegram-acp-bot) connector * [Telegram-ACP](https://github.com/SuperKenVery/Telegram-ACP/) (Telegram) — Supports multi-thread chat and message streaming * [WeChat ACP](https://github.com/formulahendry/wechat-acp) (WeChat) [​](https://agentclientprotocol.com/get-started/clients#frameworks) Frameworks --------------------------------------------------------------------------------- These frameworks add ACP support through dedicated integrations or adapters: * [AgentPool](https://phil65.github.io/agentpool/) — with built-in ACP integration for IDEs and external ACP agents * [fast-agent](https://fast-agent.ai/acp/) — through [`fast-agent-acp`](https://fast-agent.ai/acp/) * [Koog](https://docs.koog.ai/agent-client-protocol/) — through the [`agents-features-acp`](https://github.com/JetBrains/koog/tree/develop/examples/notebooks/acp) integration * [LangChain / LangGraph](https://docs.langchain.com/oss/python/deepagents/acp) — through [Deep Agents ACP](https://docs.langchain.com/oss/python/deepagents/acp) * [LlamaIndex](https://github.com/AstraBert/workflows-acp) — through the [`workflows-acp`](https://github.com/AstraBert/workflows-acp) adapter for Agent Workflows * [LLMling-Agent](https://github.com/phil65/llmling-agent) — with built-in ACP support for running agents through ACP clients [​](https://agentclientprotocol.com/get-started/clients#connectors) Connectors --------------------------------------------------------------------------------- These connectors bridge ACP into other environments and transport layers: * [AgentRQ](https://github.com/agentrq/acp-gateway) — bridges stdio-based ACP agents to the AgentRQ - Human-in-the-loop task collaboration service using MCP server. * [Aptove Bridge](https://github.com/aptove/bridge) — bridges stdio-based ACP agents to the Aptove mobile client over WebSocket * [OpenClaw](https://docs.openclaw.ai/cli/acp) — through the [`openclaw acp`](https://docs.openclaw.ai/cli/acp) bridge to an OpenClaw Gateway * [stdio Bus](https://stdiobus.com/) – deterministic stdio-based kernel providing transport-level routing for ACP/MCP-style agent protocols. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/get-started/agents) [ACP RegistryThe easiest way to find and install ACP-compatible agents.\ \ Next](https://agentclientprotocol.com/get-started/registry) ⌘I On this page * [Editors and IDEs](https://agentclientprotocol.com/get-started/clients#editors-and-ides) * [Clients and apps](https://agentclientprotocol.com/get-started/clients#clients-and-apps) * [Notebook and data tools](https://agentclientprotocol.com/get-started/clients#notebook-and-data-tools) * [Mobile clients](https://agentclientprotocol.com/get-started/clients#mobile-clients) * [Messaging](https://agentclientprotocol.com/get-started/clients#messaging) * [Frameworks](https://agentclientprotocol.com/get-started/clients#frameworks) * [Connectors](https://agentclientprotocol.com/get-started/clients#connectors) --- # Updates - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/updates#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Updates [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) This page is for larger ACP announcements and project updates. For lifecycle changes to Requests for Dialog, see [RFD Updates](https://agentclientprotocol.com/rfds/updates) . [​](https://agentclientprotocol.com/updates#april-22-2026) April 22, 2026 Working Groups [​](https://agentclientprotocol.com/updates#transports-working-group) Transports Working Group ------------------------------------------------------------------------------------------------- A new Transports Working Group has been formed to standardize remote agent transports like WebSockets and HTTP.Anna Zhdan (JetBrains / Core Maintainer) and Alex Hancock (Block / Goose) are leading the effort, with a Draft RFD already underway.[Read the full announcement](https://agentclientprotocol.com/announcements/transports-working-group) . [​](https://agentclientprotocol.com/updates#march-9-2026) March 9, 2026 Protocol [​](https://agentclientprotocol.com/updates#acp-registry-is-released) ACP Registry is Released ------------------------------------------------------------------------------------------------- The ACP Registry RFD has moved to Completed and the initial version of the registry is released.The registry gives ACP clients a standard way to discover, install, and configure compatible agents without inventing custom integration metadata.[Read the full announcement](https://agentclientprotocol.com/announcements/acp-agent-registry-stabilized) . [​](https://agentclientprotocol.com/updates#march-9-2026-2) March 9, 2026 Protocol [​](https://agentclientprotocol.com/updates#session-info-update-is-stabilized) Session Info Update is Stabilized ------------------------------------------------------------------------------------------------------------------- The Session Info Update RFD has moved to Completed and the session\_info\_update notification is stabilized.This lets agents push session metadata updates to clients in real time so titles and related metadata stay current without polling.[Read the full announcement](https://agentclientprotocol.com/announcements/session-info-update-stabilized) . [​](https://agentclientprotocol.com/updates#march-9-2026-3) March 9, 2026 Protocol [​](https://agentclientprotocol.com/updates#session-list-is-stabilized) Session List is Stabilized ----------------------------------------------------------------------------------------------------- The Session List RFD has moved to Completed and the session/list method is stabilized.This gives clients a standard way to discover existing sessions from an agent for features like history, switching, and cleanup.[Read the full announcement](https://agentclientprotocol.com/announcements/session-list-stabilized) . [​](https://agentclientprotocol.com/updates#february-18-2026) February 18, 2026 Governance [​](https://agentclientprotocol.com/updates#sergey-ignatov-joins-acp-as-lead-maintainer) Sergey Ignatov joins ACP as Lead Maintainer --------------------------------------------------------------------------------------------------------------------------------------- Sergey Ignatov from JetBrains is now a Lead Maintainer for ACP.This reflects the growing collaboration between Zed and JetBrains around ACP and recognizes Sergey’s significant contributions to the protocol.[Read the full announcement](https://agentclientprotocol.com/announcements/sergey-ignatov-lead-maintainer) . [​](https://agentclientprotocol.com/updates#february-4-2026) February 4, 2026 Protocol [​](https://agentclientprotocol.com/updates#session-config-options-are-now-stabilized) Session Config Options are now Stabilized ----------------------------------------------------------------------------------------------------------------------------------- The Session Config Options RFD has moved to Completed and is stabilized.This gives agents a flexible way to expose session-level configuration such as models, modes, reasoning levels, and other selectors.[Read the full announcement](https://agentclientprotocol.com/announcements/session-config-options-stabilized) . [​](https://agentclientprotocol.com/updates#october-24-2025) October 24, 2025 Protocol [​](https://agentclientprotocol.com/updates#implementation-information-for-agents-and-clients) Implementation information for agents and clients --------------------------------------------------------------------------------------------------------------------------------------------------- ACP now allows agents and clients to share implementation details during initialization using the optional clientInfo and agentInfo fields.This makes it easier to identify which implementation is running, improve compatibility diagnostics, and understand adoption across the ecosystem.[Read the full announcement](https://agentclientprotocol.com/announcements/implementation-information) . Was this page helpful? YesNo [Transports Working GroupAnnouncing the new Transports Working Group, to stabilize new transport formats.\ \ Next](https://agentclientprotocol.com/announcements/transports-working-group) ⌘I FiltersClear ProtocolWorking GroupsGovernance --- # TypeScript - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/libraries/typescript#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Libraries TypeScript [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The [@agentclientprotocol/sdk](https://www.npmjs.com/package/@agentclientprotocol/sdk) npm package provides implementations of both sides of the Agent Client Protocol that you can use to build your own agent server or client. To get started, add the package as a dependency to your project: npm install @agentclientprotocol/sdk Depending on what kind of tool you’re building, you’ll need to use either the [AgentSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/AgentSideConnection.html) class or the [ClientSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/ClientSideConnection.html) class to establish communication with the ACP counterpart. You can find example implementations of both sides in the [main repository](https://github.com/agentclientprotocol/typescript-sdk/tree/main/src/examples) . These can be run from your terminal or from an ACP Client like [Zed](https://zed.dev/) , making them great starting points for your own integration! Browse the [TypeScript library reference](https://agentclientprotocol.github.io/typescript-sdk) for detailed API documentation. For a complete, production-ready implementation of an ACP agent, check out [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/zed-integration/zedIntegration.ts) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/libraries/rust) [CommunityCommunity managed libraries for the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/libraries/community) ⌘I --- # Rust - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/libraries/rust#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Libraries Rust [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The [agent-client-protocol](https://crates.io/crates/agent-client-protocol) Rust crate provides implementations of both sides of the Agent Client Protocol that you can use to build your own agent server or client. To get started, add the crate as a dependency to your project’s `Cargo.toml`: cargo add agent-client-protocol Depending on what kind of tool you’re building, you’ll need to implement either the [Agent](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/trait.Agent.html) trait or the [Client](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/trait.Client.html) trait to define the interaction with the ACP counterpart. The [agent](https://github.com/agentclientprotocol/rust-sdk/blob/main/src/agent-client-protocol/examples/agent.rs) and [client](https://github.com/agentclientprotocol/rust-sdk/blob/main/src/agent-client-protocol/examples/client.rs) example binaries provide runnable examples of how to do this, which you can use as a starting point. You can read the full documentation for the `agent-client-protocol` crate on [docs.rs](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/) . [​](https://agentclientprotocol.com/libraries/rust#users) Users ------------------------------------------------------------------ The `agent-client-protocol` crate powers the integration with external agents in the [Zed](https://zed.dev/) editor. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/libraries/python) [TypeScriptTypeScript library for the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/libraries/typescript) ⌘I On this page * [Users](https://agentclientprotocol.com/libraries/rust#users) --- # Community - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/libraries/community#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Libraries Community [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [​](https://agentclientprotocol.com/libraries/community#dart) Dart --------------------------------------------------------------------- * [acp\_dart](https://github.com/SkrOYC/acp-dart) [​](https://agentclientprotocol.com/libraries/community#net) .NET -------------------------------------------------------------------- * [acpdotnet](https://github.com/microsoft/acpdotnet) [​](https://agentclientprotocol.com/libraries/community#emacs) Emacs ----------------------------------------------------------------------- * [acp.el](https://github.com/xenodium/acp.el) [​](https://agentclientprotocol.com/libraries/community#go) Go ----------------------------------------------------------------- * [acp-go-sdk](https://github.com/coder/acp-go-sdk) * [acp-go](https://github.com/ironpark/acp-go) [​](https://agentclientprotocol.com/libraries/community#react) React ----------------------------------------------------------------------- * [use-acp](https://github.com/marimo-team/use-acp) [​](https://agentclientprotocol.com/libraries/community#typescript) TypeScript --------------------------------------------------------------------------------- * [acp-ts-sdk](https://github.com/langwatch/acp-ts-sdk) [​](https://agentclientprotocol.com/libraries/community#swift) Swift ----------------------------------------------------------------------- * [swift-acp](https://github.com/wiedymi/swift-acp) * [swift-sdk](https://github.com/aptove/swift-sdk) * [acp-swift-sdk](https://github.com/rebornix/acp-swift-sdk) Was this page helpful? YesNo [Previous\ \ TypeScriptTypeScript library for the Agent Client Protocol](https://agentclientprotocol.com/libraries/typescript) ⌘I On this page * [Dart](https://agentclientprotocol.com/libraries/community#dart) * [.NET](https://agentclientprotocol.com/libraries/community#net) * [Emacs](https://agentclientprotocol.com/libraries/community#emacs) * [Go](https://agentclientprotocol.com/libraries/community#go) * [React](https://agentclientprotocol.com/libraries/community#react) * [TypeScript](https://agentclientprotocol.com/libraries/community#typescript) * [Swift](https://agentclientprotocol.com/libraries/community#swift) --- # Python - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/libraries/python#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Libraries Python [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The [agentclientprotocol/python-sdk](https://github.com/agentclientprotocol/python-sdk) repository packages Pydantic models, async base classes, and JSON-RPC plumbing so you can build ACP-compatible agents and clients in Python. It mirrors the official ACP schema and ships helper utilities for both sides of the protocol. To get started, add the SDK to your project: pip install agent-client-protocol (Using [uv](https://github.com/astral-sh/uv) ? Run `uv add agent-client-protocol`.) The repository includes runnable examples for agents, clients, Gemini CLI bridges, and dual-agent/client demos under [`examples/`](https://github.com/agentclientprotocol/python-sdk/tree/main/examples) . Browse the full documentation—including the quickstart, contrib helpers, and API reference—at [agentclientprotocol.github.io/python-sdk](https://agentclientprotocol.github.io/python-sdk/) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/libraries/java) [RustRust library for the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/libraries/rust) ⌘I --- # Introduction - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/get-started/introduction#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Get Started Introduction [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The Agent Client Protocol (ACP) standardizes communication between code editors/IDEs and coding agents and is suitable for both local and remote scenarios. [​](https://agentclientprotocol.com/get-started/introduction#why-acp) Why ACP? --------------------------------------------------------------------------------- AI coding agents and editors are tightly coupled but interoperability isn’t the default. Each editor must build custom integrations for every agent they want to support, and agents must implement editor-specific APIs to reach users. This creates several problems: * Integration overhead: Every new agent-editor combination requires custom work * Limited compatibility: Agents work with only a subset of available editors * Developer lock-in: Choosing an agent often means accepting their available interfaces ACP solves this by providing a standardized protocol for agent-editor communication, similar to how the [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) standardized language server integration. Agents that implement ACP work with any compatible editor. Editors that support ACP gain access to the entire ecosystem of ACP-compatible agents. This decoupling allows both sides to innovate independently while giving developers the freedom to choose the best tools for their workflow. [​](https://agentclientprotocol.com/get-started/introduction#overview) Overview ---------------------------------------------------------------------------------- ACP assumes that the user is primarily in their editor, and wants to reach out and use agents to assist them with specific tasks. ACP is suitable for both local and remote scenarios: * **Local agents** run as sub-processes of the code editor, communicating via JSON-RPC over stdio. * **Remote agents** can be hosted in the cloud or on separate infrastructure, communicating over HTTP or WebSocket Full support for remote agents is a work in progress. We are actively collaborating with agentic platforms to ensure the protocol addresses the specific requirements of cloud-hosted and remote deployment scenarios. The protocol re-uses the JSON representations used in MCP where possible, but includes custom types for useful agentic coding UX elements, like displaying diffs. The default format for user-readable text is Markdown, which allows enough flexibility to represent rich formatting without requiring that the code editor is capable of rendering HTML. Was this page helpful? YesNo [ArchitectureOverview of the Agent Client Protocol architecture.\ \ Next](https://agentclientprotocol.com/get-started/architecture) ⌘I On this page * [Why ACP?](https://agentclientprotocol.com/get-started/introduction#why-acp) * [Overview](https://agentclientprotocol.com/get-started/introduction#overview) --- # Agent Plan - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/agent-plan#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Agent Plan [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Plans are execution strategies for complex tasks that require multiple steps. Agents may share plans with Clients through [`session/update`](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) notifications, providing real-time visibility into their thinking and progress. [​](https://agentclientprotocol.com/protocol/agent-plan#creating-plans) Creating Plans ----------------------------------------------------------------------------------------- When the language model creates an execution plan, the Agent **SHOULD** report it to the Client: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "plan", "entries": [\ {\ "content": "Analyze the existing codebase structure",\ "priority": "high",\ "status": "pending"\ },\ {\ "content": "Identify components that need refactoring",\ "priority": "high",\ "status": "pending"\ },\ {\ "content": "Create unit tests for critical functions",\ "priority": "medium",\ "status": "pending"\ }\ ] } } } [​](https://agentclientprotocol.com/protocol/agent-plan#param-entries) entries PlanEntry\[\] required An array of [plan entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) representing the tasks to be accomplished [​](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) Plan Entries ------------------------------------------------------------------------------------- Each plan entry represents a specific task or goal within the overall execution strategy: [​](https://agentclientprotocol.com/protocol/agent-plan#param-content) content string required A human-readable description of what this task aims to accomplish [​](https://agentclientprotocol.com/protocol/agent-plan#param-priority) priority PlanEntryPriority required The relative importance of this task. * `high` * `medium` * `low` [​](https://agentclientprotocol.com/protocol/agent-plan#param-status) status PlanEntryStatus required The current [execution status](https://agentclientprotocol.com/protocol/agent-plan#status) of this task * `pending` * `in_progress` * `completed` [​](https://agentclientprotocol.com/protocol/agent-plan#updating-plans) Updating Plans ----------------------------------------------------------------------------------------- As the Agent progresses through the plan, it **SHOULD** report updates by sending more `session/update` notifications with the same structure. The Agent **MUST** send a complete list of all plan entries in each update and their current status. The Client **MUST** replace the current plan completely. ### [​](https://agentclientprotocol.com/protocol/agent-plan#dynamic-planning) Dynamic Planning Plans can evolve during execution. The Agent **MAY** add, remove, or modify plan entries as it discovers new requirements or completes tasks, allowing it to adapt based on what it learns. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/terminals) [Session ModesSwitch between different agent operating modes\ \ Next](https://agentclientprotocol.com/protocol/session-modes) ⌘I On this page * [Creating Plans](https://agentclientprotocol.com/protocol/agent-plan#creating-plans) * [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) * [Updating Plans](https://agentclientprotocol.com/protocol/agent-plan#updating-plans) * [Dynamic Planning](https://agentclientprotocol.com/protocol/agent-plan#dynamic-planning) --- # File System - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/file-system#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol File System [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The filesystem methods allow Agents to read and write text files within the Client’s environment. These methods enable Agents to access unsaved editor state and allow Clients to track file modifications made during agent execution. [​](https://agentclientprotocol.com/protocol/file-system#checking-support) Checking Support ---------------------------------------------------------------------------------------------- Before attempting to use filesystem methods, Agents **MUST** verify that the Client supports these capabilities by checking the [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities) field in the `initialize` response: { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true } } } } If `readTextFile` or `writeTextFile` is `false` or not present, the Agent **MUST NOT** attempt to call the corresponding filesystem method. [​](https://agentclientprotocol.com/protocol/file-system#reading-files) Reading Files ---------------------------------------------------------------------------------------- The `fs/read_text_file` method allows Agents to read text file contents from the Client’s filesystem, including unsaved changes in the editor. { "jsonrpc": "2.0", "id": 3, "method": "fs/read_text_file", "params": { "sessionId": "sess_abc123def456", "path": "/home/user/project/src/main.py", "line": 10, "limit": 50 } } [​](https://agentclientprotocol.com/protocol/file-system#param-session-id) sessionId SessionId required The [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) for this request [​](https://agentclientprotocol.com/protocol/file-system#param-path) path string required Absolute path to the file to read [​](https://agentclientprotocol.com/protocol/file-system#param-line) line number Optional line number to start reading from (1-based) [​](https://agentclientprotocol.com/protocol/file-system#param-limit) limit number Optional maximum number of lines to read The Client responds with the file contents: { "jsonrpc": "2.0", "id": 3, "result": { "content": "def hello_world():\n print('Hello, world!')\n" } } [​](https://agentclientprotocol.com/protocol/file-system#writing-files) Writing Files ---------------------------------------------------------------------------------------- The `fs/write_text_file` method allows Agents to write or update text files in the Client’s filesystem. { "jsonrpc": "2.0", "id": 4, "method": "fs/write_text_file", "params": { "sessionId": "sess_abc123def456", "path": "/home/user/project/config.json", "content": "{\n \"debug\": true,\n \"version\": \"1.0.0\"\n}" } } [​](https://agentclientprotocol.com/protocol/file-system#param-session-id-1) sessionId SessionId required The [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) for this request [​](https://agentclientprotocol.com/protocol/file-system#param-path-1) path string required Absolute path to the file to write.The Client **MUST** create the file if it doesn’t exist. [​](https://agentclientprotocol.com/protocol/file-system#param-content) content string required The text content to write to the file The Client responds with an empty result on success: { "jsonrpc": "2.0", "id": 4, "result": null } Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/tool-calls) [TerminalsExecuting and managing terminal commands\ \ Next](https://agentclientprotocol.com/protocol/terminals) ⌘I On this page * [Checking Support](https://agentclientprotocol.com/protocol/file-system#checking-support) * [Reading Files](https://agentclientprotocol.com/protocol/file-system#reading-files) * [Writing Files](https://agentclientprotocol.com/protocol/file-system#writing-files) --- # Overview - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/overview#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Overview [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The Agent Client Protocol allows [Agents](https://agentclientprotocol.com/protocol/overview#agent) and [Clients](https://agentclientprotocol.com/protocol/overview#client) to communicate by exposing methods that each side can call and sending notifications to inform each other of events. [​](https://agentclientprotocol.com/protocol/overview#communication-model) Communication Model ------------------------------------------------------------------------------------------------- The protocol follows the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification with two types of messages: * **Methods**: Request-response pairs that expect a result or error * **Notifications**: One-way messages that don’t expect a response [​](https://agentclientprotocol.com/protocol/overview#message-flow) Message Flow ----------------------------------------------------------------------------------- A typical flow follows this pattern: 1 [](https://agentclientprotocol.com/protocol/overview#) Initialization Phase * Client → Agent: `initialize` to establish connection * Client → Agent: `authenticate` if required by the Agent 2 [](https://agentclientprotocol.com/protocol/overview#) Session Setup - either: * Client → Agent: `session/new` to create a new session * Client → Agent: `session/load` to resume an existing session if supported 3 [](https://agentclientprotocol.com/protocol/overview#) Prompt Turn * Client → Agent: `session/prompt` to send user message * Agent → Client: `session/update` notifications for progress updates * Agent → Client: File operations or permission requests as needed * Client → Agent: `session/cancel` to interrupt processing if needed * Turn ends and the Agent sends the `session/prompt` response with a stop reason [​](https://agentclientprotocol.com/protocol/overview#agent) Agent --------------------------------------------------------------------- Agents are programs that use generative AI to autonomously modify code. They typically run as subprocesses of the Client. ### [​](https://agentclientprotocol.com/protocol/overview#baseline-methods) Baseline Methods [​](https://agentclientprotocol.com/protocol/overview#param-initialize) initialize [Schema](https://agentclientprotocol.com/protocol/schema#initialize) [Negotiate versions and exchange capabilities.](https://agentclientprotocol.com/protocol/initialization) . [​](https://agentclientprotocol.com/protocol/overview#param-authenticate) authenticate [Schema](https://agentclientprotocol.com/protocol/schema#authenticate) Authenticate with the Agent (if required). [​](https://agentclientprotocol.com/protocol/overview#param-session-new) session/new [Schema](https://agentclientprotocol.com/protocol/schema#session%2Fnew) [Create a new conversation session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) . [​](https://agentclientprotocol.com/protocol/overview#param-session-prompt) session/prompt [Schema](https://agentclientprotocol.com/protocol/schema#session%2Fprompt) [Send user prompts](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message) to the Agent. ### [​](https://agentclientprotocol.com/protocol/overview#optional-methods) Optional Methods [​](https://agentclientprotocol.com/protocol/overview#param-session-load) session/load [Schema](https://agentclientprotocol.com/protocol/schema#session%2Fload) [Load an existing session](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) (requires `loadSession` capability). [​](https://agentclientprotocol.com/protocol/overview#param-session-set-mode) session/set\_mode [Schema](https://agentclientprotocol.com/protocol/schema#session%2Fset-mode) [Switch between agent operating modes](https://agentclientprotocol.com/protocol/session-modes#setting-the-current-mode) . ### [​](https://agentclientprotocol.com/protocol/overview#notifications) Notifications [​](https://agentclientprotocol.com/protocol/overview#param-session-cancel) session/cancel [Schema](https://agentclientprotocol.com/protocol/schema#session%2Fcancel) [Cancel ongoing operations](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) (no response expected). [​](https://agentclientprotocol.com/protocol/overview#client) Client ----------------------------------------------------------------------- Clients provide the interface between users and agents. They are typically code editors (IDEs, text editors) but can also be other UIs for interacting with agents. Clients manage the environment, handle user interactions, and control access to resources. ### [​](https://agentclientprotocol.com/protocol/overview#baseline-methods-2) Baseline Methods [​](https://agentclientprotocol.com/protocol/overview#param-session-request-permission) session/request\_permission [Schema](https://agentclientprotocol.com/protocol/schema#session%2Frequest_permission) [Request user authorization](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) for tool calls. ### [​](https://agentclientprotocol.com/protocol/overview#optional-methods-2) Optional Methods [​](https://agentclientprotocol.com/protocol/overview#param-fs-read-text-file) fs/read\_text\_file [Schema](https://agentclientprotocol.com/protocol/schema#fs%2Fread_text_file) [Read file contents](https://agentclientprotocol.com/protocol/file-system#reading-files) (requires `fs.readTextFile` capability). [​](https://agentclientprotocol.com/protocol/overview#param-fs-write-text-file) fs/write\_text\_file [Schema](https://agentclientprotocol.com/protocol/schema#fs%2Fwrite_text_file) [Write file contents](https://agentclientprotocol.com/protocol/file-system#writing-files) (requires `fs.writeTextFile` capability). [​](https://agentclientprotocol.com/protocol/overview#param-terminal-create) terminal/create [Schema](https://agentclientprotocol.com/protocol/schema#terminal%2Fcreate) [Create a new terminal](https://agentclientprotocol.com/protocol/terminals) (requires `terminal` capability). [​](https://agentclientprotocol.com/protocol/overview#param-terminal-output) terminal/output [Schema](https://agentclientprotocol.com/protocol/schema#terminal%2Foutput) Get terminal output and exit status (requires `terminal` capability). [​](https://agentclientprotocol.com/protocol/overview#param-terminal-release) terminal/release [Schema](https://agentclientprotocol.com/protocol/schema#terminal%2Frelease) Release a terminal (requires `terminal` capability). [​](https://agentclientprotocol.com/protocol/overview#param-terminal-wait-for-exit) terminal/wait\_for\_exit [Schema](https://agentclientprotocol.com/protocol/schema#terminal%2Fwait_for_exit) Wait for terminal command to exit (requires `terminal` capability). [​](https://agentclientprotocol.com/protocol/overview#param-terminal-kill) terminal/kill [Schema](https://agentclientprotocol.com/protocol/schema#terminal%2Fkill) Kill terminal command without releasing (requires `terminal` capability). ### [​](https://agentclientprotocol.com/protocol/overview#notifications-2) Notifications [​](https://agentclientprotocol.com/protocol/overview#param-session-update) session/update [Schema](https://agentclientprotocol.com/protocol/schema#session%2Fupdate) [Send session updates](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) to inform the Client of changes (no response expected). This includes: - [Message chunks](https://agentclientprotocol.com/protocol/content) (agent, user, thought) - [Tool calls and updates](https://agentclientprotocol.com/protocol/tool-calls) - [Plans](https://agentclientprotocol.com/protocol/agent-plan) - [Available commands updates](https://agentclientprotocol.com/protocol/slash-commands#advertising-commands) - [Mode changes](https://agentclientprotocol.com/protocol/session-modes#from-the-agent) [​](https://agentclientprotocol.com/protocol/overview#argument-requirements) Argument requirements ----------------------------------------------------------------------------------------------------- * All file paths in the protocol **MUST** be absolute. * Line numbers are 1-based [​](https://agentclientprotocol.com/protocol/overview#error-handling) Error Handling --------------------------------------------------------------------------------------- All methods follow standard JSON-RPC 2.0 [error handling](https://www.jsonrpc.org/specification#error_object) : * Successful responses include a `result` field * Errors include an `error` object with `code` and `message` * Notifications never receive responses (success or error) [​](https://agentclientprotocol.com/protocol/overview#extensibility) Extensibility ------------------------------------------------------------------------------------- The protocol provides built-in mechanisms for adding custom functionality while maintaining compatibility: * Add custom data using `_meta` fields * Create custom methods by prefixing their name with underscore (`_`) * Advertise custom capabilities during initialization Learn about [protocol extensibility](https://agentclientprotocol.com/protocol/extensibility) to understand how to use these mechanisms. [​](https://agentclientprotocol.com/protocol/overview#next-steps) Next Steps ------------------------------------------------------------------------------- * Learn about [Initialization](https://agentclientprotocol.com/protocol/initialization) to understand version and capability negotiation * Understand [Session Setup](https://agentclientprotocol.com/protocol/session-setup) for creating and loading sessions * Review the [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn) lifecycle * Explore [Extensibility](https://agentclientprotocol.com/protocol/extensibility) to add custom features Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/get-started/registry) [InitializationHow all Agent Client Protocol connections begin\ \ Next](https://agentclientprotocol.com/protocol/initialization) ⌘I On this page * [Communication Model](https://agentclientprotocol.com/protocol/overview#communication-model) * [Message Flow](https://agentclientprotocol.com/protocol/overview#message-flow) * [Agent](https://agentclientprotocol.com/protocol/overview#agent) * [Baseline Methods](https://agentclientprotocol.com/protocol/overview#baseline-methods) * [Optional Methods](https://agentclientprotocol.com/protocol/overview#optional-methods) * [Notifications](https://agentclientprotocol.com/protocol/overview#notifications) * [Client](https://agentclientprotocol.com/protocol/overview#client) * [Baseline Methods](https://agentclientprotocol.com/protocol/overview#baseline-methods-2) * [Optional Methods](https://agentclientprotocol.com/protocol/overview#optional-methods-2) * [Notifications](https://agentclientprotocol.com/protocol/overview#notifications-2) * [Argument requirements](https://agentclientprotocol.com/protocol/overview#argument-requirements) * [Error Handling](https://agentclientprotocol.com/protocol/overview#error-handling) * [Extensibility](https://agentclientprotocol.com/protocol/overview#extensibility) * [Next Steps](https://agentclientprotocol.com/protocol/overview#next-steps) --- # Extensibility - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/extensibility#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Extensibility [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The Agent Client Protocol provides built-in extension mechanisms that allow implementations to add custom functionality while maintaining compatibility with the core protocol. These mechanisms ensure that Agents and Clients can innovate without breaking interoperability. [​](https://agentclientprotocol.com/protocol/extensibility#the-meta-field) The `_meta` Field ----------------------------------------------------------------------------------------------- All types in the protocol include a `_meta` field with type `{ [key: string]: unknown }` that implementations can use to attach custom information. This includes requests, responses, notifications, and even nested types like content blocks, tool calls, plan entries, and capability objects. { "jsonrpc": "2.0", "id": 1, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [\ {\ "type": "text",\ "text": "Hello, world!"\ }\ ], "_meta": { "traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01", "zed.dev/debugMode": true } } } Clients may propagate fields to the agent for correlation purposes, such as `requestId`. The following root-level keys in `_meta` **SHOULD** be reserved for [W3C trace context](https://www.w3.org/TR/trace-context/) to guarantee interop with existing MCP implementations and OpenTelemetry tooling: * `traceparent` * `tracestate` * `baggage` Implementations **MUST NOT** add any custom fields at the root of a type that’s part of the specification. All possible names are reserved for future protocol versions. [​](https://agentclientprotocol.com/protocol/extensibility#extension-methods) Extension Methods -------------------------------------------------------------------------------------------------- The protocol reserves any method name starting with an underscore (`_`) for custom extensions. This allows implementations to add new functionality without the risk of conflicting with future protocol versions. Extension methods follow standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) semantics: * **[Requests](https://www.jsonrpc.org/specification#request_object) ** - Include an `id` field and expect a response * **[Notifications](https://www.jsonrpc.org/specification#notification) ** - Omit the `id` field and are one-way ### [​](https://agentclientprotocol.com/protocol/extensibility#custom-requests) Custom Requests In addition to the requests specified by the protocol, implementations **MAY** expose and call custom JSON-RPC requests as long as their name starts with an underscore (`_`). { "jsonrpc": "2.0", "id": 1, "method": "_zed.dev/workspace/buffers", "params": { "language": "rust" } } Upon receiving a custom request, implementations **MUST** respond accordingly with the provided `id`: { "jsonrpc": "2.0", "id": 1, "result": { "buffers": [\ { "id": 0, "path": "/home/user/project/src/main.rs" },\ { "id": 1, "path": "/home/user/project/src/editor.rs" }\ ] } } If the receiving end doesn’t recognize the custom method name, it should respond with the standard “Method not found” error: { "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "Method not found" } } To avoid such cases, extensions **SHOULD** advertise their [custom capabilities](https://agentclientprotocol.com/protocol/extensibility#advertising-custom-capabilities) so that callers can check their availability first and adapt their behavior or interface accordingly. ### [​](https://agentclientprotocol.com/protocol/extensibility#custom-notifications) Custom Notifications Custom notifications are regular JSON-RPC notifications that start with an underscore (`_`). Like all notifications, they omit the `id` field: { "jsonrpc": "2.0", "method": "_zed.dev/file_opened", "params": { "path": "/home/user/project/src/editor.rs" } } Unlike with custom requests, implementations **SHOULD** ignore unrecognized notifications. [​](https://agentclientprotocol.com/protocol/extensibility#advertising-custom-capabilities) Advertising Custom Capabilities ------------------------------------------------------------------------------------------------------------------------------ Implementations **SHOULD** use the `_meta` field in capability objects to advertise support for extensions and their methods: { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "loadSession": true, "_meta": { "zed.dev": { "workspace": true, "fileNotifications": true } } } } } This allows implementations to negotiate custom features during initialization without breaking compatibility with standard Clients and Agents. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/slash-commands) [TransportsMechanisms for agents and clients to communicate with each other\ \ Next](https://agentclientprotocol.com/protocol/transports) ⌘I On this page * [The \_meta Field](https://agentclientprotocol.com/protocol/extensibility#the-meta-field) * [Extension Methods](https://agentclientprotocol.com/protocol/extensibility#extension-methods) * [Custom Requests](https://agentclientprotocol.com/protocol/extensibility#custom-requests) * [Custom Notifications](https://agentclientprotocol.com/protocol/extensibility#custom-notifications) * [Advertising Custom Capabilities](https://agentclientprotocol.com/protocol/extensibility#advertising-custom-capabilities) --- # Content - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/content#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Content [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Content blocks represent displayable information that flows through the Agent Client Protocol. They provide a structured way to handle various types of user-facing content—whether it’s text from language models, images for analysis, or embedded resources for context. Content blocks appear in: * User prompts sent via [`session/prompt`](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message) * Language model output streamed through [`session/update`](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) notifications * Progress updates and results from [tool calls](https://agentclientprotocol.com/protocol/tool-calls) [​](https://agentclientprotocol.com/protocol/content#content-types) Content Types ------------------------------------------------------------------------------------ The Agent Client Protocol uses the same `ContentBlock` structure as the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification/2025-06-18/schema#contentblock) . This design choice enables Agents to seamlessly forward content from MCP tool outputs without transformation. ### [​](https://agentclientprotocol.com/protocol/content#text-content) Text Content Plain text messages form the foundation of most interactions. { "type": "text", "text": "What's the weather like today?" } All Agents **MUST** support text content blocks when included in prompts. [​](https://agentclientprotocol.com/protocol/content#param-text) text string required The text content to display [​](https://agentclientprotocol.com/protocol/content#param-annotations) annotations Annotations Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations) . ### [​](https://agentclientprotocol.com/protocol/content#image-content) Image Content Images can be included for visual context or analysis. { "type": "image", "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..." } Requires the `image` [prompt capability](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities) when included in prompts. [​](https://agentclientprotocol.com/protocol/content#param-data) data string required Base64-encoded image data [​](https://agentclientprotocol.com/protocol/content#param-mime-type) mimeType string required The MIME type of the image (e.g., “image/png”, “image/jpeg”) [​](https://agentclientprotocol.com/protocol/content#param-uri) uri string Optional URI reference for the image source [​](https://agentclientprotocol.com/protocol/content#param-annotations-1) annotations Annotations Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations) . ### [​](https://agentclientprotocol.com/protocol/content#audio-content) Audio Content Audio data for transcription or analysis. { "type": "audio", "mimeType": "audio/wav", "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAAB..." } Requires the `audio` [prompt capability](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities) when included in prompts. [​](https://agentclientprotocol.com/protocol/content#param-data-1) data string required Base64-encoded audio data [​](https://agentclientprotocol.com/protocol/content#param-mime-type-1) mimeType string required The MIME type of the audio (e.g., “audio/wav”, “audio/mp3”) [​](https://agentclientprotocol.com/protocol/content#param-annotations-2) annotations Annotations Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations) . ### [​](https://agentclientprotocol.com/protocol/content#embedded-resource) Embedded Resource Complete resource contents embedded directly in the message. { "type": "resource", "resource": { "uri": "file:///home/user/script.py", "mimeType": "text/x-python", "text": "def hello():\n print('Hello, world!')" } } This is the preferred way to include context in prompts, such as when using @-mentions to reference files or other resources. By embedding the content directly in the request, Clients can include context from sources that the Agent may not have direct access to. Requires the `embeddedContext` [prompt capability](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities) when included in prompts. [​](https://agentclientprotocol.com/protocol/content#param-resource) resource EmbeddedResourceResource required The embedded resource contents, which can be either: Show Text Resource [​](https://agentclientprotocol.com/protocol/content#param-uri-1) uri string required The URI identifying the resource [​](https://agentclientprotocol.com/protocol/content#param-text-1) text string required The text content of the resource [​](https://agentclientprotocol.com/protocol/content#param-mime-type-2) mimeType string Optional MIME type of the text content Show Blob Resource [​](https://agentclientprotocol.com/protocol/content#param-uri-2) uri string required The URI identifying the resource [​](https://agentclientprotocol.com/protocol/content#param-blob) blob string required Base64-encoded binary data [​](https://agentclientprotocol.com/protocol/content#param-mime-type-3) mimeType string Optional MIME type of the blob [​](https://agentclientprotocol.com/protocol/content#param-annotations-3) annotations Annotations Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations) . ### [​](https://agentclientprotocol.com/protocol/content#resource-link) Resource Link References to resources that the Agent can access. { "type": "resource_link", "uri": "file:///home/user/document.pdf", "name": "document.pdf", "mimeType": "application/pdf", "size": 1024000 } [​](https://agentclientprotocol.com/protocol/content#param-uri-3) uri string required The URI of the resource [​](https://agentclientprotocol.com/protocol/content#param-name) name string required A human-readable name for the resource [​](https://agentclientprotocol.com/protocol/content#param-mime-type-4) mimeType string The MIME type of the resource [​](https://agentclientprotocol.com/protocol/content#param-title) title string Optional display title for the resource [​](https://agentclientprotocol.com/protocol/content#param-description) description string Optional description of the resource contents [​](https://agentclientprotocol.com/protocol/content#param-size) size integer Optional size of the resource in bytes [​](https://agentclientprotocol.com/protocol/content#param-annotations-4) annotations Annotations Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations) . Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/prompt-turn) [Tool CallsHow Agents report tool call execution\ \ Next](https://agentclientprotocol.com/protocol/tool-calls) ⌘I On this page * [Content Types](https://agentclientprotocol.com/protocol/content#content-types) * [Text Content](https://agentclientprotocol.com/protocol/content#text-content) * [Image Content](https://agentclientprotocol.com/protocol/content#image-content) * [Audio Content](https://agentclientprotocol.com/protocol/content#audio-content) * [Embedded Resource](https://agentclientprotocol.com/protocol/content#embedded-resource) * [Resource Link](https://agentclientprotocol.com/protocol/content#resource-link) --- # Slash Commands - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/slash-commands#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Slash Commands [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows. Commands are run as part of regular [prompt](https://agentclientprotocol.com/protocol/prompt-turn) requests where the Client includes the command text in the prompt. [​](https://agentclientprotocol.com/protocol/slash-commands#advertising-commands) Advertising commands --------------------------------------------------------------------------------------------------------- After creating a session, the Agent **MAY** send a list of available commands via the `available_commands_update` session notification: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "available_commands_update", "availableCommands": [\ {\ "name": "web",\ "description": "Search the web for information",\ "input": {\ "hint": "query to search for"\ }\ },\ {\ "name": "test",\ "description": "Run tests for the current project"\ },\ {\ "name": "plan",\ "description": "Create a detailed implementation plan",\ "input": {\ "hint": "description of what to plan"\ }\ }\ ] } } } [​](https://agentclientprotocol.com/protocol/slash-commands#param-available-commands) availableCommands AvailableCommand\[\] The list of commands available in this session ### [​](https://agentclientprotocol.com/protocol/slash-commands#availablecommand) AvailableCommand [​](https://agentclientprotocol.com/protocol/slash-commands#param-name) name string required The command name (e.g., “web”, “test”, “plan”) [​](https://agentclientprotocol.com/protocol/slash-commands#param-description) description string required Human-readable description of what the command does [​](https://agentclientprotocol.com/protocol/slash-commands#param-input) input AvailableCommandInput Optional input specification for the command ### [​](https://agentclientprotocol.com/protocol/slash-commands#availablecommandinput) AvailableCommandInput Currently supports unstructured text input: [​](https://agentclientprotocol.com/protocol/slash-commands#param-hint) hint string required A hint to display when the input hasn’t been provided yet [​](https://agentclientprotocol.com/protocol/slash-commands#dynamic-updates) Dynamic updates ----------------------------------------------------------------------------------------------- The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. This allows commands to be added based on context, removed when no longer relevant, or modified with updated descriptions. [​](https://agentclientprotocol.com/protocol/slash-commands#running-commands) Running commands ------------------------------------------------------------------------------------------------- Commands are included as regular user messages in prompt requests: { "jsonrpc": "2.0", "id": 3, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [\ {\ "type": "text",\ "text": "/web agent client protocol"\ }\ ] } } The Agent recognizes the command prefix and processes it accordingly. Commands may be accompanied by any other user message content types (images, audio, etc.) in the same prompt array. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/session-config-options) [ExtensibilityAdding custom data and capabilities\ \ Next](https://agentclientprotocol.com/protocol/extensibility) ⌘I On this page * [Advertising commands](https://agentclientprotocol.com/protocol/slash-commands#advertising-commands) * [AvailableCommand](https://agentclientprotocol.com/protocol/slash-commands#availablecommand) * [AvailableCommandInput](https://agentclientprotocol.com/protocol/slash-commands#availablecommandinput) * [Dynamic updates](https://agentclientprotocol.com/protocol/slash-commands#dynamic-updates) * [Running commands](https://agentclientprotocol.com/protocol/slash-commands#running-commands) --- # ACP Registry - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/get-started/registry#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Get Started ACP Registry [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [​](https://agentclientprotocol.com/get-started/registry#overview) Overview ------------------------------------------------------------------------------ The ACP Registry is an easy way for developers to distribute their ACP-compatible agents to any client that speaks the protocol. This is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods) . Visit [the registry repository on GitHub](https://github.com/agentclientprotocol/registry) to learn more about it. [​](https://agentclientprotocol.com/get-started/registry#available-agents) Available Agents ---------------------------------------------------------------------------------------------- Amp --- ACP wrapper for Amp - the frontier coding agent**0.7.0**,[](https://github.com/tao12345666333/amp-acp) Auggie CLI ---------- Augment Code’s powerful software agent, backed by industry-leading context engine**0.24.0**,[](https://github.com/augmentcode/auggie) Autohand Code ------------- Autohand Code - AI coding agent powered by Autohand AI**0.2.1**,[](https://github.com/autohandai/autohand-acp) Claude Agent ------------ ACP wrapper for Anthropic’s Claude**0.30.0**,[](https://github.com/agentclientprotocol/claude-agent-acp) Cline ----- Autonomous coding agent CLI - capable of creating/editing files, running commands, using the browser, and more**2.15.0**,[](https://github.com/cline/cline) Codebuddy Code -------------- Tencent Cloud’s official intelligent coding tool**2.93.1** Codex CLI --------- ACP adapter for OpenAI’s coding assistant**0.11.1**,[](https://github.com/zed-industries/codex-acp) Corust Agent ------------ Co-building with a seasoned Rust partner.**0.5.0**,[](https://github.com/Corust-ai/corust-agent-release) crow-cli -------- Minimal ACP Native Coding Agent**0.1.19**,[](https://github.com/crow-cli/crow-cli) Cursor ------ Cursor’s coding agent**2026.03.30** DeepAgents ---------- Batteries-included AI coding and general purpose agent powered by LangChain.**0.1.7**,[](https://github.com/langchain-ai/deepagentsjs) Factory Droid ------------- Factory Droid - AI coding agent powered by Factory AI**0.106.0** fast-agent ---------- Code and build agents with comprehensive multi-provider support**0.6.22**,[](https://github.com/evalstate/fast-agent) Gemini CLI ---------- Google’s official CLI for Gemini**0.38.2**,[](https://github.com/google-gemini/gemini-cli) GitHub Copilot -------------- GitHub’s AI pair programmer**1.0.34**,[](https://github.com/github/copilot-cli) goose ----- A local, extensible, open source AI agent that automates engineering tasks**1.31.1**,[](https://github.com/block/goose) Junie ----- AI Coding Agent by JetBrains**1417.47.0**,[](https://github.com/JetBrains/junie) Kilo ---- The open source coding agent**7.2.14**,[](https://github.com/Kilo-Org/kilocode) Kimi CLI -------- Moonshot AI’s coding assistant**1.37.0**,[](https://github.com/MoonshotAI/kimi-cli) Minion Code ----------- An enhanced AI code assistant built on the Minion framework with rich development tools**0.1.44**,[](https://github.com/femto/minion-code) Mistral Vibe ------------ Mistral’s open-source coding assistant**2.8.1**,[](https://github.com/mistralai/mistral-vibe) Nova ---- Nova by Compass AI - a fully-fledged software engineer at your command**1.0.100**,[](https://github.com/Compass-Agentic-Platform/nova) OpenCode -------- The open source coding agent**1.14.20**,[](https://github.com/anomalyco/opencode) pi ACP ------ ACP adapter for pi coding agent**0.0.26**,[](https://github.com/svkozak/pi-acp) Qoder CLI --------- AI coding assistant with agentic capabilities**0.1.47** Qwen Code --------- Alibaba’s Qwen coding assistant**0.14.5**,[](https://github.com/QwenLM/qwen-code) Stakpak ------- Open-source DevOps agent in Rust with enterprise-grade security**0.3.74**,[](https://github.com/stakpak/agent) [​](https://agentclientprotocol.com/get-started/registry#using-the-registry) Using the Registry -------------------------------------------------------------------------------------------------- Clients can fetch the registry programmatically: curl https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json The registry JSON contains all agent metadata including distribution information for automatic installation. [​](https://agentclientprotocol.com/get-started/registry#submit-your-agent) Submit your Agent ------------------------------------------------------------------------------------------------ To add your agent to the registry: 1. Fork the [registry repository on GitHub](https://github.com/agentclientprotocol/registry) 2. Create a folder with your agent’s ID (lowercase, hyphens allowed) 3. Add an `agent.json` file following [the schema](https://github.com/agentclientprotocol/registry/blob/main/agent.schema.json) 4. Optionally add an `icon.svg` (16x16 recommended) 5. Submit a pull request See the [contributing guide](https://github.com/agentclientprotocol/registry/blob/main/CONTRIBUTING.md) for details. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/get-started/clients) [OverviewHow the Agent Client Protocol works\ \ Next](https://agentclientprotocol.com/protocol/overview) ⌘I On this page * [Overview](https://agentclientprotocol.com/get-started/registry#overview) * [Available Agents](https://agentclientprotocol.com/get-started/registry#available-agents) * [Using the Registry](https://agentclientprotocol.com/get-started/registry#using-the-registry) * [Submit your Agent](https://agentclientprotocol.com/get-started/registry#submit-your-agent) --- # Initialization - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/initialization#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Initialization [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The Initialization phase allows [Clients](https://agentclientprotocol.com/protocol/overview#client) and [Agents](https://agentclientprotocol.com/protocol/overview#agent) to negotiate protocol versions, capabilities, and authentication methods. Before a Session can be created, Clients **MUST** initialize the connection by calling the `initialize` method with: * The latest [protocol version](https://agentclientprotocol.com/protocol/initialization#protocol-version) supported * The [capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities) supported They **SHOULD** also provide a name and version to the Agent. { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true }, "terminal": true }, "clientInfo": { "name": "my-client", "title": "My Client", "version": "1.0.0" } } } The Agent **MUST** respond with the chosen [protocol version](https://agentclientprotocol.com/protocol/initialization#protocol-version) and the [capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities) it supports. It **SHOULD** also provide a name and version to the Client as well: { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "loadSession": true, "promptCapabilities": { "image": true, "audio": true, "embeddedContext": true }, "mcpCapabilities": { "http": true, "sse": true } }, "agentInfo": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" }, "authMethods": [] } } [​](https://agentclientprotocol.com/protocol/initialization#protocol-version) Protocol version ------------------------------------------------------------------------------------------------- The protocol versions that appear in the `initialize` requests and responses are a single integer that identifies a **MAJOR** protocol version. This version is only incremented when breaking changes are introduced. Clients and Agents **MUST** agree on a protocol version and act according to its specification. See [Capabilities](https://agentclientprotocol.com/protocol/initialization#capabilities) to learn how non-breaking features are introduced. ### [​](https://agentclientprotocol.com/protocol/initialization#version-negotiation) Version Negotiation The `initialize` request **MUST** include the latest protocol version the Client supports. If the Agent supports the requested version, it **MUST** respond with the same version. Otherwise, the Agent **MUST** respond with the latest version it supports. If the Client does not support the version specified by the Agent in the `initialize` response, the Client **SHOULD** close the connection and inform the user about it. [​](https://agentclientprotocol.com/protocol/initialization#capabilities) Capabilities ----------------------------------------------------------------------------------------- Capabilities describe features supported by the Client and the Agent. All capabilities included in the `initialize` request are **OPTIONAL**. Clients and Agents **SHOULD** support all possible combinations of their peer’s capabilities. The introduction of new capabilities is not considered a breaking change. Therefore, Clients and Agents **MUST** treat all capabilities omitted in the `initialize` request as **UNSUPPORTED**. Capabilities are high-level and are not attached to a specific base protocol concept. Capabilities may specify the availability of protocol methods, notifications, or a subset of their parameters. They may also signal behaviors of the Agent or Client implementation. Implementations can also [advertise custom capabilities](https://agentclientprotocol.com/protocol/extensibility#advertising-custom-capabilities) using the `_meta` field to indicate support for protocol extensions. ### [​](https://agentclientprotocol.com/protocol/initialization#client-capabilities) Client Capabilities The Client **SHOULD** specify whether it supports the following capabilities: #### [​](https://agentclientprotocol.com/protocol/initialization#file-system) File System [​](https://agentclientprotocol.com/protocol/initialization#param-read-text-file) readTextFile boolean The `fs/read_text_file` method is available. [​](https://agentclientprotocol.com/protocol/initialization#param-write-text-file) writeTextFile boolean The `fs/write_text_file` method is available. Learn more about File System methods #### [​](https://agentclientprotocol.com/protocol/initialization#terminal) Terminal [​](https://agentclientprotocol.com/protocol/initialization#param-terminal) terminal boolean All `terminal/*` methods are available, allowing the Agent to execute and manage shell commands. Learn more about Terminals ### [​](https://agentclientprotocol.com/protocol/initialization#agent-capabilities) Agent Capabilities The Agent **SHOULD** specify whether it supports the following capabilities: [​](https://agentclientprotocol.com/protocol/initialization#param-load-session) loadSession boolean default: false The [`session/load`](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) method is available. [​](https://agentclientprotocol.com/protocol/initialization#param-prompt-capabilities) promptCapabilities PromptCapabilities Object Object indicating the different types of [content](https://agentclientprotocol.com/protocol/content) that may be included in `session/prompt` requests. #### [​](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities) Prompt capabilities As a baseline, all Agents **MUST** support `ContentBlock::Text` and `ContentBlock::ResourceLink` in `session/prompt` requests. Optionally, they **MAY** support richer types of [content](https://agentclientprotocol.com/protocol/content) by specifying the following capabilities: [​](https://agentclientprotocol.com/protocol/initialization#param-image) image boolean default: false The prompt may include `ContentBlock::Image` [​](https://agentclientprotocol.com/protocol/initialization#param-audio) audio boolean default: false The prompt may include `ContentBlock::Audio` [​](https://agentclientprotocol.com/protocol/initialization#param-embedded-context) embeddedContext boolean default: false The prompt may include `ContentBlock::Resource` #### [​](https://agentclientprotocol.com/protocol/initialization#mcp-capabilities) MCP capabilities [​](https://agentclientprotocol.com/protocol/initialization#param-http) http boolean default: false The Agent supports connecting to MCP servers over HTTP. [​](https://agentclientprotocol.com/protocol/initialization#param-sse) sse boolean default: false The Agent supports connecting to MCP servers over SSE.Note: This transport has been deprecated by the MCP spec. #### [​](https://agentclientprotocol.com/protocol/initialization#session-capabilities) Session Capabilities As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`. Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities. `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol. [​](https://agentclientprotocol.com/protocol/initialization#implementation-information) Implementation Information --------------------------------------------------------------------------------------------------------------------- Both Clients and Agents **SHOULD** provide information about their implementation in the `clientInfo` and `agentInfo` fields respectively. Both take the following three fields: [​](https://agentclientprotocol.com/protocol/initialization#param-name) name string Intended for programmatic or logical use, but can be used as a display name fallback if title isn’t present. [​](https://agentclientprotocol.com/protocol/initialization#param-title) title string Intended for UI and end-user contexts — optimized to be human-readable and easily understood. If not provided, the name should be used for display. [​](https://agentclientprotocol.com/protocol/initialization#param-version) version string Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. Note: in future versions of the protocol, this information will be required. * * * Once the connection is initialized, you’re ready to [create a session](https://agentclientprotocol.com/protocol/session-setup) and begin the conversation with the Agent. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/overview) [Session SetupCreating and loading sessions\ \ Next](https://agentclientprotocol.com/protocol/session-setup) ⌘I On this page * [Protocol version](https://agentclientprotocol.com/protocol/initialization#protocol-version) * [Version Negotiation](https://agentclientprotocol.com/protocol/initialization#version-negotiation) * [Capabilities](https://agentclientprotocol.com/protocol/initialization#capabilities) * [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities) * [File System](https://agentclientprotocol.com/protocol/initialization#file-system) * [Terminal](https://agentclientprotocol.com/protocol/initialization#terminal) * [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities) * [Prompt capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities) * [MCP capabilities](https://agentclientprotocol.com/protocol/initialization#mcp-capabilities) * [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities) * [Implementation Information](https://agentclientprotocol.com/protocol/initialization#implementation-information) --- # Session List - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/session-list#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Session List [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The `session/list` method allows Clients to discover sessions known to an Agent. Clients can use this to display session history and switch between sessions. Agents can also push session metadata updates to Clients in real-time via the `session_info_update` notification, keeping session titles and metadata in sync without polling. Before listing sessions, Clients **MUST** first complete the [initialization](https://agentclientprotocol.com/protocol/initialization) phase to verify the Agent supports this capability. [​](https://agentclientprotocol.com/protocol/session-list#checking-support) Checking Support ----------------------------------------------------------------------------------------------- Before attempting to list sessions, Clients **MUST** verify that the Agent supports this capability by checking the `sessionCapabilities.list` field in the `initialize` response: { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "list": {} } } } } If `sessionCapabilities.list` is not present, the Agent does not support listing sessions and Clients **MUST NOT** attempt to call `session/list`. [​](https://agentclientprotocol.com/protocol/session-list#listing-sessions) Listing Sessions ----------------------------------------------------------------------------------------------- Clients discover existing sessions by calling the `session/list` method with optional filtering and pagination parameters: { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": { "cwd": "/home/user/project", "cursor": "eyJwYWdlIjogMn0=" } } All parameters are optional. A request with an empty `params` object returns the first page of sessions. [​](https://agentclientprotocol.com/protocol/session-list#param-cwd) cwd string Filter sessions by working directory. Must be an absolute path. Only sessions with a matching `cwd` are returned. [​](https://agentclientprotocol.com/protocol/session-list#param-cursor) cursor string Opaque cursor token from a previous response’s `nextCursor` field for cursor-based pagination. See [Pagination](https://agentclientprotocol.com/protocol/session-list#pagination) . The Agent **MUST** respond with a list of sessions and optional pagination metadata: { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [\ {\ "sessionId": "sess_abc123def456",\ "cwd": "/home/user/project",\ "title": "Implement session list API",\ "updatedAt": "2025-10-29T14:22:15Z",\ "_meta": {\ "messageCount": 12,\ "hasErrors": false\ }\ },\ {\ "sessionId": "sess_xyz789ghi012",\ "cwd": "/home/user/another-project",\ "title": "Debug authentication flow",\ "updatedAt": "2025-10-28T16:45:30Z"\ },\ {\ "sessionId": "sess_uvw345rst678",\ "cwd": "/home/user/project",\ "updatedAt": "2025-10-27T15:30:00Z"\ }\ ], "nextCursor": "eyJwYWdlIjogM30=" } } [​](https://agentclientprotocol.com/protocol/session-list#param-sessions) sessions SessionInfo\[\] required Array of session information objects. Show SessionInfo [​](https://agentclientprotocol.com/protocol/session-list#param-session-id) sessionId string required Unique identifier for the session. [​](https://agentclientprotocol.com/protocol/session-list#param-cwd-1) cwd string required Working directory for the session. Always an absolute path. [​](https://agentclientprotocol.com/protocol/session-list#param-title) title string Human-readable title for the session. May be auto-generated from the first prompt. [​](https://agentclientprotocol.com/protocol/session-list#param-updated-at) updatedAt string ISO 8601 timestamp of the last activity in the session. [​](https://agentclientprotocol.com/protocol/session-list#param-meta) \_meta object Agent-specific metadata. See [Extensibility](https://agentclientprotocol.com/protocol/extensibility) . [​](https://agentclientprotocol.com/protocol/session-list#param-next-cursor) nextCursor string Opaque cursor token. If present, pass this in the next request’s `cursor` parameter to fetch the next page. If absent, there are no more results. When no sessions match the criteria, the Agent **MUST** return an empty `sessions` array. [​](https://agentclientprotocol.com/protocol/session-list#pagination) Pagination ----------------------------------------------------------------------------------- `session/list` uses cursor-based pagination. The request includes an optional `cursor`, and the response includes `nextCursor` when more results are available. * Clients **MUST** treat a missing `nextCursor` as the end of results * Clients **MUST** treat cursors as opaque tokens — do not parse, modify, or persist them * Agents **SHOULD** return an error if the cursor is invalid * Agents **SHOULD** enforce reasonable page sizes internally [​](https://agentclientprotocol.com/protocol/session-list#updating-session-metadata) Updating Session Metadata ----------------------------------------------------------------------------------------------------------------- Agents can update session metadata in real-time by sending a `session_info_update` notification via `session/update`. This follows the same pattern as other session notifications like [`available_commands_update`](https://agentclientprotocol.com/protocol/slash-commands) and [`current_mode_update`](https://agentclientprotocol.com/protocol/session-modes) . { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Implement user authentication", "_meta": { "tags": ["feature", "auth"], "priority": "high" } } } } All fields are optional. Only include fields that have changed — omitted fields are left unchanged. [​](https://agentclientprotocol.com/protocol/session-list#param-title-1) title string | null Human-readable title for the session. Set to `null` to clear. [​](https://agentclientprotocol.com/protocol/session-list#param-updated-at-1) updatedAt string | null ISO 8601 timestamp of last activity. Set to `null` to clear. [​](https://agentclientprotocol.com/protocol/session-list#param-meta-1) \_meta object Agent-specific metadata. See [Extensibility](https://agentclientprotocol.com/protocol/extensibility) . The `sessionId` and `cwd` fields are **not** included in the update — `sessionId` is already in the notification’s `params`, and `cwd` is immutable (set during [`session/new`](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) ). Agents typically send this notification after the first meaningful exchange to auto-generate a title. [​](https://agentclientprotocol.com/protocol/session-list#interaction-with-other-session-methods) Interaction with Other Session Methods ------------------------------------------------------------------------------------------------------------------------------------------- `session/list` is a discovery mechanism only — it does **not** restore or modify sessions: 1. Client calls `session/list` to discover available sessions 2. User selects a session from the list 3. Client calls [`session/load`](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) with the chosen `sessionId` to resume the conversation Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/session-setup) [Prompt TurnUnderstanding the core conversation flow\ \ Next](https://agentclientprotocol.com/protocol/prompt-turn) ⌘I On this page * [Checking Support](https://agentclientprotocol.com/protocol/session-list#checking-support) * [Listing Sessions](https://agentclientprotocol.com/protocol/session-list#listing-sessions) * [Pagination](https://agentclientprotocol.com/protocol/session-list#pagination) * [Updating Session Metadata](https://agentclientprotocol.com/protocol/session-list#updating-session-metadata) * [Interaction with Other Session Methods](https://agentclientprotocol.com/protocol/session-list#interaction-with-other-session-methods) --- # Session Modes - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/session-modes#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Session Modes [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) You can now use [Session Config Options](https://agentclientprotocol.com/protocol/session-config-options) . Dedicated session mode methods will be removed in a future version of the protocol. Until then, you can offer both to clients for backwards compatibility. Agents can provide a set of modes they can operate in. Modes often affect the system prompts used, the availability of tools, and whether they request permission before running. [​](https://agentclientprotocol.com/protocol/session-modes#initial-state) Initial state ------------------------------------------------------------------------------------------ During [Session Setup](https://agentclientprotocol.com/protocol/session-setup) the Agent **MAY** return a list of modes it can operate in and the currently active mode: { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "modes": { "currentModeId": "ask", "availableModes": [\ {\ "id": "ask",\ "name": "Ask",\ "description": "Request permission before making any changes"\ },\ {\ "id": "architect",\ "name": "Architect",\ "description": "Design and plan software systems without implementation"\ },\ {\ "id": "code",\ "name": "Code",\ "description": "Write and modify code with full tool access"\ }\ ] } } } [​](https://agentclientprotocol.com/protocol/session-modes#param-modes) modes SessionModeState The current mode state for the session ### [​](https://agentclientprotocol.com/protocol/session-modes#sessionmodestate) SessionModeState [​](https://agentclientprotocol.com/protocol/session-modes#param-current-mode-id) currentModeId SessionModeId required The ID of the mode that is currently active [​](https://agentclientprotocol.com/protocol/session-modes#param-available-modes) availableModes SessionMode\[\] required The set of modes that the Agent can operate in ### [​](https://agentclientprotocol.com/protocol/session-modes#sessionmode) SessionMode [​](https://agentclientprotocol.com/protocol/session-modes#param-id) id SessionModeId required Unique identifier for this mode [​](https://agentclientprotocol.com/protocol/session-modes#param-name) name string required Human-readable name of the mode [​](https://agentclientprotocol.com/protocol/session-modes#param-description) description string Optional description providing more details about what this mode does [​](https://agentclientprotocol.com/protocol/session-modes#setting-the-current-mode) Setting the current mode ---------------------------------------------------------------------------------------------------------------- The current mode can be changed at any point during a session, whether the Agent is idle or generating a response. ### [​](https://agentclientprotocol.com/protocol/session-modes#from-the-client) From the Client Typically, Clients display the available modes to the user and allow them to change the current one, which they can do by calling the [`session/set_mode`](https://agentclientprotocol.com/protocol/schema#session%2Fset-mode) method. { "jsonrpc": "2.0", "id": 2, "method": "session/set_mode", "params": { "sessionId": "sess_abc123def456", "modeId": "code" } } [​](https://agentclientprotocol.com/protocol/session-modes#param-session-id) sessionId SessionId required The ID of the session to set the mode for [​](https://agentclientprotocol.com/protocol/session-modes#param-mode-id) modeId SessionModeId required The ID of the mode to switch to. Must be one of the modes listed in `availableModes` ### [​](https://agentclientprotocol.com/protocol/session-modes#from-the-agent) From the Agent The Agent can also change its own mode and let the Client know by sending the `current_mode_update` session notification: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "current_mode_update", "modeId": "code" } } } #### [​](https://agentclientprotocol.com/protocol/session-modes#exiting-plan-modes) Exiting plan modes A common case where an Agent might switch modes is from within a special “exit mode” tool that can be provided to the language model during plan/architect modes. The language model can call this tool when it determines it’s ready to start implementing a solution. This “switch mode” tool will usually request permission before running, which it can do just like any other tool: { "jsonrpc": "2.0", "id": 3, "method": "session/request_permission", "params": { "sessionId": "sess_abc123def456", "toolCall": { "toolCallId": "call_switch_mode_001", "title": "Ready for implementation", "kind": "switch_mode", "status": "pending", "content": [\ {\ "type": "text",\ "text": "## Implementation Plan..."\ }\ ] }, "options": [\ {\ "optionId": "code",\ "name": "Yes, and auto-accept all actions",\ "kind": "allow_always"\ },\ {\ "optionId": "ask",\ "name": "Yes, and manually accept actions",\ "kind": "allow_once"\ },\ {\ "optionId": "reject",\ "name": "No, stay in architect mode",\ "kind": "reject_once"\ }\ ] } } When an option is chosen, the tool runs, setting the mode and sending the `current_mode_update` notification mentioned above. Learn more about permission requests Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/agent-plan) [Session Config OptionsFlexible configuration selectors for agent sessions\ \ Next](https://agentclientprotocol.com/protocol/session-config-options) ⌘I On this page * [Initial state](https://agentclientprotocol.com/protocol/session-modes#initial-state) * [SessionModeState](https://agentclientprotocol.com/protocol/session-modes#sessionmodestate) * [SessionMode](https://agentclientprotocol.com/protocol/session-modes#sessionmode) * [Setting the current mode](https://agentclientprotocol.com/protocol/session-modes#setting-the-current-mode) * [From the Client](https://agentclientprotocol.com/protocol/session-modes#from-the-client) * [From the Agent](https://agentclientprotocol.com/protocol/session-modes#from-the-agent) * [Exiting plan modes](https://agentclientprotocol.com/protocol/session-modes#exiting-plan-modes) --- # Transports - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/transports#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Transports [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) ACP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded. The protocol currently defines the following transport mechanisms for agent-client communication: 1. [stdio](https://agentclientprotocol.com/protocol/transports#stdio) , communication over standard in and standard out 2. _[Streamable HTTP](https://agentclientprotocol.com/protocol/transports#streamable-http) (draft proposal in progress)_ Agents and clients **SHOULD** support stdio whenever possible. It is also possible for agents and clients to implement [custom transports](https://agentclientprotocol.com/protocol/transports#custom-transports) . [​](https://agentclientprotocol.com/protocol/transports#stdio) stdio ----------------------------------------------------------------------- In the **stdio** transport: * The client launches the agent as a subprocess. * The agent reads JSON-RPC messages from its standard input (`stdin`) and sends messages to its standard output (`stdout`). * Messages are individual JSON-RPC requests, notifications, or responses. * Messages are delimited by newlines (`\n`), and **MUST NOT** contain embedded newlines. * The agent **MAY** write UTF-8 strings to its standard error (`stderr`) for logging purposes. Clients **MAY** capture, forward, or ignore this logging. * The agent **MUST NOT** write anything to its `stdout` that is not a valid ACP message. * The client **MUST NOT** write anything to the agent’s `stdin` that is not a valid ACP message. [​](https://agentclientprotocol.com/protocol/transports#streamable-http) _Streamable HTTP_ --------------------------------------------------------------------------------------------- _In discussion, draft proposal in progress._ [​](https://agentclientprotocol.com/protocol/transports#custom-transports) Custom Transports ----------------------------------------------------------------------------------------------- Agents and clients **MAY** implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange. Implementers who choose to support custom transports **MUST** ensure they preserve the JSON-RPC message format and lifecycle requirements defined by ACP. Custom transports **SHOULD** document their specific connection establishment and message exchange patterns to aid interoperability. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/extensibility) [SchemaSchema definitions for the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/protocol/schema) ⌘I On this page * [stdio](https://agentclientprotocol.com/protocol/transports#stdio) * [Streamable HTTP](https://agentclientprotocol.com/protocol/transports#streamable-http) * [Custom Transports](https://agentclientprotocol.com/protocol/transports#custom-transports) --- # Terminals - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/terminals#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Terminals [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) The terminal methods allow Agents to execute shell commands within the Client’s environment. These methods enable Agents to run build processes, execute scripts, and interact with command-line tools while providing real-time output streaming and process control. [​](https://agentclientprotocol.com/protocol/terminals#checking-support) Checking Support -------------------------------------------------------------------------------------------- Before attempting to use terminal methods, Agents **MUST** verify that the Client supports this capability by checking the [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities) field in the `initialize` response: { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "clientCapabilities": { "terminal": true } } } If `terminal` is `false` or not present, the Agent **MUST NOT** attempt to call any terminal methods. [​](https://agentclientprotocol.com/protocol/terminals#executing-commands) Executing Commands ------------------------------------------------------------------------------------------------ The `terminal/create` method starts a command in a new terminal: { "jsonrpc": "2.0", "id": 5, "method": "terminal/create", "params": { "sessionId": "sess_abc123def456", "command": "npm", "args": ["test", "--coverage"], "env": [\ {\ "name": "NODE_ENV",\ "value": "test"\ }\ ], "cwd": "/home/user/project", "outputByteLimit": 1048576 } } [​](https://agentclientprotocol.com/protocol/terminals#param-session-id) sessionId SessionId required The [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) for this request [​](https://agentclientprotocol.com/protocol/terminals#param-command) command string required The command to execute [​](https://agentclientprotocol.com/protocol/terminals#param-args) args string\[\] Array of command arguments [​](https://agentclientprotocol.com/protocol/terminals#param-env) env EnvVariable\[\] Environment variables for the command.Each variable has: * `name`: The environment variable name * `value`: The environment variable value [​](https://agentclientprotocol.com/protocol/terminals#param-cwd) cwd string Working directory for the command (absolute path) [​](https://agentclientprotocol.com/protocol/terminals#param-output-byte-limit) outputByteLimit number Maximum number of output bytes to retain. Once exceeded, earlier output is truncated to stay within this limit.When the limit is exceeded, the Client truncates from the beginning of the output to stay within the limit.The Client **MUST** ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit. The Client returns a Terminal ID immediately without waiting for completion: { "jsonrpc": "2.0", "id": 5, "result": { "terminalId": "term_xyz789" } } This allows the command to run in the background while the Agent performs other operations. After creating the terminal, the Agent can use the `terminal/wait_for_exit` method to wait for the command to complete. The Agent **MUST** release the terminal using `terminal/release` when it’s no longer needed. [​](https://agentclientprotocol.com/protocol/terminals#embedding-in-tool-calls) Embedding in Tool Calls ---------------------------------------------------------------------------------------------------------- Terminals can be embedded directly in [tool calls](https://agentclientprotocol.com/protocol/tool-calls) to provide real-time output to users: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call", "toolCallId": "call_002", "title": "Running tests", "kind": "execute", "status": "in_progress", "content": [\ {\ "type": "terminal",\ "terminalId": "term_xyz789"\ }\ ] } } } When a terminal is embedded in a tool call, the Client displays live output as it’s generated and continues to display it even after the terminal is released. [​](https://agentclientprotocol.com/protocol/terminals#getting-output) Getting Output ---------------------------------------------------------------------------------------- The `terminal/output` method retrieves the current terminal output without waiting for the command to complete: { "jsonrpc": "2.0", "id": 6, "method": "terminal/output", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } The Client responds with the current output and exit status (if the command has finished): { "jsonrpc": "2.0", "id": 6, "result": { "output": "Running tests...\n✓ All tests passed (42 total)\n", "truncated": false, "exitStatus": { "exitCode": 0, "signal": null } } } [​](https://agentclientprotocol.com/protocol/terminals#param-output) output string required The terminal output captured so far [​](https://agentclientprotocol.com/protocol/terminals#param-truncated) truncated boolean required Whether the output was truncated due to byte limits [​](https://agentclientprotocol.com/protocol/terminals#param-exit-status) exitStatus TerminalExitStatus Present only if the command has exited. Contains: * `exitCode`: The process exit code (may be null) * `signal`: The signal that terminated the process (may be null) [​](https://agentclientprotocol.com/protocol/terminals#waiting-for-exit) Waiting for Exit -------------------------------------------------------------------------------------------- The `terminal/wait_for_exit` method returns once the command completes: { "jsonrpc": "2.0", "id": 7, "method": "terminal/wait_for_exit", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } The Client responds once the command exits: { "jsonrpc": "2.0", "id": 7, "result": { "exitCode": 0, "signal": null } } [​](https://agentclientprotocol.com/protocol/terminals#param-exit-code) exitCode number The process exit code (may be null if terminated by signal) [​](https://agentclientprotocol.com/protocol/terminals#param-signal) signal string The signal that terminated the process (may be null if exited normally) [​](https://agentclientprotocol.com/protocol/terminals#killing-commands) Killing Commands -------------------------------------------------------------------------------------------- The `terminal/kill` method terminates a command without releasing the terminal: { "jsonrpc": "2.0", "id": 8, "method": "terminal/kill", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } After killing a command, the terminal remains valid and can be used with: * `terminal/output` to get the final output * `terminal/wait_for_exit` to get the exit status The Agent **MUST** still call `terminal/release` when it’s done using it. ### [​](https://agentclientprotocol.com/protocol/terminals#building-a-timeout) Building a Timeout Agents can implement command timeouts by combining terminal methods: 1. Create a terminal with `terminal/create` 2. Start a timer for the desired timeout duration 3. Concurrently wait for either the timer to expire or `terminal/wait_for_exit` to return 4. If the timer expires first: * Call `terminal/kill` to terminate the command * Call `terminal/output` to retrieve any final output * Include the output in the response to the model 5. Call `terminal/release` when done [​](https://agentclientprotocol.com/protocol/terminals#releasing-terminals) Releasing Terminals -------------------------------------------------------------------------------------------------- The `terminal/release` kills the command if still running and releases all resources: { "jsonrpc": "2.0", "id": 9, "method": "terminal/release", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } After release the terminal ID becomes invalid for all other `terminal/*` methods. If the terminal was added to a tool call, the client **SHOULD** continue to display its output after release. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/file-system) [Agent PlanHow Agents communicate their execution plans\ \ Next](https://agentclientprotocol.com/protocol/agent-plan) ⌘I On this page * [Checking Support](https://agentclientprotocol.com/protocol/terminals#checking-support) * [Executing Commands](https://agentclientprotocol.com/protocol/terminals#executing-commands) * [Embedding in Tool Calls](https://agentclientprotocol.com/protocol/terminals#embedding-in-tool-calls) * [Getting Output](https://agentclientprotocol.com/protocol/terminals#getting-output) * [Waiting for Exit](https://agentclientprotocol.com/protocol/terminals#waiting-for-exit) * [Killing Commands](https://agentclientprotocol.com/protocol/terminals#killing-commands) * [Building a Timeout](https://agentclientprotocol.com/protocol/terminals#building-a-timeout) * [Releasing Terminals](https://agentclientprotocol.com/protocol/terminals#releasing-terminals) --- # Prompt Turn - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/prompt-turn#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Prompt Turn [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) A prompt turn represents a complete interaction cycle between the [Client](https://agentclientprotocol.com/protocol/overview#client) and [Agent](https://agentclientprotocol.com/protocol/overview#agent) , starting with a user message and continuing until the Agent completes its response. This may involve multiple exchanges with the language model and tool invocations. Before sending prompts, Clients **MUST** first complete the [initialization](https://agentclientprotocol.com/protocol/initialization) phase and [session setup](https://agentclientprotocol.com/protocol/session-setup) . [​](https://agentclientprotocol.com/protocol/prompt-turn#the-prompt-turn-lifecycle) The Prompt Turn Lifecycle ---------------------------------------------------------------------------------------------------------------- A prompt turn follows a structured flow that enables rich interactions between the user, Agent, and any connected tools. ### [​](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message) 1\. User Message The turn begins when the Client sends a `session/prompt`: { "jsonrpc": "2.0", "id": 2, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [\ {\ "type": "text",\ "text": "Can you analyze this code for potential issues?"\ },\ {\ "type": "resource",\ "resource": {\ "uri": "file:///home/user/project/main.py",\ "mimeType": "text/x-python",\ "text": "def process_data(items):\n for item in items:\n print(item)"\ }\ }\ ] } } [​](https://agentclientprotocol.com/protocol/prompt-turn#param-session-id) sessionId SessionId The [ID](https://agentclientprotocol.com/protocol/session-setup#session-id) of the session to send this message to. [​](https://agentclientprotocol.com/protocol/prompt-turn#param-prompt) prompt ContentBlock\[\] The contents of the user message, e.g. text, images, files, etc.Clients **MUST** restrict types of content according to the [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities) established during [initialization](https://agentclientprotocol.com/protocol/initialization) . Learn more about Content ### [​](https://agentclientprotocol.com/protocol/prompt-turn#2-agent-processing) 2\. Agent Processing Upon receiving the prompt request, the Agent processes the user’s message and sends it to the language model, which **MAY** respond with text content, tool calls, or both. ### [​](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) 3\. Agent Reports Output The Agent reports the model’s output to the Client via `session/update` notifications. This may include the Agent’s plan for accomplishing the task: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "plan", "entries": [\ {\ "content": "Check for syntax errors",\ "priority": "high",\ "status": "pending"\ },\ {\ "content": "Identify potential type issues",\ "priority": "medium",\ "status": "pending"\ },\ {\ "content": "Review error handling patterns",\ "priority": "medium",\ "status": "pending"\ },\ {\ "content": "Suggest improvements",\ "priority": "low",\ "status": "pending"\ }\ ] } } } See all 32 lines Learn more about Agent Plans The Agent then reports text responses from the model: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "I'll analyze your code for potential issues. Let me examine it..." } } } } If the model requested tool calls, these are also reported immediately: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call", "toolCallId": "call_001", "title": "Analyzing Python code", "kind": "other", "status": "pending" } } } ### [​](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion) 4\. Check for Completion If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`: { "jsonrpc": "2.0", "id": 2, "result": { "stopReason": "end_turn" } } Agents **MAY** stop the turn at any point by returning the corresponding [`StopReason`](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons) . ### [​](https://agentclientprotocol.com/protocol/prompt-turn#5-tool-invocation-and-status-reporting) 5\. Tool Invocation and Status Reporting Before proceeding with execution, the Agent **MAY** request permission from the Client via the `session/request_permission` method. Once permission is granted (if required), the Agent **SHOULD** invoke the tool and report a status update marking the tool as `in_progress`: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "in_progress" } } } As the tool runs, the Agent **MAY** send additional updates, providing real-time feedback about tool execution progress. While tools execute on the Agent, they **MAY** leverage Client capabilities such as the file system (`fs`) methods to access resources within the Client’s environment. When the tool completes, the Agent sends another update with the final status and any content: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "completed", "content": [\ {\ "type": "content",\ "content": {\ "type": "text",\ "text": "Analysis complete:\n- No syntax errors found\n- Consider adding type hints for better clarity\n- The function could benefit from error handling for empty lists"\ }\ }\ ] } } } Learn more about Tool Calls ### [​](https://agentclientprotocol.com/protocol/prompt-turn#6-continue-conversation) 6\. Continue Conversation The Agent sends the tool results back to the language model as another request. The cycle returns to [step 2](https://agentclientprotocol.com/protocol/prompt-turn#2-agent-processing) , continuing until the language model completes its response without requesting additional tool calls or the turn gets stopped by the Agent or cancelled by the Client. [​](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons) Stop Reasons -------------------------------------------------------------------------------------- When an Agent stops a turn, it must specify the corresponding `StopReason`: [​](https://agentclientprotocol.com/protocol/prompt-turn#param-end-turn) end\_turn The language model finishes responding without requesting more tools [​](https://agentclientprotocol.com/protocol/prompt-turn#param-max-tokens) max\_tokens The maximum token limit is reached [​](https://agentclientprotocol.com/protocol/prompt-turn#param-max-turn-requests) max\_turn\_requests The maximum number of model requests in a single turn is exceeded [​](https://agentclientprotocol.com/protocol/prompt-turn#param-refusal) refusal The Agent refuses to continue [​](https://agentclientprotocol.com/protocol/prompt-turn#param-cancelled) cancelled The Client cancels the turn [​](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) Cancellation -------------------------------------------------------------------------------------- Clients **MAY** cancel an ongoing prompt turn at any time by sending a `session/cancel` notification: { "jsonrpc": "2.0", "method": "session/cancel", "params": { "sessionId": "sess_abc123def456" } } The Client **SHOULD** preemptively mark all non-finished tool calls pertaining to the current turn as `cancelled` as soon as it sends the `session/cancel` notification. The Client **MUST** respond to all pending `session/request_permission` requests with the `cancelled` outcome. When the Agent receives this notification, it **SHOULD** stop all language model requests and all tool call invocations as soon as possible. After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent **MUST** respond to the original `session/prompt` request with the `cancelled` [stop reason](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons) . API client libraries and tools often throw an exception when their operation is aborted, which may propagate as an error response to `session/prompt`.Clients often display unrecognized errors from the Agent to the user, which would be undesirable for cancellations as they aren’t considered errors.Agents **MUST** catch these errors and return the semantically meaningful `cancelled` stop reason, so that Clients can reliably confirm the cancellation. The Agent **MAY** send `session/update` notifications with content or tool call updates after receiving the `session/cancel` notification, but it **MUST** ensure that it does so before responding to the `session/prompt` request. The Client **SHOULD** still accept tool call updates received after sending `session/cancel`. * * * Once a prompt turn completes, the Client may send another `session/prompt` to continue the conversation, building on the context established in previous turns. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/session-list) [ContentUnderstanding content blocks in the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/protocol/content) ⌘I On this page * [The Prompt Turn Lifecycle](https://agentclientprotocol.com/protocol/prompt-turn#the-prompt-turn-lifecycle) * [1\. User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message) * [2\. Agent Processing](https://agentclientprotocol.com/protocol/prompt-turn#2-agent-processing) * [3\. Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) * [4\. Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion) * [5\. Tool Invocation and Status Reporting](https://agentclientprotocol.com/protocol/prompt-turn#5-tool-invocation-and-status-reporting) * [6\. Continue Conversation](https://agentclientprotocol.com/protocol/prompt-turn#6-continue-conversation) * [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons) * [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) --- # Session Config Options - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/session-config-options#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Session Config Options [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Agents can provide an arbitrary list of configuration options for a session, allowing Clients to offer users customizable selectors for things like models, modes, reasoning levels, and more. Session Config Options are the preferred way to expose session-level configuration. If an Agent provides `configOptions`, Clients **SHOULD** use them instead of the [`modes`](https://agentclientprotocol.com/protocol/session-modes) field. Modes will be removed in a future version of the protocol. [​](https://agentclientprotocol.com/protocol/session-config-options#initial-state) Initial State --------------------------------------------------------------------------------------------------- During [Session Setup](https://agentclientprotocol.com/protocol/session-setup) the Agent **MAY** return a list of configuration options and their current values: { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "configOptions": [\ {\ "id": "mode",\ "name": "Session Mode",\ "description": "Controls how the agent requests permission",\ "category": "mode",\ "type": "select",\ "currentValue": "ask",\ "options": [\ {\ "value": "ask",\ "name": "Ask",\ "description": "Request permission before making any changes"\ },\ {\ "value": "code",\ "name": "Code",\ "description": "Write and modify code with full tool access"\ }\ ]\ },\ {\ "id": "model",\ "name": "Model",\ "category": "model",\ "type": "select",\ "currentValue": "model-1",\ "options": [\ {\ "value": "model-1",\ "name": "Model 1",\ "description": "The fastest model"\ },\ {\ "value": "model-2",\ "name": "Model 2",\ "description": "The most powerful model"\ }\ ]\ }\ ] } } [​](https://agentclientprotocol.com/protocol/session-config-options#param-config-options) configOptions ConfigOption\[\] The list of configuration options available for this session. The order of this array represents the Agent’s preferred priority. Clients **SHOULD** respect this ordering when displaying options. ### [​](https://agentclientprotocol.com/protocol/session-config-options#configoption) ConfigOption [​](https://agentclientprotocol.com/protocol/session-config-options#param-id) id string required Unique identifier for this configuration option. Used when setting values. [​](https://agentclientprotocol.com/protocol/session-config-options#param-name) name string required Human-readable label for the option [​](https://agentclientprotocol.com/protocol/session-config-options#param-description) description string Optional description providing more details about what this option controls [​](https://agentclientprotocol.com/protocol/session-config-options#param-category) category ConfigOptionCategory Optional [semantic category](https://agentclientprotocol.com/protocol/session-config-options#option-categories) to help Clients provide consistent UX. [​](https://agentclientprotocol.com/protocol/session-config-options#param-type) type ConfigOptionType required The type of input control. Currently only `select` is supported. [​](https://agentclientprotocol.com/protocol/session-config-options#param-current-value) currentValue string required The currently selected value for this option [​](https://agentclientprotocol.com/protocol/session-config-options#param-options) options ConfigOptionValue\[\] required The available values for this option ### [​](https://agentclientprotocol.com/protocol/session-config-options#configoptionvalue) ConfigOptionValue [​](https://agentclientprotocol.com/protocol/session-config-options#param-value) value string required The value identifier used when setting this option [​](https://agentclientprotocol.com/protocol/session-config-options#param-name-1) name string required Human-readable name to display [​](https://agentclientprotocol.com/protocol/session-config-options#param-description-1) description string Optional description of what this value does [​](https://agentclientprotocol.com/protocol/session-config-options#option-categories) Option Categories ----------------------------------------------------------------------------------------------------------- Each config option **MAY** include a `category` field. Categories are semantic metadata intended to help Clients provide consistent UX, such as attaching keyboard shortcuts, choosing icons, or deciding placement. Categories are for UX purposes only and **MUST NOT** be required for correctness. Clients **MUST** handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use (e.g., `_my_custom_category`). Category names that do not begin with `_` are reserved for the ACP spec. | Category | Description | | --- | --- | | `mode` | Session mode selector | | `model` | Model selector | | `thought_level` | Thought/reasoning level selector | When multiple options share the same category, Clients **SHOULD** use the array ordering to resolve ties, preferring earlier options in the list for prominent placement or keyboard shortcuts. [​](https://agentclientprotocol.com/protocol/session-config-options#option-ordering) Option Ordering ------------------------------------------------------------------------------------------------------- The order of the `configOptions` array is significant. Agents **SHOULD** place higher-priority options first in the list. Clients **SHOULD**: * Display options in the order provided by the Agent * Use ordering to resolve ties when multiple options share the same category * If displaying a limited number of options, prefer those at the beginning of the list [​](https://agentclientprotocol.com/protocol/session-config-options#default-values-and-graceful-degradation) Default Values and Graceful Degradation ------------------------------------------------------------------------------------------------------------------------------------------------------- Agents **MUST** always provide a default value for every configuration option. This ensures the Agent can operate correctly even if: * The Client doesn’t support configuration options * The Client chooses not to display certain options * The Client receives an option type it doesn’t recognize If a Client receives an option with an unrecognized `type`, it **SHOULD** ignore that option. The Agent will continue using its default value. [​](https://agentclientprotocol.com/protocol/session-config-options#setting-a-config-option) Setting a Config Option ----------------------------------------------------------------------------------------------------------------------- The current value of a config option can be changed at any point during a session, whether the Agent is idle or generating a response. ### [​](https://agentclientprotocol.com/protocol/session-config-options#from-the-client) From the Client Clients can change a config option value by calling the `session/set_config_option` method: { "jsonrpc": "2.0", "id": 2, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123def456", "configId": "mode", "value": "code" } } [​](https://agentclientprotocol.com/protocol/session-config-options#param-session-id) sessionId SessionId required The ID of the session [​](https://agentclientprotocol.com/protocol/session-config-options#param-config-id) configId string required The `id` of the configuration option to change [​](https://agentclientprotocol.com/protocol/session-config-options#param-value-1) value string required The new value to set. Must be one of the values listed in the option’s `options` array. The Agent **MUST** respond with the complete list of all configuration options and their current values: { "jsonrpc": "2.0", "id": 2, "result": { "configOptions": [\ {\ "id": "mode",\ "name": "Session Mode",\ "type": "select",\ "currentValue": "code",\ "options": [...]\ },\ {\ "id": "model",\ "name": "Model",\ "type": "select",\ "currentValue": "model-1",\ "options": [...]\ }\ ] } } The response always contains the **complete** configuration state. This allows Agents to reflect dependent changes. For example, if changing the model affects available reasoning options, or if an option’s available values change based on another selection. ### [​](https://agentclientprotocol.com/protocol/session-config-options#from-the-agent) From the Agent The Agent can also change configuration options and notify the Client by sending a `config_option_update` session notification: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "config_option_update", "configOptions": [\ {\ "id": "mode",\ "name": "Session Mode",\ "type": "select",\ "currentValue": "code",\ "options": [...]\ },\ {\ "id": "model",\ "name": "Model",\ "type": "select",\ "currentValue": "model-2",\ "options": [...]\ }\ ] } } } This notification also contains the complete configuration state. Common reasons an Agent might update configuration options include: * Switching modes after completing a planning phase * Falling back to a different model due to rate limits or errors * Adjusting available options based on context discovered during execution [​](https://agentclientprotocol.com/protocol/session-config-options#relationship-to-session-modes) Relationship to Session Modes ----------------------------------------------------------------------------------------------------------------------------------- Session Config Options supersede the older [Session Modes](https://agentclientprotocol.com/protocol/session-modes) API. However, during the transition period, Agents that provide mode-like configuration **SHOULD** send both: * `configOptions` with a `category: "mode"` option for Clients that support config options * `modes` for Clients that only support the older API If an Agent provides both `configOptions` and `modes` in the session response: * Clients that support config options **SHOULD** use `configOptions` exclusively and ignore `modes` * Clients that don’t support config options **SHOULD** fall back to `modes` * Agents **SHOULD** keep both in sync to ensure consistent behavior regardless of which field the Client uses Learn about the Session Modes API Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/session-modes) [Slash CommandsAdvertise available slash commands to clients\ \ Next](https://agentclientprotocol.com/protocol/slash-commands) ⌘I On this page * [Initial State](https://agentclientprotocol.com/protocol/session-config-options#initial-state) * [ConfigOption](https://agentclientprotocol.com/protocol/session-config-options#configoption) * [ConfigOptionValue](https://agentclientprotocol.com/protocol/session-config-options#configoptionvalue) * [Option Categories](https://agentclientprotocol.com/protocol/session-config-options#option-categories) * [Option Ordering](https://agentclientprotocol.com/protocol/session-config-options#option-ordering) * [Default Values and Graceful Degradation](https://agentclientprotocol.com/protocol/session-config-options#default-values-and-graceful-degradation) * [Setting a Config Option](https://agentclientprotocol.com/protocol/session-config-options#setting-a-config-option) * [From the Client](https://agentclientprotocol.com/protocol/session-config-options#from-the-client) * [From the Agent](https://agentclientprotocol.com/protocol/session-config-options#from-the-agent) * [Relationship to Session Modes](https://agentclientprotocol.com/protocol/session-config-options#relationship-to-session-modes) --- # Introduce RFD Process - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/introduce-rfd-process#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Completed Introduce RFD Process [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------------------ > What are you proposing to change? Bullet points welcome. Introduce a “Request for Dialog” (RFD) process to replace ad-hoc design discussions with structured, community-friendly design documents that track features from conception to completion. [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#status-quo) Status quo ---------------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? Currently all development is being done primarily by the Zed team tracking requests and proposals from multiple teams. The goal is to create a process that helps to keep files organized and which can scale to participation by an emerging community. [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#shiny-future) Shiny future -------------------------------------------------------------------------------------------- > How will things will play out once this feature exists? ### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#project-licensing) Project licensing All code and RFDs are licensed under an Apache 2.0 license. The project is intended to remain open source and freely available in perpetuity. ### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#decision-making) Decision making For the initial phase, the project shall have a “design team” that consists of the Zed team acting in “BDFL” capacity. The expectation is that the project will setup a more structure governance structure as it grows. The design team makes all decisions regarding RFDs and sets overall project direction. ### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#rfd-lifecycle) RFD lifecycle #### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#rfds-are-proposed-by-opening-a-pr) RFDs are proposed by opening a PR An RFD begins as a PR adding a new file into the “Draft” section. The RFD can start minimal - just an elevator pitch and status quo are enough to begin dialog. Pull requests become the discussion forum where ideas get refined through collaborative iteration. As discussion proceeds, the FAQ of the RFD should be extended. If discussion has been going long enough, the PR should be closed, feedback summarized, and then re-opened with a link to the original PR. #### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#the-pr-is-merged-into-%E2%80%9Cdraft%E2%80%9D-once-a-core-team-member-decides-to-champion-it) The PR is merged into “draft” once a core team member decides to champion it RFD proposals are merged into the “draft” section if a core team member decides to champion them. The champion is then the point-of-contact for that proposal going forward and they will work with the proposal authors and others to make it reality. Core team members do not need to seek consensus to merge a proposal into the draft, but they should listen carefully to concerns from other core team members, as it will be difficult to move the RFD forward if those concerns are not ultimately addressed. Once a proposal is moved to draft, code and implementation may begin to land into the PR. This work needs to be properly feature gated and marked with the name of the RFD. Further discussion on the RFD can take place on [Zulip](https://agentclientprotocol.zulipchat.com/) if needed. #### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#moving-to-the-%E2%80%9Cpreview%E2%80%9D-section) Moving to the “preview” section Once the champion feels the RFD is ready for others to check it out, they can open a PR to move the file to the preview section. This is a signal to the community (and particularly other core team members) to check out the proposal and see what they think. The PR should stay open for “a few days” to give people an opportunity to leave feedback. The champion is empowered to decide whether to land the PR. As ever, all new feedback should be recorded in the FAQ section. #### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#deciding-to-accept-an-rfd) Deciding to accept an RFD When they feel the RFD is ready to be completed, the champion requests review by the team. The team can raise concerns and notes during discussion. Final decision on an RFD is made by the core team lead. #### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#implementation-of-an-rfd) Implementation of an RFD Once accepted, RFDs become living documents that track implementation progress. Status badges in design documentation link back to the relevant RFD, creating a clear connection between “why we’re building this” and “how it works.” When building code with an agent, agents should read RFDs during implementation to understand design rationale and update them with implementation progress. ### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#moderating-and-managing-rfd-discussions) Moderating and managing RFD discussions Moving RFDs between points in the cycle involve opening PRs. Those PRs will be places to hold dialog and discussion — but not the only place, we expect more detailed discussions to take place on [Zulip](https://agentclientprotocol.zulipchat.com/) or other communication channels. RFD owners and champions should actively “curate” discussions by collecting questions that come up and ensuring they are covered in the FAQ. Duplicate questions can be directed to the FAQ. If the discussion on the PR gets to the point where Github begins to hide comments, the PR should typically be closed, feedback collected, and then re-opened. [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#implementation-plan) Implementation plan ---------------------------------------------------------------------------------------------------------- > What is your implementation plan? * ✅ Create RFD infrastructure (about, TEMPLATE, navigation setup) * ✅ Establish lifecycle: Draft → Preview → Accepted → Completed * ⏳ Write RFDs for major in-progress features [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#frequently-asked-questions) Frequently asked questions ------------------------------------------------------------------------------------------------------------------------ ### [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#why-%E2%80%9Crequest-for-dialog%E2%80%9D-and-not-%E2%80%9Crequest-for-comment%E2%80%9D) Why “Request for Dialog” and not “Request for Comment”? Well, partly because “dialog” emphasizes conversation and exploration rather than just collecting feedback on a predetermined design. We also shamelessly stole this process from [Niko Matsakis and the Symposium project](https://symposium-dev.github.io/symposium/rfds/index.html) (with permission) so that we could benefit from their experience. [​](https://agentclientprotocol.com/rfds/introduce-rfd-process#revision-history) Revision history ---------------------------------------------------------------------------------------------------- * 2025-10-28: Initial version, created alongside RFD infrastructure Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/session-resume) [Session Config Options\ \ Next](https://agentclientprotocol.com/rfds/session-config-options) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/introduce-rfd-process#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/introduce-rfd-process#status-quo) * [Shiny future](https://agentclientprotocol.com/rfds/introduce-rfd-process#shiny-future) * [Project licensing](https://agentclientprotocol.com/rfds/introduce-rfd-process#project-licensing) * [Decision making](https://agentclientprotocol.com/rfds/introduce-rfd-process#decision-making) * [RFD lifecycle](https://agentclientprotocol.com/rfds/introduce-rfd-process#rfd-lifecycle) * [RFDs are proposed by opening a PR](https://agentclientprotocol.com/rfds/introduce-rfd-process#rfds-are-proposed-by-opening-a-pr) * [The PR is merged into “draft” once a core team member decides to champion it](https://agentclientprotocol.com/rfds/introduce-rfd-process#the-pr-is-merged-into-%E2%80%9Cdraft%E2%80%9D-once-a-core-team-member-decides-to-champion-it) * [Moving to the “preview” section](https://agentclientprotocol.com/rfds/introduce-rfd-process#moving-to-the-%E2%80%9Cpreview%E2%80%9D-section) * [Deciding to accept an RFD](https://agentclientprotocol.com/rfds/introduce-rfd-process#deciding-to-accept-an-rfd) * [Implementation of an RFD](https://agentclientprotocol.com/rfds/introduce-rfd-process#implementation-of-an-rfd) * [Moderating and managing RFD discussions](https://agentclientprotocol.com/rfds/introduce-rfd-process#moderating-and-managing-rfd-discussions) * [Implementation plan](https://agentclientprotocol.com/rfds/introduce-rfd-process#implementation-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/introduce-rfd-process#frequently-asked-questions) * [Why “Request for Dialog” and not “Request for Comment”?](https://agentclientprotocol.com/rfds/introduce-rfd-process#why-%E2%80%9Crequest-for-dialog%E2%80%9D-and-not-%E2%80%9Crequest-for-comment%E2%80%9D) * [Revision history](https://agentclientprotocol.com/rfds/introduce-rfd-process#revision-history) --- # Represent deleted files in diff - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/diff-delete#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Represent deleted files in diff [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [anna239](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/diff-delete#elevator-pitch) Elevator pitch -------------------------------------------------------------------------------------- > What are you proposing to change? Add flag `deleted` to [Diff](https://agentclientprotocol.com/protocol/tool-calls#diffs) entity type for the case of a deleted file. [​](https://agentclientprotocol.com/rfds/diff-delete#status-quo) Status quo ------------------------------------------------------------------------------ > How do things work today and what problems does this cause? Why would we change things? Currently, in Diff entity type `newText` is not nullable, so it’s not possible to distinguish between a deleted file and empty file. [​](https://agentclientprotocol.com/rfds/diff-delete#what-we-propose-to-do-about-it) What we propose to do about it ---------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? Add flag `deleted` to [Diff](https://agentclientprotocol.com/protocol/tool-calls#diffs) entity type for the case of a deleted file. **Current structure (cannot distinguish deleted file from empty file):** { "type": "diff", "path": "/home/user/project/src/config.json", "oldText": "{\n \"debug\": false\n}", "newText": "" } **Proposed structure with `deleted` flag:** { "type": "diff", "path": "/home/user/project/src/config.json", "oldText": "{\n \"debug\": false\n}", "newText": "", "deleted": true } Note: we would ideally make newText nullable, but that would break existing clients. [​](https://agentclientprotocol.com/rfds/diff-delete#shiny-future) Shiny future ---------------------------------------------------------------------------------- > How will things will play out once this feature exists? It is possible for the agent to distinguish between a deleted file and an empty file. [​](https://agentclientprotocol.com/rfds/diff-delete#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------ > Tell me more about your implementation. What is your detailed implementation plan? Adding the new field will be a non-breaking change, and clients that update can better distinguish between deleted and empty files. [​](https://agentclientprotocol.com/rfds/diff-delete#frequently-asked-questions) Frequently asked questions -------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? **Do we need to represent moved files?** An agent could represent that with a deleted file at the old path and a new file at the new path. We need to rework the entire diff structure to handle more cases, and binary files, but in the meantime this provides a stop-gap until we can implement a more comprehensive solution. ### [​](https://agentclientprotocol.com/rfds/diff-delete#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? We considered making newText nullable, but that would break existing clients. [​](https://agentclientprotocol.com/rfds/diff-delete#revision-history) Revision history ------------------------------------------------------------------------------------------ 2026-02-20: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/message-id) [Boolean Config Option Type\ \ Next](https://agentclientprotocol.com/rfds/boolean-config-option) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/diff-delete#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/diff-delete#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/diff-delete#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/diff-delete#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/diff-delete#implementation-details-and-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/diff-delete#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/diff-delete#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/diff-delete#revision-history) --- # Tool Calls - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/tool-calls#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Tool Calls [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Tool calls represent actions that language models request Agents to perform during a [prompt turn](https://agentclientprotocol.com/protocol/prompt-turn) . When an LLM determines it needs to interact with external systems—like reading files, running code, or fetching data—it generates tool calls that the Agent executes on its behalf. Agents report tool calls through [`session/update`](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) notifications, allowing Clients to display real-time progress and results to users. While Agents handle the actual execution, they may leverage Client capabilities like [permission requests](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) or [file system access](https://agentclientprotocol.com/protocol/file-system) to provide a richer, more integrated experience. [​](https://agentclientprotocol.com/protocol/tool-calls#creating) Creating ----------------------------------------------------------------------------- When the language model requests a tool invocation, the Agent **SHOULD** report it to the Client: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call", "toolCallId": "call_001", "title": "Reading configuration file", "kind": "read", "status": "pending" } } } [​](https://agentclientprotocol.com/protocol/tool-calls#param-tool-call-id) toolCallId ToolCallId required A unique identifier for this tool call within the session [​](https://agentclientprotocol.com/protocol/tool-calls#param-title) title string required A human-readable title describing what the tool is doing [​](https://agentclientprotocol.com/protocol/tool-calls#param-kind) kind ToolKind The category of tool being invoked. Show kinds * `read` - Reading files or data - `edit` - Modifying files or content - `delete` - Removing files or data - `move` - Moving or renaming files - `search` - Searching for information - `execute` - Running commands or code - `think` - Internal reasoning or planning - `fetch` - Retrieving external data * `other` - Other tool types (default) Tool kinds help Clients choose appropriate icons and optimize how they display tool execution progress. [​](https://agentclientprotocol.com/protocol/tool-calls#param-status) status ToolCallStatus The current [execution status](https://agentclientprotocol.com/protocol/tool-calls#status) (defaults to `pending`) [​](https://agentclientprotocol.com/protocol/tool-calls#param-content) content ToolCallContent\[\] [Content produced](https://agentclientprotocol.com/protocol/tool-calls#content) by the tool call [​](https://agentclientprotocol.com/protocol/tool-calls#param-locations) locations ToolCallLocation\[\] [File locations](https://agentclientprotocol.com/protocol/tool-calls#following-the-agent) affected by this tool call [​](https://agentclientprotocol.com/protocol/tool-calls#param-raw-input) rawInput object The raw input parameters sent to the tool [​](https://agentclientprotocol.com/protocol/tool-calls#param-raw-output) rawOutput object The raw output returned by the tool [​](https://agentclientprotocol.com/protocol/tool-calls#updating) Updating ----------------------------------------------------------------------------- As tools execute, Agents send updates to report progress and results. Updates use the `session/update` notification with `tool_call_update`: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "in_progress", "content": [\ {\ "type": "content",\ "content": {\ "type": "text",\ "text": "Found 3 configuration files..."\ }\ }\ ] } } } All fields except `toolCallId` are optional in updates. Only the fields being changed need to be included. [​](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) Requesting Permission ------------------------------------------------------------------------------------------------------- The Agent **MAY** request permission from the user before executing a tool call by calling the `session/request_permission` method: { "jsonrpc": "2.0", "id": 5, "method": "session/request_permission", "params": { "sessionId": "sess_abc123def456", "toolCall": { "toolCallId": "call_001" }, "options": [\ {\ "optionId": "allow-once",\ "name": "Allow once",\ "kind": "allow_once"\ },\ {\ "optionId": "reject-once",\ "name": "Reject",\ "kind": "reject_once"\ }\ ] } } [​](https://agentclientprotocol.com/protocol/tool-calls#param-session-id) sessionId SessionId required The session ID for this request [​](https://agentclientprotocol.com/protocol/tool-calls#param-tool-call) toolCall ToolCallUpdate required The tool call update containing details about the operation [​](https://agentclientprotocol.com/protocol/tool-calls#param-options) options PermissionOption\[\] required Available [permission options](https://agentclientprotocol.com/protocol/tool-calls#permission-options) for the user to choose from The Client responds with the user’s decision: { "jsonrpc": "2.0", "id": 5, "result": { "outcome": { "outcome": "selected", "optionId": "allow-once" } } } Clients **MAY** automatically allow or reject permission requests according to the user settings. If the current prompt turn gets [cancelled](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) , the Client **MUST** respond with the `"cancelled"` outcome: { "jsonrpc": "2.0", "id": 5, "result": { "outcome": { "outcome": "cancelled" } } } [​](https://agentclientprotocol.com/protocol/tool-calls#param-outcome) outcome RequestPermissionOutcome required The user’s decision, either: - `cancelled` - The [prompt turn was cancelled](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) - `selected` with an `optionId` - The ID of the selected permission option ### [​](https://agentclientprotocol.com/protocol/tool-calls#permission-options) Permission Options Each permission option provided to the Client contains: [​](https://agentclientprotocol.com/protocol/tool-calls#param-option-id) optionId string required Unique identifier for this option [​](https://agentclientprotocol.com/protocol/tool-calls#param-name) name string required Human-readable label to display to the user [​](https://agentclientprotocol.com/protocol/tool-calls#param-kind-1) kind PermissionOptionKind required A hint to help Clients choose appropriate icons and UI treatment for each option. * `allow_once` - Allow this operation only this time * `allow_always` - Allow this operation and remember the choice * `reject_once` - Reject this operation only this time * `reject_always` - Reject this operation and remember the choice [​](https://agentclientprotocol.com/protocol/tool-calls#status) Status ------------------------------------------------------------------------- Tool calls progress through different statuses during their lifecycle: [​](https://agentclientprotocol.com/protocol/tool-calls#param-pending) pending The tool call hasn’t started running yet because the input is either streaming or awaiting approval [​](https://agentclientprotocol.com/protocol/tool-calls#param-in-progress) in\_progress The tool call is currently running [​](https://agentclientprotocol.com/protocol/tool-calls#param-completed) completed The tool call completed successfully [​](https://agentclientprotocol.com/protocol/tool-calls#param-failed) failed The tool call failed with an error [​](https://agentclientprotocol.com/protocol/tool-calls#content) Content --------------------------------------------------------------------------- Tool calls can produce different types of content: ### [​](https://agentclientprotocol.com/protocol/tool-calls#regular-content) Regular Content Standard [content blocks](https://agentclientprotocol.com/protocol/content) like text, images, or resources: { "type": "content", "content": { "type": "text", "text": "Analysis complete. Found 3 issues." } } ### [​](https://agentclientprotocol.com/protocol/tool-calls#diffs) Diffs File modifications shown as diffs: { "type": "diff", "path": "/home/user/project/src/config.json", "oldText": "{\n \"debug\": false\n}", "newText": "{\n \"debug\": true\n}" } [​](https://agentclientprotocol.com/protocol/tool-calls#param-path) path string required The absolute file path being modified [​](https://agentclientprotocol.com/protocol/tool-calls#param-old-text) oldText string The original content (null for new files) [​](https://agentclientprotocol.com/protocol/tool-calls#param-new-text) newText string required The new content after modification ### [​](https://agentclientprotocol.com/protocol/tool-calls#terminals) Terminals Live terminal output from command execution: { "type": "terminal", "terminalId": "term_xyz789" } [​](https://agentclientprotocol.com/protocol/tool-calls#param-terminal-id) terminalId string required The ID of a terminal created with `terminal/create` When a terminal is embedded in a tool call, the Client displays live output as it’s generated and continues to display it even after the terminal is released. Learn more about Terminals [​](https://agentclientprotocol.com/protocol/tool-calls#following-the-agent) Following the Agent --------------------------------------------------------------------------------------------------- Tool calls can report file locations they’re working with, enabling Clients to implement “follow-along” features that track which files the Agent is accessing or modifying in real-time. { "path": "/home/user/project/src/main.py", "line": 42 } [​](https://agentclientprotocol.com/protocol/tool-calls#param-path-1) path string required The absolute file path being accessed or modified [​](https://agentclientprotocol.com/protocol/tool-calls#param-line) line number Optional line number within the file Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/content) [File SystemClient filesystem access methods\ \ Next](https://agentclientprotocol.com/protocol/file-system) ⌘I On this page * [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating) * [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating) * [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) * [Permission Options](https://agentclientprotocol.com/protocol/tool-calls#permission-options) * [Status](https://agentclientprotocol.com/protocol/tool-calls#status) * [Content](https://agentclientprotocol.com/protocol/tool-calls#content) * [Regular Content](https://agentclientprotocol.com/protocol/tool-calls#regular-content) * [Diffs](https://agentclientprotocol.com/protocol/tool-calls#diffs) * [Terminals](https://agentclientprotocol.com/protocol/tool-calls#terminals) * [Following the Agent](https://agentclientprotocol.com/protocol/tool-calls#following-the-agent) --- # Session Setup - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/session-setup#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Session Setup [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Sessions represent a specific conversation or thread between the [Client](https://agentclientprotocol.com/protocol/overview#client) and [Agent](https://agentclientprotocol.com/protocol/overview#agent) . Each session maintains its own context, conversation history, and state, allowing multiple independent interactions with the same Agent. Before creating a session, Clients **MUST** first complete the [initialization](https://agentclientprotocol.com/protocol/initialization) phase to establish protocol compatibility and capabilities. [​](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) Creating a Session ---------------------------------------------------------------------------------------------------- Clients create a new session by calling the `session/new` method with: * The [working directory](https://agentclientprotocol.com/protocol/session-setup#working-directory) for the session * A list of [MCP servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers) the Agent should connect to { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "mcpServers": [\ {\ "name": "filesystem",\ "command": "/path/to/mcp-server",\ "args": ["--stdio"],\ "env": []\ }\ ] } } The Agent **MUST** respond with a unique [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) that identifies this conversation: { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456" } } [​](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) Loading Sessions ------------------------------------------------------------------------------------------------ Agents that support the `loadSession` capability allow Clients to resume previous conversations. This feature enables persistence across restarts and sharing sessions between different Client instances. ### [​](https://agentclientprotocol.com/protocol/session-setup#checking-support) Checking Support Before attempting to load a session, Clients **MUST** verify that the Agent supports this capability by checking the `loadSession` field in the `initialize` response: { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "loadSession": true } } } If `loadSession` is `false` or not present, the Agent does not support loading sessions and Clients **MUST NOT** attempt to call `session/load`. ### [​](https://agentclientprotocol.com/protocol/session-setup#loading-a-session) Loading a Session To load an existing session, Clients **MUST** call the `session/load` method with: * The [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) to resume * [MCP servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers) to connect to * The [working directory](https://agentclientprotocol.com/protocol/session-setup#working-directory) { "jsonrpc": "2.0", "id": 1, "method": "session/load", "params": { "sessionId": "sess_789xyz", "cwd": "/home/user/project", "mcpServers": [\ {\ "name": "filesystem",\ "command": "/path/to/mcp-server",\ "args": ["--mode", "filesystem"],\ "env": []\ }\ ] } } The Agent **MUST** replay the entire conversation to the Client in the form of `session/update` notifications (like `session/prompt`). For example, a user message from the conversation history: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "user_message_chunk", "content": { "type": "text", "text": "What's the capital of France?" } } } } Followed by the agent’s response: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "The capital of France is Paris." } } } } When **all** the conversation entries have been streamed to the Client, the Agent **MUST** respond to the original `session/load` request. { "jsonrpc": "2.0", "id": 1, "result": null } The Client can then continue sending prompts as if the session was never interrupted. [​](https://agentclientprotocol.com/protocol/session-setup#session-id) Session ID ------------------------------------------------------------------------------------ The session ID returned by `session/new` is a unique identifier for the conversation context. Clients use this ID to: * Send prompt requests via `session/prompt` * Cancel ongoing operations via `session/cancel` * Load previous sessions via `session/load` (if the Agent supports the `loadSession` capability) [​](https://agentclientprotocol.com/protocol/session-setup#working-directory) Working Directory -------------------------------------------------------------------------------------------------- The `cwd` (current working directory) parameter establishes the file system context for the session. This directory: * **MUST** be an absolute path * **MUST** be used for the session regardless of where the Agent subprocess was spawned * **SHOULD** serve as a boundary for tool operations on the file system [​](https://agentclientprotocol.com/protocol/session-setup#mcp-servers) MCP Servers -------------------------------------------------------------------------------------- The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) allows Agents to access external tools and data sources. When creating a session, Clients **MAY** include connection details for MCP servers that the Agent should connect to. MCP servers can be connected to using different transports. All Agents **MUST** support the stdio transport, while HTTP and SSE transports are optional capabilities that can be checked during initialization. While they are not required to by the spec, new Agents **SHOULD** support the HTTP transport to ensure compatibility with modern MCP servers. ### [​](https://agentclientprotocol.com/protocol/session-setup#transport-types) Transport Types #### [​](https://agentclientprotocol.com/protocol/session-setup#stdio-transport) Stdio Transport All Agents **MUST** support connecting to MCP servers via stdio (standard input/output). This is the default transport mechanism. [​](https://agentclientprotocol.com/protocol/session-setup#param-name) name string required A human-readable identifier for the server [​](https://agentclientprotocol.com/protocol/session-setup#param-command) command string required The absolute path to the MCP server executable [​](https://agentclientprotocol.com/protocol/session-setup#param-args) args array required Command-line arguments to pass to the server [​](https://agentclientprotocol.com/protocol/session-setup#param-env) env EnvVariable\[\] Environment variables to set when launching the server Show EnvVariable [​](https://agentclientprotocol.com/protocol/session-setup#param-name-1) name string The name of the environment variable. [​](https://agentclientprotocol.com/protocol/session-setup#param-value) value string The value of the environment variable. Example stdio transport configuration: { "name": "filesystem", "command": "/path/to/mcp-server", "args": ["--stdio"], "env": [\ {\ "name": "API_KEY",\ "value": "secret123"\ }\ ] } #### [​](https://agentclientprotocol.com/protocol/session-setup#http-transport) HTTP Transport When the Agent supports `mcpCapabilities.http`, Clients can specify MCP servers configurations using the HTTP transport. [​](https://agentclientprotocol.com/protocol/session-setup#param-type) type string required Must be `"http"` to indicate HTTP transport [​](https://agentclientprotocol.com/protocol/session-setup#param-name-2) name string required A human-readable identifier for the server [​](https://agentclientprotocol.com/protocol/session-setup#param-url) url string required The URL of the MCP server [​](https://agentclientprotocol.com/protocol/session-setup#param-headers) headers HttpHeader\[\] required HTTP headers to include in requests to the server Show HttpHeader [​](https://agentclientprotocol.com/protocol/session-setup#param-name-3) name string The name of the HTTP header. [​](https://agentclientprotocol.com/protocol/session-setup#param-value-1) value string The value to set for the HTTP header. Example HTTP transport configuration: { "type": "http", "name": "api-server", "url": "https://api.example.com/mcp", "headers": [\ {\ "name": "Authorization",\ "value": "Bearer token123"\ },\ {\ "name": "Content-Type",\ "value": "application/json"\ }\ ] } #### [​](https://agentclientprotocol.com/protocol/session-setup#sse-transport) SSE Transport When the Agent supports `mcpCapabilities.sse`, Clients can specify MCP servers configurations using the SSE transport. This transport was deprecated by the MCP spec. [​](https://agentclientprotocol.com/protocol/session-setup#param-type-1) type string required Must be `"sse"` to indicate SSE transport [​](https://agentclientprotocol.com/protocol/session-setup#param-name-4) name string required A human-readable identifier for the server [​](https://agentclientprotocol.com/protocol/session-setup#param-url-1) url string required The URL of the SSE endpoint [​](https://agentclientprotocol.com/protocol/session-setup#param-headers-1) headers HttpHeader\[\] required HTTP headers to include when establishing the SSE connection Show HttpHeader [​](https://agentclientprotocol.com/protocol/session-setup#param-name-5) name string The name of the HTTP header. [​](https://agentclientprotocol.com/protocol/session-setup#param-value-2) value string The value to set for the HTTP header. Example SSE transport configuration: { "type": "sse", "name": "event-stream", "url": "https://events.example.com/mcp", "headers": [\ {\ "name": "X-API-Key",\ "value": "apikey456"\ }\ ] } ### [​](https://agentclientprotocol.com/protocol/session-setup#checking-transport-support) Checking Transport Support Before using HTTP or SSE transports, Clients **MUST** verify the Agent’s capabilities during initialization: { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "mcpCapabilities": { "http": true, "sse": true } } } } If `mcpCapabilities.http` is `false` or not present, the Agent does not support HTTP transport. If `mcpCapabilities.sse` is `false` or not present, the Agent does not support SSE transport. Agents **SHOULD** connect to all MCP servers specified by the Client. Clients **MAY** use this ability to provide tools directly to the underlying language model by including their own MCP server. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/initialization) [Session ListDiscovering existing sessions\ \ Next](https://agentclientprotocol.com/protocol/session-list) ⌘I On this page * [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) * [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) * [Checking Support](https://agentclientprotocol.com/protocol/session-setup#checking-support) * [Loading a Session](https://agentclientprotocol.com/protocol/session-setup#loading-a-session) * [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) * [Working Directory](https://agentclientprotocol.com/protocol/session-setup#working-directory) * [MCP Servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers) * [Transport Types](https://agentclientprotocol.com/protocol/session-setup#transport-types) * [Stdio Transport](https://agentclientprotocol.com/protocol/session-setup#stdio-transport) * [HTTP Transport](https://agentclientprotocol.com/protocol/session-setup#http-transport) * [SSE Transport](https://agentclientprotocol.com/protocol/session-setup#sse-transport) * [Checking Transport Support](https://agentclientprotocol.com/protocol/session-setup#checking-transport-support) --- # Meta Field Propagation Conventions - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/meta-propagation#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Meta Field Propagation Conventions [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [Adrian Cole](https://github.com/codefromthecrypt) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/meta-propagation#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------------- Document `params._meta` as the convention for propagating metadata from clients to agents, such as trace identifiers or correlation IDs. This aligns with [MCP](https://modelcontextprotocol.io/) , enabling shared instrumentation since both protocols use stdio JSON-RPC transports. [​](https://agentclientprotocol.com/rfds/meta-propagation#status-quo) Status quo ----------------------------------------------------------------------------------- ACP clients already propagate context to agents via `_meta`. For example, `requestId` is used for request correlation in [AionUi](https://github.com/iOfficeAI/AionUi/blob/main/src/common/codex/types/eventData.ts#L12-L16) . However, the [extensibility](https://agentclientprotocol.com/protocol/extensibility) documentation does not specify the `_meta` type or document its use for propagation. Without documentation, parties must coordinate ad hoc, which can lead to portability accidents (such as one side using `_meta.traceparent` and the other `_meta.otel.traceparent`). Documenting that propagated fields are root keys in `_meta` prevents this. [​](https://agentclientprotocol.com/rfds/meta-propagation#what-we-propose-to-do-about-it) What we propose to do about it --------------------------------------------------------------------------------------------------------------------------- Update the [extensibility](https://agentclientprotocol.com/protocol/extensibility#the-_meta-field) documentation with two changes: 1. Add the type `{ [key: string]: unknown }` to the existing summary sentence. This type is compatible with MCP SDKs. 2. Add a new paragraph after the JSON example about propagation conventions. [​](https://agentclientprotocol.com/rfds/meta-propagation#shiny-future) Shiny future --------------------------------------------------------------------------------------- * Same instrumentation (OpenInference, etc.) works for both ACP and MCP. * Observability tools can correlate traces across protocols. [​](https://agentclientprotocol.com/rfds/meta-propagation#implementation-details) Implementation details ----------------------------------------------------------------------------------------------------------- **Change 1**: Update the existing summary sentence in [extensibility](https://agentclientprotocol.com/protocol/extensibility#the-_meta-field) : -All types in the protocol include a `_meta` field that implementations can use to attach custom information. +All types in the protocol include a `_meta` field with type `{ [key: string]: unknown }` that implementations can use to attach custom information. **Change 2**: After the JSON example, before “Implementations **MUST NOT**”, add: > Clients may propagate fields to the agent for correlation purposes, such as `requestId`. The following root-level keys in `_meta` **SHOULD** be reserved for [W3C trace context](https://www.w3.org/TR/trace-context/) > to guarantee interop with existing MCP implementations and OpenTelemetry tooling: > > * `traceparent` > * `tracestate` > * `baggage` [​](https://agentclientprotocol.com/rfds/meta-propagation#faq) FAQ --------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/meta-propagation#why-document-this-now) Why document this now? Clients already propagate context via `_meta`. Documenting prevents incompatible drift and enables shared tooling with MCP. ### [​](https://agentclientprotocol.com/rfds/meta-propagation#why-reference-mcp) Why reference MCP? ACP and MCP are the two core agentic protocols, both using stdio JSON-RPC. Where `_meta` types are compatible, instrumentation code can be abstracted and reused for both: Here are several MCP SDKs that propagate W3C trace-context in `_meta`: * [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) - native W3C trace-context propagation * [OpenInference](https://github.com/Arize-ai/openinference) - Python and TypeScript MCP instrumentation (collaboration between Arize and Elastic) * [curioswitch/mcp-go-sdk-otel](https://github.com/curioswitch/mcp-go-sdk-otel) - Go MCP instrumentation [​](https://agentclientprotocol.com/rfds/meta-propagation#revision-history) Revision history ----------------------------------------------------------------------------------------------- * 2025-12-04: Implementation in extensibility docs * 2025-11-28: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/request-cancellation) [Agent Telemetry Export\ \ Next](https://agentclientprotocol.com/rfds/agent-telemetry-export) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/meta-propagation#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/meta-propagation#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/meta-propagation#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/meta-propagation#shiny-future) * [Implementation details](https://agentclientprotocol.com/rfds/meta-propagation#implementation-details) * [FAQ](https://agentclientprotocol.com/rfds/meta-propagation#faq) * [Why document this now?](https://agentclientprotocol.com/rfds/meta-propagation#why-document-this-now) * [Why reference MCP?](https://agentclientprotocol.com/rfds/meta-propagation#why-reference-mcp) * [Revision history](https://agentclientprotocol.com/rfds/meta-propagation#revision-history) --- # Requests for Dialog (RFDs) - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/about#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Requests for Dialog (RFDs) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) A “Request for Dialog” (RFD) is ACP’s version of the RFC process. RFDs are the primary mechanism for proposing new features, collecting community input on an issue, and documenting design decisions. [​](https://agentclientprotocol.com/rfds/about#when-to-write-an-rfd) When to write an RFD -------------------------------------------------------------------------------------------- You should consider writing an RFD if you intend to make a “substantial” change to ACP or its documentation. What constitutes a “substantial” change is evolving based on community norms and varies depending on what part of the ecosystem you are proposing to change. Some changes do not require an RFD: * Rephrasing, reorganizing or refactoring * Addition or removal of warnings * Additions that strictly improve objective, numerical quality criteria (speedup, better browser support) * Fixing objectively incorrect behavior [​](https://agentclientprotocol.com/rfds/about#the-rfd-process) The RFD Process ---------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/about#1-propose-by-opening-a-pr) 1\. Propose by opening a PR [Fork the repo](https://github.com/agentclientprotocol/agent-client-protocol) and copy `docs/rfds/TEMPLATE.md` to `docs/rfds/my-feature.md` (using kebab-case naming). The RFD can start minimal - just an elevator pitch and status quo are enough to begin dialog. Pull requests become the discussion forum where ideas get refined through collaborative iteration. ### [​](https://agentclientprotocol.com/rfds/about#2-merge-to-%E2%80%9Cdraft%E2%80%9D-when-championed) 2\. Merge to “Draft” when championed RFD proposals are merged into the “Draft” section if a core team member decides to champion them. The champion becomes the point-of-contact and will work with authors to make it reality. Once in draft, implementation may begin (properly feature-gated with the RFD name). Implementation can also begin at a particular SDK or agent/client level to prove out the design for better review and feedback before broader adoption. RFDs are living documents that track implementation progress. PRs working towards an RFD will typically update it to reflect changes in design or direction. ### [​](https://agentclientprotocol.com/rfds/about#2b-move-to-%E2%80%9Cto-be-removed%E2%80%9D) 2b. Move to “To be removed” RFDs that have never landed may be closed at the discretion of a core team member. RFDs that have landed in draft form are moved to “To be removed” instead until there has been time to remove them fully from the codebase, then they are removed entirely. ### [​](https://agentclientprotocol.com/rfds/about#3-move-to-%E2%80%9Cpreview%E2%80%9D-when-fully-implemented) 3\. Move to “Preview” when fully implemented When the champion feels the RFD is ready for broader review, they open a PR to move it to “Preview.” This signals the community to provide feedback. The PR stays open for a few days before the champion decides whether to land it. ### [​](https://agentclientprotocol.com/rfds/about#4-completed) 4\. Completed Once in preview, the RFD can be moved to “completed” with a final PR. The core team should comment and express concerns, but **final decision is always made by the core team lead**. Depending on what the RFD is about, “completed” is the only state that can represent a 1-way door (if there is a stability commitment involved), as changes might require a breaking change to the protocol after this point. Preview RFDs don’t have to be completed. They may also go back to draft to await further changes or even be moved to “To be removed”. ### [​](https://agentclientprotocol.com/rfds/about#5-implementation-and-completion) 5\. Implementation and completion #### [​](https://agentclientprotocol.com/rfds/about#rfd-lifecycle) RFD Lifecycle * **Early drafts**: Initial ideas, brainstorming, early exploration * **Mature drafts**: Well-formed proposals ready for broader review * **Accepted**: Approved for implementation, may reference implementation work * **To be removed (yet?)**: Decided against for now, but preserved for future consideration * **Completed**: Implementation finished and merged [​](https://agentclientprotocol.com/rfds/about#governance) Governance ------------------------------------------------------------------------ The project currently has a design team with the [Zed team as the lead (BDFL)](https://agentclientprotocol.com/community/governance) . Champions from the core team guide RFDs through the process, but final decisions rest with the team lead. This structure maintains velocity while anticipating future governance expansion. [​](https://agentclientprotocol.com/rfds/about#discussion-and-moderation) Discussion and Moderation ------------------------------------------------------------------------------------------------------ Detailed discussions often happen on [Zulip](https://agentclientprotocol.zulipchat.com/) , with PR comments for process decisions. The results of detailed discussions should be incorporated into the relevant RFD. RFD champions actively curate discussions by collecting questions in the FAQ section. If PR discussions become too long, they should be closed, feedback summarized, and reopened with links to the original. [​](https://agentclientprotocol.com/rfds/about#licensing) Licensing ---------------------------------------------------------------------- All RFDs are licensed under Apache 2.0. The project remains open source. [​](https://agentclientprotocol.com/rfds/about#) ---------------------------------------------------- Was this page helpful? YesNo [RFD UpdatesLifecycle updates for ACP Requests for Dialog\ \ Next](https://agentclientprotocol.com/rfds/updates) ⌘I On this page * [When to write an RFD](https://agentclientprotocol.com/rfds/about#when-to-write-an-rfd) * [The RFD Process](https://agentclientprotocol.com/rfds/about#the-rfd-process) * [1\. Propose by opening a PR](https://agentclientprotocol.com/rfds/about#1-propose-by-opening-a-pr) * [2\. Merge to “Draft” when championed](https://agentclientprotocol.com/rfds/about#2-merge-to-%E2%80%9Cdraft%E2%80%9D-when-championed) * [2b. Move to “To be removed”](https://agentclientprotocol.com/rfds/about#2b-move-to-%E2%80%9Cto-be-removed%E2%80%9D) * [3\. Move to “Preview” when fully implemented](https://agentclientprotocol.com/rfds/about#3-move-to-%E2%80%9Cpreview%E2%80%9D-when-fully-implemented) * [4\. Completed](https://agentclientprotocol.com/rfds/about#4-completed) * [5\. Implementation and completion](https://agentclientprotocol.com/rfds/about#5-implementation-and-completion) * [RFD Lifecycle](https://agentclientprotocol.com/rfds/about#rfd-lifecycle) * [Governance](https://agentclientprotocol.com/rfds/about#governance) * [Discussion and Moderation](https://agentclientprotocol.com/rfds/about#discussion-and-moderation) * [Licensing](https://agentclientprotocol.com/rfds/about#licensing) * [](https://agentclientprotocol.com/rfds/about#) --- # Authentication Methods - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/auth-methods#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Authentication Methods [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [anna239](https://github.com/anna239) [​](https://agentclientprotocol.com/rfds/auth-methods#elevator-pitch) Elevator pitch --------------------------------------------------------------------------------------- > What are you proposing to change? I suggest adding more information about auth methods that agent supports, which will allow clients to draw more appropriate UI. [​](https://agentclientprotocol.com/rfds/auth-methods#status-quo) Status quo ------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? Agents have different ways of authenticating users: env vars with api keys, running a command like ` login`, some just open a browser and use oauth. [AuthMethod](https://agentclientprotocol.com/protocol/schema#authmethod) does not really tell the client what should be done to authenticate. This means we can’t show the user a control for entering key if an agent supports auth through env var. Very few agents can authenticate fully on their own without user input, so agents with ACP auth support are limited in the methods they can offer, or require manual setup before being run as an ACP agent. [​](https://agentclientprotocol.com/rfds/auth-methods#what-we-propose-to-do-about-it) What we propose to do about it ----------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? We can add addition types of AuthMethods, to provide clients with additional information so they can assist in the login process. [​](https://agentclientprotocol.com/rfds/auth-methods#shiny-future) Shiny future ----------------------------------------------------------------------------------- > How will things will play out once this feature exists? It will be easier for end-users to start using an agent from inside the IDE as auth process will be more straightforward [​](https://agentclientprotocol.com/rfds/auth-methods#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? I suggest adding following auth types: ### [​](https://agentclientprotocol.com/rfds/auth-methods#auth-method-types) Auth method types 1. Agent auth Same as what there is now – agent handles the auth itself. This is the default type when no `type` is provided, preserving backward compatibility. { "id": "123", "name": "Agent", "description": "Authenticate through agent" } An explicit `"type": "agent"` is also accepted but not required. 2. Env variable The user provides credentials that the client passes to the agent as environment variables. Requires `"type": "env_var"`. The `vars` field is an array of `AuthEnvVar` objects, each describing a single environment variable. This supports services that require multiple credentials (e.g. Azure OpenAI needs both an API key and an endpoint URL). Simple single-key example: { "id": "openai", "name": "OpenAI API Key", "type": "env_var", "vars": [{ "name": "OPENAI_API_KEY" }], "link": "https://platform.openai.com/api-keys" } Multiple variables with metadata: { "id": "azure-openai", "name": "Azure OpenAI", "type": "env_var", "vars": [\ { "name": "AZURE_OPENAI_API_KEY", "label": "API Key" },\ {\ "name": "AZURE_OPENAI_ENDPOINT",\ "label": "Endpoint URL",\ "secret": false\ },\ {\ "name": "AZURE_OPENAI_API_VERSION",\ "label": "API Version",\ "secret": false,\ "optional": true\ }\ ], "link": "https://portal.azure.com" } Fields on `AuthMethodEnvVar`: * `vars` (required): Array of `AuthEnvVar` objects. * `link` (optional): URL where the user can obtain their credentials. Fields on `AuthEnvVar`: * `name` (required): The environment variable name (e.g. `"OPENAI_API_KEY"`). * `label` (optional): Human-readable label for this variable, displayed in client UI. * `secret` (optional, default `true`): Whether this value is a secret. Clients should use a password-style input for secret vars and a plain text input otherwise. * `optional` (optional, default `false`): Whether this variable is optional. Since environment variables need to be supplied when the agent process starts, the client can check if it already passed such variables to the process, in which case the user can click on the button and the agent will read the already available values. Otherwise, when the user clicks the button, the client could restart the agent process with the desired environment variables, and then automatically send the authenticate message with the correct id to sign in for the user. 3. Terminal Auth This requires the client to be able to run an interactive terminal for the user to login via a TUI. Requires `"type": "terminal"`. { "id": "123", "name": "Run in terminal", "description": "Setup Label", "type": "terminal", "args": ["--setup"], "env": { "VAR1": "value1", "VAR2": "value2" } } * `args` (optional, default `[]`): Additional arguments to pass when running the agent binary. * `env` (optional, default `{}`): Additional environment variables to set. The `command` cannot be specified, the client will invoke the exact same binary with the exact same setup. The agent can supply additional arguments and environment variables as necessary. These will be supplied in **addition** to any args/env supplied by default when the server is started. So agents will need to have a way to kickoff their interactive login flow even if normal acp commands/arguments are supplied as well. This is so that the agent doesn’t need to know about the environment it is running in. It can’t know the absolute path necessarily, and shouldn’t be able to supply other commands or programs to minimize security issues. ### [​](https://agentclientprotocol.com/rfds/auth-methods#client-capabilities) Client capabilities Because `terminal` auth methods require specific client-side support, clients must opt in via `AuthCapabilities` on `ClientCapabilities` during initialization: { "clientCapabilities": { "auth": { "terminal": true } } } * `auth.terminal` (default `false`): When `true`, the agent may include `terminal` entries in its authentication methods. The `env_var` type does not require a capability opt-in since any client can set environment variables when starting a process, we are just providing additional context for the environment variable. [​](https://agentclientprotocol.com/rfds/auth-methods#frequently-asked-questions) Frequently asked questions --------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/auth-methods#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? An alternative approach would be to include this information to an agent’s declaration making it more static, see [Registry RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289) There is also an alternative to adding a separate `elicitation` capability, which is to create a separate auth type for this. Then the client can decide themselves if they support it or not. [​](https://agentclientprotocol.com/rfds/auth-methods#revision-history) Revision history ------------------------------------------------------------------------------------------- There was a part about elicitations [https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx](https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx) removed it for now, will move to a separate rfd * 2026-03-09: Remove auth\_methods from Error type * 2026-03-03: Changed `env_var` from single `varName` to structured `vars` array of `AuthEnvVar` objects; simplified field name from `varName` to `name` * 2026-02-27: Updated to reflect current implementation * 2026-01-14: Updates based on Core Maintainer discussion Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/session-usage) [Rust SDK based on SACP\ \ Next](https://agentclientprotocol.com/rfds/rust-sdk-v1) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/auth-methods#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/auth-methods#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/auth-methods#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/auth-methods#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/auth-methods#implementation-details-and-plan) * [Auth method types](https://agentclientprotocol.com/rfds/auth-methods#auth-method-types) * [Client capabilities](https://agentclientprotocol.com/rfds/auth-methods#client-capabilities) * [Frequently asked questions](https://agentclientprotocol.com/rfds/auth-methods#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/auth-methods#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/auth-methods#revision-history) --- # Agent Telemetry Export - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/agent-telemetry-export#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Agent Telemetry Export [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@codefromthecrypt](https://github.com/codefromthecrypt) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------------------- > What are you proposing to change? Define how agents export telemetry (logs, metrics, traces) to clients without tunneling it over the ACP transport. Clients run a local telemetry receiver and pass standard OpenTelemetry environment variables when launching agents. This keeps telemetry out-of-band and enables editors to display agent activity, debug issues, and integrate with observability backends. [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#status-quo) Status quo ----------------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? ACP defines how clients launch agents as subprocesses and communicate over stdio. The [meta-propagation RFD](https://agentclientprotocol.com/rfds/meta-propagation) addresses trace context propagation via `params._meta`, enabling trace correlation. However, there is no convention for how agents should export the actual telemetry data (spans, metrics, logs). Without a standard approach: 1. **No visibility into agent behavior** - Editors cannot display what agents are doing (token usage, tool calls, timing) 2. **Difficult debugging** - When agents fail, there’s no structured way to capture diagnostics 3. **Fragmented solutions** - Each agent/client pair invents their own telemetry mechanism 4. **Credential exposure risk** - If agents need to send telemetry directly to backends, they need credentials Tunneling telemetry over the ACP stdio transport is problematic: * **Head-of-line blocking** - Telemetry traffic could delay agent messages * **Implementation burden** - ACP would need to define telemetry message formats * **Coupling** - Agents would need ACP-specific telemetry code instead of standard SDKs [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-we-propose-to-do-about-it) What we propose to do about it --------------------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? Clients that want to receive agent telemetry run a local OTLP (OpenTelemetry Protocol) receiver and inject environment variables when launching agent subprocesses: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_SERVICE_NAME=agent-name Agents using OpenTelemetry SDKs auto-configure from these variables. The client’s receiver can: * Display telemetry in the editor UI (e.g., token counts, timing, errors) * Forward telemetry to the client’s configured observability backend * Add client-side context before forwarding This follows the [OpenTelemetry collector deployment pattern](https://opentelemetry.io/docs/collector/deployment/agent/) where a local receiver proxies telemetry to backends. ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#architecture) Architecture ┌────────────────────────────────────────────────────────────┐ │ Client/Editor │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ ACP Handler │ │OTLP Receiver │───▶│ Exporter │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └────────┬─────────────────────▲──────────────────┬──────────┘ │ stdio │ HTTP │ ▼ │ ▼ ┌─────────────────────┐ │ ┌───────────────────┐ │ Agent Process │ │ │ Observability │ │ ┌──────────────┐ │ │ │ Backend │ │ │ ACP Agent │ │ │ └───────────────────┘ │ ├──────────────┤ │ │ │ │ OTEL SDK │────────────┘ │ └──────────────┘ │ └─────────────────────┘ ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#discovery) Discovery Environment variables must be set before launching the subprocess, but ACP capability exchange happens after connection. Options for discovery: 1. **Optimistic injection** - Clients inject OTEL environment variables unconditionally. Agents without OpenTelemetry support simply ignore them. This is pragmatic since environment variables are low-cost and OTEL SDKs handle misconfiguration gracefully. 2. **Registry metadata** - Agent registries (like the one proposed in PR #289) could include telemetry support in agent manifests, letting clients know ahead of time. 3. **Manual configuration** - Users configure their client to enable telemetry collection for specific agents. [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#shiny-future) Shiny future --------------------------------------------------------------------------------------------- > How will things will play out once this feature exists? 1. **Editor integration** - Editors can show agent activity: token usage, tool call timing, model switches, errors 2. **Unified debugging** - When agents fail, structured telemetry is available for diagnosis 3. **End-to-end traces** - Combined with `params._meta` trace propagation, traces flow from client through agent to any downstream services 4. **No credential sharing** - Agents never see backend credentials; the client handles authentication 5. **Standard SDKs** - Agent authors use normal OpenTelemetry SDKs that work in any context, not ACP-specific code [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#implementation-details) Implementation details ----------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#1-create-docs/protocol/observability-mdx) 1\. Create `docs/protocol/observability.mdx` Add a new protocol documentation page covering observability practices for ACP. This page will describe: **For Clients/Editors:** * Running an OTLP receiver to collect agent telemetry * Injecting `OTEL_EXPORTER_*` environment variables when launching agent subprocesses * Respecting user-configured `OTEL_*` variables (do not override if already set) * Forwarding telemetry to configured backends with client credentials **For Agent Authors:** * Using OpenTelemetry SDKs with standard auto-configuration * Recommended spans, metrics, and log patterns for agent operations * How telemetry flows when `OTEL_*` variables are present vs absent ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#2-update-docs/protocol/extensibility-mdx) 2\. Update `docs/protocol/extensibility.mdx` Add a section linking to the new observability doc, similar to how extensibility concepts relate to other protocol features. Add a brief mention that observability practices (telemetry export) are documented separately. ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#3-update-docs/docs-json) 3\. Update `docs/docs.json` Add `protocol/observability` to the Protocol navigation group. [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#frequently-asked-questions) Frequently asked questions ------------------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#how-does-this-relate-to-trace-propagation-in-params-meta) How does this relate to trace propagation in `params._meta`? They are complementary: * **Trace propagation** (`params._meta` with `traceparent`, etc.) passes trace context so spans can be correlated * **Telemetry export** (this RFD) defines where agents send the actual span/metric/log data Both are needed for end-to-end observability. ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-if-an-agent-doesn%E2%80%99t-use-opentelemetry) What if an agent doesn’t use OpenTelemetry? Agents without OTEL SDKs simply ignore the environment variables. No harm is done. Over time, as more agents adopt OpenTelemetry, the ecosystem benefits. ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-if-the-user-already-configured-otel-environment-variables) What if the user already configured `OTEL_*` environment variables? If `OTEL_*` variables are already set in the environment, clients should not override them. User-configured telemetry settings take precedence, allowing users to direct agent telemetry to their own backends when desired. ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#why-not-define-acp-specific-telemetry-messages) Why not define ACP-specific telemetry messages? This would duplicate OTLP functionality, add implementation burden to ACP, and force agent authors to use non-standard APIs. Using OTLP means agents work with standard tooling and documentation. ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-about-agents-that-aren%E2%80%99t-launched-as-subprocesses) What about agents that aren’t launched as subprocesses? This RFD focuses on the stdio transport where clients launch agents. For other transports (HTTP, etc.), agents would need alternative configuration mechanisms, which could be addressed in future RFDs. ### [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? 1. **Tunneling telemetry over ACP** - Rejected due to head-of-line blocking concerns and implementation complexity 2. **Agents export directly to backends** - Rejected because it requires sharing credentials with agents 3. **File-based telemetry** - Rejected because it doesn’t support real-time display and adds complexity The environment variable approach: * Uses existing standards (OTLP, OpenTelemetry SDK conventions) * Keeps telemetry out-of-band from ACP messages * Lets clients control where telemetry goes without exposing credentials * Requires no changes to ACP message formats [​](https://agentclientprotocol.com/rfds/agent-telemetry-export#revision-history) Revision history ----------------------------------------------------------------------------------------------------- * 2025-12-04: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/meta-propagation) [Agent Extensions via ACP Proxies\ \ Next](https://agentclientprotocol.com/rfds/proxy-chains) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/agent-telemetry-export#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/agent-telemetry-export#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-we-propose-to-do-about-it) * [Architecture](https://agentclientprotocol.com/rfds/agent-telemetry-export#architecture) * [Discovery](https://agentclientprotocol.com/rfds/agent-telemetry-export#discovery) * [Shiny future](https://agentclientprotocol.com/rfds/agent-telemetry-export#shiny-future) * [Implementation details](https://agentclientprotocol.com/rfds/agent-telemetry-export#implementation-details) * [1\. Create docs/protocol/observability.mdx](https://agentclientprotocol.com/rfds/agent-telemetry-export#1-create-docs%2Fprotocol%2Fobservability-mdx) * [2\. Update docs/protocol/extensibility.mdx](https://agentclientprotocol.com/rfds/agent-telemetry-export#2-update-docs%2Fprotocol%2Fextensibility-mdx) * [3\. Update docs/docs.json](https://agentclientprotocol.com/rfds/agent-telemetry-export#3-update-docs%2Fdocs-json) * [Frequently asked questions](https://agentclientprotocol.com/rfds/agent-telemetry-export#frequently-asked-questions) * [How does this relate to trace propagation in params.\_meta?](https://agentclientprotocol.com/rfds/agent-telemetry-export#how-does-this-relate-to-trace-propagation-in-params-meta) * [What if an agent doesn’t use OpenTelemetry?](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-if-an-agent-doesn%E2%80%99t-use-opentelemetry) * [What if the user already configured OTEL\_\* environment variables?](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-if-the-user-already-configured-otel-environment-variables) * [Why not define ACP-specific telemetry messages?](https://agentclientprotocol.com/rfds/agent-telemetry-export#why-not-define-acp-specific-telemetry-messages) * [What about agents that aren’t launched as subprocesses?](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-about-agents-that-aren%E2%80%99t-launched-as-subprocesses) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/agent-telemetry-export#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/agent-telemetry-export#revision-history) --- # Logout Method - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/logout-method#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Logout Method [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@anna239](https://github.com/anna239) [​](https://agentclientprotocol.com/rfds/logout-method#elevator-pitch) Elevator pitch ---------------------------------------------------------------------------------------- > What are you proposing to change? Add a `logout` method that allows clients to terminate an authenticated session with an agent. This is the counterpart to the existing `authenticate` method and enables proper session cleanup and credential invalidation. [​](https://agentclientprotocol.com/rfds/logout-method#status-quo) Status quo -------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? Currently, ACP provides an `authenticate` method for establishing authenticated sessions, but there is no standardized way to: * Log out of an authenticated session * Invalidate credentials or tokens * Signal to the agent that the user wants to end their authenticated state Users who want to switch accounts, revoke access, or simply log out must rely on: * Manually clearing credentials outside of ACP * Agent-specific workarounds This creates inconsistent user experiences and potential security concerns when credentials should be invalidated but aren’t. [​](https://agentclientprotocol.com/rfds/logout-method#shiny-future) Shiny future ------------------------------------------------------------------------------------ > How will things play out once this feature exists? Clients will be able to offer a proper “Log out” button that: 1. Cleanly terminates the authenticated session 2. Allows the agent to invalidate tokens/credentials as needed 3. Returns the connection to an unauthenticated state 4. Enables the user to re-authenticate with different credentials [​](https://agentclientprotocol.com/rfds/logout-method#implementation-details-and-plan) Implementation details and plan -------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/logout-method#new-method-logout) New Method: `logout` A new method that terminates the current authenticated session. #### [​](https://agentclientprotocol.com/rfds/logout-method#logoutrequest) LogoutRequest interface LogoutRequest { /** Extension metadata */ _meta?: Record; } #### [​](https://agentclientprotocol.com/rfds/logout-method#logoutresponse) LogoutResponse interface LogoutResponse { /** Extension metadata */ _meta?: Record; } ### [​](https://agentclientprotocol.com/rfds/logout-method#capability-advertisement) Capability Advertisement The `logout` capability should be advertised within a new `auth` object in `AgentCapabilities`: interface AgentCapabilities { // ... existing fields ... /** Authentication-related capabilities */ auth?: AgentAuthCapabilities; } interface AgentAuthCapabilities { /** Extension metadata */ _meta?: Record; /** Agent supports the logout method. Supply `{}` to indicate support. */ logout?: LogoutCapabilities; } interface LogoutCapabilities { /** Extension metadata */ _meta?: Record; } ### [​](https://agentclientprotocol.com/rfds/logout-method#json-schema-additions) JSON Schema Additions { "$defs": { "AgentAuthCapabilities": { "description": "Authentication-related capabilities supported by the agent.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] }, "logout": { "allOf": [\ {\ "$ref": "#/$defs/LogoutCapabilities"\ }\ ], "description": "Whether the agent supports the logout method. Supply `{}` to indicate support." } }, "type": "object" }, "LogoutCapabilities": { "description": "Logout capabilities supported by the agent. Supply `{}` to indicate support.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] } }, "type": "object" }, "LogoutRequest": { "description": "Request to terminate the current authenticated session.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] } }, "type": "object", "x-method": "logout", "x-side": "agent" }, "LogoutResponse": { "description": "Response to the logout method.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] } }, "type": "object", "x-method": "logout", "x-side": "agent" } } } ### [​](https://agentclientprotocol.com/rfds/logout-method#example-exchange) Example Exchange **Request:** { "jsonrpc": "2.0", "id": 1, "method": "logout", "params": {} } **Response:** { "jsonrpc": "2.0", "id": 1, "result": {} } ### [​](https://agentclientprotocol.com/rfds/logout-method#behavior) Behavior 1. **Pre-condition**: The client should only call `logout` if: * The agent advertises `auth.logout: {}` 2. **Agent responsibilities**: * Invalidate any stored tokens or credentials as appropriate * Clean up any session state associated with the authenticated user * Return the connection to an unauthenticated state 3. **Post-condition**: After a successful `logout`: * Subsequent requests that require authentication should return `auth_required` error * The client can call `authenticate` again to establish a new authenticated session 4. **Active sessions**: If there are active sessions when `logout` is called, the agent should either: * Terminate them gracefully * Throw an `auth_required` error [​](https://agentclientprotocol.com/rfds/logout-method#frequently-asked-questions) Frequently asked questions ---------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document? ### [​](https://agentclientprotocol.com/rfds/logout-method#should-logout-affect-active-sessions) Should logout affect active sessions? This is left as implementation-defined. Some agents may want to: * Automatically terminate all sessions (strict security) * Keep sessions running The RFD intentionally does not mandate a specific behavior to allow flexibility. [​](https://agentclientprotocol.com/rfds/logout-method#revision-history) Revision history -------------------------------------------------------------------------------------------- * 2026-02-02: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/rust-sdk-v1) [Session Delete\ \ Next](https://agentclientprotocol.com/rfds/session-delete) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/logout-method#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/logout-method#status-quo) * [Shiny future](https://agentclientprotocol.com/rfds/logout-method#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/logout-method#implementation-details-and-plan) * [New Method: logout](https://agentclientprotocol.com/rfds/logout-method#new-method-logout) * [LogoutRequest](https://agentclientprotocol.com/rfds/logout-method#logoutrequest) * [LogoutResponse](https://agentclientprotocol.com/rfds/logout-method#logoutresponse) * [Capability Advertisement](https://agentclientprotocol.com/rfds/logout-method#capability-advertisement) * [JSON Schema Additions](https://agentclientprotocol.com/rfds/logout-method#json-schema-additions) * [Example Exchange](https://agentclientprotocol.com/rfds/logout-method#example-exchange) * [Behavior](https://agentclientprotocol.com/rfds/logout-method#behavior) * [Frequently asked questions](https://agentclientprotocol.com/rfds/logout-method#frequently-asked-questions) * [Should logout affect active sessions?](https://agentclientprotocol.com/rfds/logout-method#should-logout-affect-active-sessions) * [Revision history](https://agentclientprotocol.com/rfds/logout-method#revision-history) --- # Boolean Config Option Type - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/boolean-config-option#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Boolean Config Option Type [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [fscarponi](https://github.com/fscarponi) * Champion: [benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/boolean-config-option#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------------------ Add a new `boolean` type to session configuration options, enabling agents to expose simple ON/OFF toggles (e.g., “Brave Mode”, “Read Only”, “Produce Report”) as first-class config options alongside the existing `select` type. [​](https://agentclientprotocol.com/rfds/boolean-config-option#status-quo) Status quo ---------------------------------------------------------------------------------------- Currently, `SessionConfigKind` only supports the `select` type, which allows agents to expose dropdown-style selectors with a list of named values. This works well for choosing models, modes, or reasoning levels. However, there is no native way to represent a simple boolean on/off toggle. To expose a boolean option today, agents must use a `select` with two artificial options (e.g., “on”/“off”), and clients need custom, non-agnostic logic to detect that a particular select is actually a boolean toggle. This defeats the purpose of a standardized protocol. [​](https://agentclientprotocol.com/rfds/boolean-config-option#what-we-propose-to-do-about-it) What we propose to do about it -------------------------------------------------------------------------------------------------------------------------------- * Add a `SessionConfigBoolean` struct with a `current_value: bool` field * Add a `Boolean(SessionConfigBoolean)` variant to the `SessionConfigKind` enum, discriminated by `"type": "boolean"` * Add a `SessionConfigOptionValue` internally-tagged enum so that `SetSessionConfigOptionRequest` can carry both string values (for `select`) and boolean values (for `boolean`) with an explicit `type` discriminator * Provide convenience constructors and `From` impls for ergonomic usage * Update documentation and regenerate schema files [​](https://agentclientprotocol.com/rfds/boolean-config-option#shiny-future) Shiny future -------------------------------------------------------------------------------------------- Clients can natively render boolean config options as toggle switches or checkboxes, without any custom logic. Agents can expose options like “Brave Mode”, “Produce Report”, or “Read Only” in a standardized way that any ACP-compliant client understands out of the box. [​](https://agentclientprotocol.com/rfds/boolean-config-option#implementation-details-and-plan) Implementation details and plan ---------------------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/boolean-config-option#wire-format-declaring-a-boolean-option) Wire format: declaring a boolean option In a `session/new` response (or any response containing `configOptions`): { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123", "configOptions": [\ {\ "id": "brave_mode",\ "name": "Brave Mode",\ "description": "Skip confirmation prompts and act autonomously",\ "type": "boolean",\ "currentValue": true\ },\ {\ "id": "mode",\ "name": "Session Mode",\ "category": "mode",\ "type": "select",\ "currentValue": "code",\ "options": [\ { "value": "ask", "name": "Ask" },\ { "value": "code", "name": "Code" }\ ]\ }\ ] } } ### [​](https://agentclientprotocol.com/rfds/boolean-config-option#wire-format-setting-a-boolean-option) Wire format: setting a boolean option The `session/set_config_option` request carries a `type` discriminator alongside the `value`. The `type` field describes the _shape_ of the value, not the option kind. When `type` is absent the value is treated as a `SessionConfigValueId` string, preserving backwards compatibility with existing clients: { "jsonrpc": "2.0", "id": 2, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123", "configId": "brave_mode", "type": "boolean", "value": true } } For select options the `type` field can be omitted (defaults to `value_id`): { "jsonrpc": "2.0", "id": 3, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123", "configId": "mode", "value": "code" } } The response returns the full set of config options with current values, as with `select`: { "jsonrpc": "2.0", "id": 2, "result": { "configOptions": [\ {\ "id": "brave_mode",\ "name": "Brave Mode",\ "description": "Skip confirmation prompts and act autonomously",\ "type": "boolean",\ "currentValue": true\ },\ {\ "id": "mode",\ "name": "Session Mode",\ "category": "mode",\ "type": "select",\ "currentValue": "code",\ "options": [..]\ }\ ] } } Key changes: 1. `SessionConfigBoolean` struct with `current_value: bool` 2. `Boolean(SessionConfigBoolean)` variant in `SessionConfigKind` (tagged via `"type": "boolean"`) 3. `SessionConfigOptionValue` enum using `#[serde(tag = "type")]` with a `#[serde(untagged)]` fallback variant — the same pattern as `AuthMethod`: * `Boolean { value: bool }` — matched when `type` is `"boolean"` * `ValueId { value: SessionConfigValueId }` — untagged fallback when `type` is absent or unrecognised 4. `SessionConfigOptionValue` is flattened (`#[serde(flatten)]`) onto `SetSessionConfigOptionRequest`, producing top-level `type` and `value` fields on the wire 5. The `value` field type change in `SetSessionConfigOptionRequest` is gated behind `#[cfg(feature = "unstable_boolean_config")]` — without the feature the field remains `SessionConfigValueId` 6. `From` impls (`&str`, `SessionConfigValueId`, `bool`) ensure ergonomic construction 7. Wire-level backward compatible: existing JSON payloads without a `type` field remain valid via the untagged fallback ### [​](https://agentclientprotocol.com/rfds/boolean-config-option#client-capabilities) Client capabilities Per the existing protocol design, clients that receive a config option with an unrecognized `type` should ignore it. Since the agent is required to have a default value for every option, the agent can function correctly even if the client doesn’t render or interact with the boolean option. No new client capability negotiation is needed. [​](https://agentclientprotocol.com/rfds/boolean-config-option#frequently-asked-questions) Frequently asked questions ------------------------------------------------------------------------------------------------------------------------ ### [​](https://agentclientprotocol.com/rfds/boolean-config-option#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? We considered reusing the existing `select` type with a convention (e.g., options named “on”/“off”), but this would require clients to implement non-agnostic detection logic, which contradicts the goal of a standardized protocol. A dedicated `boolean` type is cleaner and lets clients render the appropriate UI control without guessing. ### [​](https://agentclientprotocol.com/rfds/boolean-config-option#is-this-a-breaking-change) Is this a breaking change? On the wire/JSON level: no. When `type` is absent the value is treated as a `SessionConfigValueId`, so existing payloads deserialize correctly. On the Rust API level: the type of `SetSessionConfigOptionRequest.value` changes, but this is gated behind `unstable_boolean_config`. Without the feature flag the stable API is unchanged. With the feature flag, `From` impls ensure source compatibility for users of the `new()` constructor. [​](https://agentclientprotocol.com/rfds/boolean-config-option#revision-history) Revision history ---------------------------------------------------------------------------------------------------- * 2026-02-24: Initial proposal * 2026-03-05: Updated to reflect final implementation — `flag` renamed to `boolean`, value type changed from untagged `String | Bool` enum to internally-tagged enum with `type` discriminator and untagged `ValueId` fallback, feature-gated behind `unstable_boolean_config` Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/diff-delete) [Elicitation: Structured User Input\ \ Next](https://agentclientprotocol.com/rfds/elicitation) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/boolean-config-option#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/boolean-config-option#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/boolean-config-option#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/boolean-config-option#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/boolean-config-option#implementation-details-and-plan) * [Wire format: declaring a boolean option](https://agentclientprotocol.com/rfds/boolean-config-option#wire-format-declaring-a-boolean-option) * [Wire format: setting a boolean option](https://agentclientprotocol.com/rfds/boolean-config-option#wire-format-setting-a-boolean-option) * [Client capabilities](https://agentclientprotocol.com/rfds/boolean-config-option#client-capabilities) * [Frequently asked questions](https://agentclientprotocol.com/rfds/boolean-config-option#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/boolean-config-option#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Is this a breaking change?](https://agentclientprotocol.com/rfds/boolean-config-option#is-this-a-breaking-change) * [Revision history](https://agentclientprotocol.com/rfds/boolean-config-option#revision-history) --- # ACP Agent Registry - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/acp-agent-registry#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Completed ACP Agent Registry [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) **Author:** [@ignatov](https://github.com/ignatov) **Champion:** [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/acp-agent-registry#elevator-pitch) Elevator pitch --------------------------------------------------------------------------------------------- ACP needs a single, trusted registry of agents so clients can discover integrations, understand their capabilities, and configure them automatically. This RFD proposes (1) a canonical manifest format that every agent must publish, (2) a dedicated `agentclientprotocol/registry` repo where maintainers contribute those manifests, and (3) tooling that aggregates and publishes a searchable catalog for editors and other clients. [​](https://agentclientprotocol.com/rfds/acp-agent-registry#status-quo) Status quo ------------------------------------------------------------------------------------- There is no canonical listing of ACP-compatible agents. Information lives in scattered READMEs or proprietary feeds, which makes it hard to: * Let users discover agents directly inside ACP-aware clients. * Ensure protocol-version compatibility or capability coverage. * Keep metadata consistent (hosting model, license, etc.). Every editor builds bespoke manifests or scrapes GitHub, leading to duplication and stale data. [​](https://agentclientprotocol.com/rfds/acp-agent-registry#agent-manifest-format-core-proposal) Agent manifest format (core proposal) ----------------------------------------------------------------------------------------------------------------------------------------- Each agent advertises itself via a manifest stored as `/agent.json` in the registry repo. Fields marked with **\*** are required: | Field | Description | | --- | --- | | `id` **\*** | Unique agent identifier. Lowercase letters, digits, and hyphens; must start with a letter (pattern: `^[a-z][a-z0-9-]*$`). Also the folder name in the registry repo. | | `name` **\*** | Human-readable display name. | | `version` **\*** | Semantic version of the agent release (e.g. `1.0.0`). | | `description` **\*** | Brief description of the agent’s functionality and purpose. | | `distribution` **\*** | Object describing how to obtain and run the agent. Supports three distribution types: `binary` (platform-specific archives), `npx` (Node packages), and `uvx` (Python packages). At least one distribution type must be provided. See [Distribution](https://agentclientprotocol.com/rfds/acp-agent-registry#distribution)
for details. | | `repository` | Source code repository URL. | | `authors` | Array of author/organization names. | | `license` | SPDX license identifier or `"proprietary"`. | | `icon` | Path to icon file (relative path or absolute URL). Must be SVG format, 16×16, monochrome using `currentColor` (enables light/dark theme adaptation). See [Icon requirements](https://agentclientprotocol.com/rfds/acp-agent-registry#icon-requirements)
. | ### [​](https://agentclientprotocol.com/rfds/acp-agent-registry#distribution) Distribution The `distribution` object supports three mutually independent strategies. An agent may provide one or more: #### [​](https://agentclientprotocol.com/rfds/acp-agent-registry#binary) `binary` Platform-specific archive downloads. Keyed by `-` targets: | Target | OS | Architecture | | --- | --- | --- | | `darwin-aarch64` | macOS | ARM64 | | `darwin-x86_64` | macOS | x86-64 | | `linux-aarch64` | Linux | ARM64 | | `linux-x86_64` | Linux | x86-64 | | `windows-aarch64` | Windows | ARM64 | | `windows-x86_64` | Windows | x86-64 | When using `binary` distribution, builds **must be provided for all three operating systems** (darwin, linux, windows). CI will reject entries that only cover a subset. Each target is an object with: | Field | Required | Description | | --- | --- | --- | | `archive` | Yes | URL to download archive | | `cmd` | Yes | Command to execute after extraction | | `args` | No | Array of command-line arguments | | `env` | No | Object of environment variables | #### [​](https://agentclientprotocol.com/rfds/acp-agent-registry#npx-/-uvx) `npx` / `uvx` Package-manager-based distribution (Node via `npx`, Python via `uvx`). Each is an object with: | Field | Required | Description | | --- | --- | --- | | `package` | Yes | Package name (with optional version spec) | | `args` | No | Array of command-line arguments | | `env` | No | Object of environment variables | ### [​](https://agentclientprotocol.com/rfds/acp-agent-registry#icon-requirements) Icon requirements Icons must meet the following requirements to pass CI validation: * **SVG format** — only `.svg` files are accepted. * **16×16 dimensions** — via `width`/`height` attributes or `viewBox`. * **Monochrome using `currentColor`** — all `fill` and `stroke` values must use `currentColor` or `none`. Hardcoded colors (e.g. `fill="#FF5500"`, `fill="red"`) are rejected. Using `currentColor` lets icons adapt automatically to the client’s light or dark theme. ### [​](https://agentclientprotocol.com/rfds/acp-agent-registry#example-binary-distribution) Example: binary distribution { "id": "someagent", "name": "SomeAgent", "version": "1.0.0", "description": "Agent for code editing", "repository": "https://github.com/example/someagent", "authors": ["Example Team"], "license": "MIT", "icon": "icon.svg", "distribution": { "binary": { "darwin-aarch64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip", "cmd": "./someagent", "args": ["acp"], }, "darwin-x86_64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip", "cmd": "./someagent", "args": ["acp"], }, "linux-aarch64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip", "cmd": "./someagent", "args": ["acp"], }, "linux-x86_64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip", "cmd": "./someagent", "args": ["acp"], }, "windows-x86_64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip", "cmd": "./someagent.exe", "args": ["acp"], "env": { "SOMEAGENT_MODE_KEY": "", }, }, }, }, } ### [​](https://agentclientprotocol.com/rfds/acp-agent-registry#example-package-distribution) Example: package distribution { "id": "pyagent", "name": "PyAgent", "version": "2.1.0", "description": "A Python-based ACP agent", "repository": "https://github.com/example/pyagent", "license": "Apache-2.0", "distribution": { "uvx": { "package": "pyagent@latest", "args": ["--mode", "acp"], }, }, } [​](https://agentclientprotocol.com/rfds/acp-agent-registry#registry-schema) Registry schema ----------------------------------------------------------------------------------------------- The aggregated `registry.json` file conforms to the registry schema and contains: | Field | Description | | --- | --- | | `version` | Registry schema version (semver, e.g. `1.0.0`). | | `agents` | Array of agent entries (each following the agent manifest schema above, sourced from `agent.json` files). | [​](https://agentclientprotocol.com/rfds/acp-agent-registry#authentication-requirements) Authentication requirements ----------------------------------------------------------------------------------------------------------------------- To be listed in the registry, an agent **must support at least one** of the following authentication methods: * **Agent Auth** — the agent handles the OAuth flow independently (opens the user’s browser, runs a local callback server, exchanges the authorization code for tokens). * **Terminal Auth** — the agent provides an interactive terminal-based setup experience (launched with additional args/env specified in the auth method). CI verifies this by checking that the agent returns an `authMethods` array in its `initialize` response, with at least one method. See the [ACP auth methods RFD](https://agentclientprotocol.com/rfds/auth-methods) for the full specification. [​](https://agentclientprotocol.com/rfds/acp-agent-registry#what-we-propose-to-do-about-it) What we propose to do about it ----------------------------------------------------------------------------------------------------------------------------- 1. **Manifest spec** (above) becomes normative; we publish the JSON Schema and validator script so maintainers can lint locally. 2. **Registry repository** `github.com/agentclientprotocol/registry`: * Structure: `/agent.json`, optional `icon.svg`, optional `README.md`. * CI validates manifests on every PR: schema compliance, slug uniqueness, icon format (16×16 SVG, monochrome `currentColor`), URL accessibility for all distribution URLs, authentication support via ACP handshake, and binary OS coverage. * Push to `main` triggers a build that aggregates all entries into `registry.json` and publishes versioned + `latest` GitHub releases. 3. **Aggregated outputs**: * `registry.json`: deterministic list of all agents with icons copied to `dist/.svg`. 4. **Distribution & search**: * Clients fetch `registry.json` from `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`. * Static site offers filters for deployment model, license, and distribution type. [​](https://agentclientprotocol.com/rfds/acp-agent-registry#shiny-future) Shiny future ----------------------------------------------------------------------------------------- * Agent maintainers make PRs to update their manifests; CI keeps data clean. * Automated version updates run hourly, checking npm, PyPI, and GitHub releases for new versions of registered agents and opening PRs automatically. * Editors/clients can bootstrap ACP support by fetching one JSON file and filtering locally. * The ACP website displays the same data for humans, ensuring consistency. * Package-based distribution (`npx`, `uvx`) lowers the barrier for agents that don’t need platform-specific binaries. [​](https://agentclientprotocol.com/rfds/acp-agent-registry#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------------- **Phase 1 – Spec & repo bootstrap** * Finalize JSON Schema and documentation. * Create registry repo with CI (GitHub Actions) that validates on PRs and publishes on merge. * Seed with reference agents. * Implement automated version update workflow (hourly cron via GitHub Actions). * Enforce authentication requirements via CI handshake verification. [​](https://agentclientprotocol.com/rfds/acp-agent-registry#revision-history) Revision history ------------------------------------------------------------------------------------------------- * 2025-11-28: Initial draft. * 2025-12-16: Minors. * 2026-02-04: Updated to match latest schema — removed `schema_version`, `homepage`, `capabilities`, and `auth` fields; added `icon` field; restructured `distribution` into `binary`, `npx`, and `uvx` types. Was this page helpful? YesNo [Previous\ \ Session Info Update](https://agentclientprotocol.com/rfds/session-info-update) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/acp-agent-registry#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/acp-agent-registry#status-quo) * [Agent manifest format (core proposal)](https://agentclientprotocol.com/rfds/acp-agent-registry#agent-manifest-format-core-proposal) * [Distribution](https://agentclientprotocol.com/rfds/acp-agent-registry#distribution) * [binary](https://agentclientprotocol.com/rfds/acp-agent-registry#binary) * [npx / uvx](https://agentclientprotocol.com/rfds/acp-agent-registry#npx-%2F-uvx) * [Icon requirements](https://agentclientprotocol.com/rfds/acp-agent-registry#icon-requirements) * [Example: binary distribution](https://agentclientprotocol.com/rfds/acp-agent-registry#example-binary-distribution) * [Example: package distribution](https://agentclientprotocol.com/rfds/acp-agent-registry#example-package-distribution) * [Registry schema](https://agentclientprotocol.com/rfds/acp-agent-registry#registry-schema) * [Authentication requirements](https://agentclientprotocol.com/rfds/acp-agent-registry#authentication-requirements) * [What we propose to do about it](https://agentclientprotocol.com/rfds/acp-agent-registry#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/acp-agent-registry#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/acp-agent-registry#implementation-details-and-plan) * [Revision history](https://agentclientprotocol.com/rfds/acp-agent-registry#revision-history) --- # Closing active sessions - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-close#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Preview Closing active sessions [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [@SteffenDE](https://github.com/SteffenDE) [​](https://agentclientprotocol.com/rfds/session-close#elevator-pitch) Elevator pitch ---------------------------------------------------------------------------------------- > What are you proposing to change? We propose adding the ability to close active sessions. This allows the agent to free up any memory and threads/subprocesses associated with that session. [​](https://agentclientprotocol.com/rfds/session-close#status-quo) Status quo -------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? Today, if you start a session, it will remain active until the ACP process is terminated. This means that if the agent implements sessions as separate processes, active users with many sessions can end up with a lot of processes unnecessarily using up system memory. Even if the agent does not spawn separate processes, memory used by large tool results or similar could still accumulate over time. The only way to free up that memory is to terminate the whole ACP process, which will stop all sessions and - if the agent does not support resuming sessions (load / resume / fork) - lead to a bad user experience. [​](https://agentclientprotocol.com/rfds/session-close#what-we-propose-to-do-about-it) What we propose to do about it ------------------------------------------------------------------------------------------------------------------------ > What are you proposing to improve the situation? Add a new `session/close` method. If supported, the agent **must** cancel any ongoing work related to the session (treat it as if `session/cancel` was called) and then free up any resources associated with the session. [​](https://agentclientprotocol.com/rfds/session-close#shiny-future) Shiny future ------------------------------------------------------------------------------------ > How will things will play out once this feature exists? Clients can track what sessions are actively used by a user and automatically close old sessions. [​](https://agentclientprotocol.com/rfds/session-close#implementation-details-and-plan) Implementation details and plan -------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? We propose to add a new `"session/close"` method. Agents must declare this option is available by returning `sessionCapabilities: { close: {} }` in their capabilities. The object is reserved to declare future capabilities. Then the client would be able to close a specific session with: { "jsonrpc": "2.0", "id": 1, "method": "session/close", "params": { "sessionId": "sess_789xyz" } } Agents might reply with an error if the session is not active or does not exist. [​](https://agentclientprotocol.com/rfds/session-close#frequently-asked-questions) Frequently asked questions ---------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? None so far. ### [​](https://agentclientprotocol.com/rfds/session-close#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? It could be an agent specific custom method, since we mainly ran into problems with Claude Code, but even for agents that don’t spawn full subprocesses for sessions, cleaning up unneeded sessions still seems like a good idea. [​](https://agentclientprotocol.com/rfds/session-close#revision-history) Revision history -------------------------------------------------------------------------------------------- 2026-04-14: Move to preview and update capability docs to `sessionCapabilities.close` 2026-03-09: Rename from session/stop to session/close 2026-02-24: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport) [Resuming of existing sessions\ \ Next](https://agentclientprotocol.com/rfds/session-resume) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-close#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-close#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-close#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/session-close#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-close#implementation-details-and-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-close#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/session-close#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/session-close#revision-history) --- # Session Delete - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-delete#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Session Delete [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [@chazcb](https://github.com/chazcb) Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/session-delete#elevator-pitch) Elevator pitch ----------------------------------------------------------------------------------------- > What are you proposing to change? Add a capability-gated `session/delete` method so clients can remove sessions from `session/list`. This complements `session/list` by giving users control over which sessions appear in their session history. [​](https://agentclientprotocol.com/rfds/session-delete#status-quo) Status quo --------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? The [`session/list` RFD](https://agentclientprotocol.com/rfds/session-list) introduced the ability for clients to enumerate sessions. However, there’s no standard way to remove sessions from this list. Without `session/delete`, users have no control over their session history—old sessions accumulate, and clients must implement non-standard deletion mechanisms or rely on agent-specific cleanup policies. [​](https://agentclientprotocol.com/rfds/session-delete#what-we-propose-to-do-about-it) What we propose to do about it ------------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? Add a `session/delete` JSON-RPC method that is capability-gated. Agents advertise support via `sessionCapabilities.delete` in their initialization response. { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "delete": {} } } } } ### [​](https://agentclientprotocol.com/rfds/session-delete#method) Method { "jsonrpc": "2.0", "id": 3, "method": "session/delete", "params": { "sessionId": "sess_abc123def456" } } ### [​](https://agentclientprotocol.com/rfds/session-delete#request-parameters) Request Parameters | Field | Type | Required | Description | | --- | --- | --- | --- | | `sessionId` | `SessionId` | Yes | The session to delete | ### [​](https://agentclientprotocol.com/rfds/session-delete#response) Response On success, returns an empty result: { "jsonrpc": "2.0", "id": 3, "result": {} } ### [​](https://agentclientprotocol.com/rfds/session-delete#semantics) Semantics * **Capability-gated**: Agents MUST NOT accept `session/delete` calls unless they advertised `sessionCapabilities.delete` at initialization. * **Removes from list**: The primary effect is that deleted sessions no longer appear in `session/list` results. * **Implementation-defined storage behavior**: Agents may implement soft delete (mark as hidden) or hard delete (remove data). The protocol does not prescribe which. * **Implementation-defined load behavior**: Agents may choose what happens when a client calls `session/load` on a deleted session—return the session anyway, return an error, or any other behavior. The protocol does not prescribe which. * **Idempotent**: Deleting an already-deleted session (or a session that never existed) SHOULD succeed silently rather than error. [​](https://agentclientprotocol.com/rfds/session-delete#alternatives-considered) Alternatives considered ----------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/session-delete#automatic-lifecycle-policies-only) Automatic lifecycle policies only Rely on agents to implement their own session retention policies (e.g., delete sessions older than 30 days) without exposing user control. **Tradeoffs**: Users have no control over which sessions are kept. A session the user wants to keep might be deleted, or a session the user wants gone might persist. ### [​](https://agentclientprotocol.com/rfds/session-delete#add-a-hidden-flag-to-sessions) Add a `hidden` flag to sessions Instead of delete, allow users to mark sessions as hidden. They’d still exist but not appear in `session/list` by default. **Tradeoffs**: More complex—requires filter parameters on `session/list` to show/hide hidden sessions. For most use cases, delete is simpler and matches user expectations. ### [​](https://agentclientprotocol.com/rfds/session-delete#batch-deletion) Batch deletion Support deleting multiple sessions in one call via a `sessionIds` array. **Tradeoffs**: Could be added later as an extension. Single-session delete covers the common case and keeps the initial implementation simple. [​](https://agentclientprotocol.com/rfds/session-delete#shiny-future) Shiny future ------------------------------------------------------------------------------------- > How will things play out once this feature exists? Users can manage their session history, and all ACP clients can offer this using the same protocol method rather than implementing their own mechanisms. [​](https://agentclientprotocol.com/rfds/session-delete#implementation-details-and-plan) Implementation details and plan --------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? 1. **Schema**: Add `session/delete` method definition, `DeleteSessionRequest` and `DeleteSessionResponse` types. 2. **Capabilities**: Add `sessionCapabilities.delete` capability flag. 3. **Protocol**: Add `session/delete` to method tables. 4. **Docs**: Update session management docs to include deletion. [​](https://agentclientprotocol.com/rfds/session-delete#frequently-asked-questions) Frequently asked questions ----------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/session-delete#why-not-prescribe-soft-vs-hard-delete) Why not prescribe soft vs hard delete? Different agents have different storage architectures and compliance requirements. Some may need to retain data for auditing; others may want to free storage immediately. The protocol focuses on the user-facing behavior (removed from list) and leaves storage decisions to implementers. ### [​](https://agentclientprotocol.com/rfds/session-delete#why-not-prescribe-behavior-for-loading-deleted-sessions) Why not prescribe behavior for loading deleted sessions? Similar reasoning—some agents may want to allow “undelete” by loading a soft-deleted session, others may want a clean error. The protocol provides the deletion mechanism; agents decide the semantics that fit their use case. ### [​](https://agentclientprotocol.com/rfds/session-delete#should-delete-require-confirmation) Should delete require confirmation? No. Confirmation UX is a client concern. The protocol provides the delete operation; clients can add confirmation dialogs, undo functionality, or other UX patterns as they see fit. ### [​](https://agentclientprotocol.com/rfds/session-delete#what-if-the-session-is-currently-active) What if the session is currently active? Agents may reject deletion of active sessions or handle it however they choose. This is implementation-defined. A reasonable approach is to allow deletion—the session simply won’t appear in future `session/list` calls. ### [​](https://agentclientprotocol.com/rfds/session-delete#why-is-this-a-separate-rfd-from-session/list) Why is this a separate RFD from session/list? The [`session/list` RFD](https://agentclientprotocol.com/rfds/session-list#what-about-session-deletion) explicitly deferred deletion to keep scope focused. Now that `session/list` is established, `session/delete` is a natural complement. [​](https://agentclientprotocol.com/rfds/session-delete#revision-history) Revision history --------------------------------------------------------------------------------------------- * **2025-02-03**: Fixed capability example to use agent capability (initialize response) * **2025-01-24**: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/logout-method) [Message ID\ \ Next](https://agentclientprotocol.com/rfds/message-id) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-delete#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-delete#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-delete#what-we-propose-to-do-about-it) * [Method](https://agentclientprotocol.com/rfds/session-delete#method) * [Request Parameters](https://agentclientprotocol.com/rfds/session-delete#request-parameters) * [Response](https://agentclientprotocol.com/rfds/session-delete#response) * [Semantics](https://agentclientprotocol.com/rfds/session-delete#semantics) * [Alternatives considered](https://agentclientprotocol.com/rfds/session-delete#alternatives-considered) * [Automatic lifecycle policies only](https://agentclientprotocol.com/rfds/session-delete#automatic-lifecycle-policies-only) * [Add a hidden flag to sessions](https://agentclientprotocol.com/rfds/session-delete#add-a-hidden-flag-to-sessions) * [Batch deletion](https://agentclientprotocol.com/rfds/session-delete#batch-deletion) * [Shiny future](https://agentclientprotocol.com/rfds/session-delete#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-delete#implementation-details-and-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-delete#frequently-asked-questions) * [Why not prescribe soft vs hard delete?](https://agentclientprotocol.com/rfds/session-delete#why-not-prescribe-soft-vs-hard-delete) * [Why not prescribe behavior for loading deleted sessions?](https://agentclientprotocol.com/rfds/session-delete#why-not-prescribe-behavior-for-loading-deleted-sessions) * [Should delete require confirmation?](https://agentclientprotocol.com/rfds/session-delete#should-delete-require-confirmation) * [What if the session is currently active?](https://agentclientprotocol.com/rfds/session-delete#what-if-the-session-is-currently-active) * [Why is this a separate RFD from session/list?](https://agentclientprotocol.com/rfds/session-delete#why-is-this-a-separate-rfd-from-session%2Flist) * [Revision history](https://agentclientprotocol.com/rfds/session-delete#revision-history) --- # Resuming of existing sessions - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-resume#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Preview Resuming of existing sessions [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@josevalim](https://github.com/josevalim) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/session-resume#elevator-pitch) Elevator pitch ----------------------------------------------------------------------------------------- > What are you proposing to change? We propose adding the ability to resume existing sessions. This is similar to “session/load”, except it does not return previous messages. [​](https://agentclientprotocol.com/rfds/session-resume#status-quo) Status quo --------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? While the spec provides a “session/load” command, not all coding agents implement it. This means that, once you close your editor, browser, etc, you can’t resume the conversation. This is particularly a problem for agents that do not directly implement ACP and the functionality is implemented via a wrapper. In such cases, they may provide the ability to resume (without history), which we would like to hook into. Not only that, resuming could be used as a mechanism for proxies and adapter libraries to emulate “session/load”. [​](https://agentclientprotocol.com/rfds/session-resume#what-we-propose-to-do-about-it) What we propose to do about it ------------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? Add a “session/resume” command and a capability `{ sessionCapabilities: { resume: {} } }`. [​](https://agentclientprotocol.com/rfds/session-resume#shiny-future) Shiny future ------------------------------------------------------------------------------------- > How will things will play out once this feature exists? We will be able to resume existing conversations, providing a better user experience. Not only that, if an agent does not implement “session/load” but it does implement “session/resume”, it is now possible to implement a proxy/adapter that intercepts the agents messages and writes them to disk. Now when the client issues a “session/load”, the proxy/adapter converts it to a “session/resume”, and then returns the stored messages. [​](https://agentclientprotocol.com/rfds/session-resume#implementation-details-and-plan) Implementation details and plan --------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? [​](https://agentclientprotocol.com/rfds/session-resume#frequently-asked-questions) Frequently asked questions ----------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/session-resume#should-we-introduce-a-new-operation-session/resume-or-add-an-option-to-session/load-) Should we introduce a new operation (session/resume) or add an option to (session/load)? A separate method provides a few benefits: * for clients that for whatever reason don’t want the history, they can just resume * for agents that can only supply resume, a proxy on top could provide load on top of it, but the agent is still clear on what it supports * for agents who support both, it should be trivial to use the same resume functionality, they just either replay events or do not ### [​](https://agentclientprotocol.com/rfds/session-resume#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? The biggest question is if it makes sense to support both “session/load” and “session/resume”. When we start a new session over ACP, we introduce custom MCP tools and configuration. This means that, while we could use “session/load” to load our own chats, loading third-party chats would likely lead to a flawed user experience, as our tools would not be available. And depending on the ACP implementation, not even the capabilities would be respected (as loading a third-party session would not include our capabilities in its history, misleading the agent). Therefore, if we assume “session/load” is for loading conversations started by the client itself, “session/resume” is effectively a subset of “session/load”, decoupled from storage mechanics. If an agent implements “session/load”, then it can be used directly, but if it doesn’t, a proxy or adapter can provide a reasonable fallback on top of “session/resume”. This argues “session/resume” is the basic primitive which “session/load” builds on top of. [​](https://agentclientprotocol.com/rfds/session-resume#revision-history) Revision history --------------------------------------------------------------------------------------------- * 2026-04-14: Update capability shape to `sessionCapabilities.resume` * 2025-11-24: Update FAQ to mention session/resume vs session/load Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/session-close) [Introduce RFD Process\ \ Next](https://agentclientprotocol.com/rfds/introduce-rfd-process) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-resume#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-resume#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-resume#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/session-resume#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-resume#implementation-details-and-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-resume#frequently-asked-questions) * [Should we introduce a new operation (session/resume) or add an option to (session/load)?](https://agentclientprotocol.com/rfds/session-resume#should-we-introduce-a-new-operation-session%2Fresume-or-add-an-option-to-session%2Fload-) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/session-resume#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/session-resume#revision-history) --- # Message ID - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/message-id#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Message ID [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@michelTho](https://github.com/michelTho) , [@nemtecl](https://github.com/nemtecl) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/message-id#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------- Add a `messageId` field to `agent_message_chunk`, `user_message_chunk`, `agent_thought_chunk` session updates and `session/prompt` requests, and a `userMessageId` field to `session/prompt` responses, to uniquely identify individual messages within a conversation. Both clients and agents can generate message IDs using UUID format. This enables clients to distinguish between different messages beyond changes in update type and lays the groundwork for future capabilities like message editing and session deduplication. [​](https://agentclientprotocol.com/rfds/message-id#status-quo) Status quo ----------------------------------------------------------------------------- Currently, when an Agent sends message chunks via `session/update` notifications, there is no explicit identifier for the message being streamed: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Let me analyze your code..." } } } } This creates several limitations: 1. **Ambiguous message boundaries** - When the Agent sends multiple messages in sequence (e.g., alternating between agent and user messages, or multiple agent messages), Clients can only infer message boundaries by detecting a change in the `sessionUpdate` type. If an Agent sends consecutive messages of the same type, Clients cannot distinguish where one message ends and another begins. 2. **Non-standard workarounds** - Currently, implementations rely on the `_meta` field to work around this limitation. While functional, this approach is not standardized and each implementation may use different conventions. 3. **Limited future capabilities** - Without stable message identifiers, it’s difficult to build features like: * Message editing or updates * Message-specific metadata or annotations * Message threading or references * Undo/redo functionality As an example, consider this sequence where a Client cannot reliably determine message boundaries: // First agent message chunk { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Analyzing..." } } // More chunks... but is this still the same message or a new one? { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Found issues." } } // Tool call happens { "sessionUpdate": "tool_call", ... } // Another agent message - definitely a new message { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Fixed the issues." } } [​](https://agentclientprotocol.com/rfds/message-id#what-we-propose-to-do-about-it) What we propose to do about it --------------------------------------------------------------------------------------------------------------------- Add a `messageId` field to `AgentMessageChunk`, `UserMessageChunk`, `AgentThoughtChunk` session updates and `PromptRequest`, and a `userMessageId` field to `PromptResponse`. These fields would: 1. **Provide stable message identification** - Each message gets a unique identifier that remains constant across all chunks of that message. 2. **Enable reliable message boundary detection** - Clients can definitively determine when a new message starts by observing a change in `messageId`. 3. **Create an extension point for future features** - Message IDs can be referenced in future protocol enhancements. ### [​](https://agentclientprotocol.com/rfds/message-id#proposed-structure) Proposed Structure When the Client sends a user message via `session/prompt`, it can optionally include a `messageId`: { "jsonrpc": "2.0", "id": 2, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "messageId": "4c12d49b-729c-4086-bfed-5b82e9a53400", "prompt": [\ {\ "type": "text",\ "text": "Can you analyze this code?"\ }\ ] } } The Agent echoes this as `userMessageId` in the response (or assigns one if the client didn’t provide it): { "jsonrpc": "2.0", "id": 2, "result": { "userMessageId": "4c12d49b-729c-4086-bfed-5b82e9a53400", "stopReason": "end_turn" } } For agent message chunks, the Agent generates and includes a `messageId`: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "ea87d0e7-beb8-484a-a404-94a30b78a5a8", "content": { "type": "text", "text": "Let me analyze your code..." } } } } If the Agent sends `user_message_chunk` updates (e.g., during `session/load`), it uses the user message ID: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "user_message_chunk", "messageId": "4c12d49b-729c-4086-bfed-5b82e9a53400", "content": { "type": "text", "text": "Can you..." } } } } The `messageId` field would be: * **Optional** on `agent_message_chunk`, `user_message_chunk`, `agent_thought_chunk` updates and `session/prompt` requests (as `messageId`) * **Optional** in `session/prompt` responses (as `userMessageId`) * **UUID format** - Both clients and agents MUST use UUID format to ensure collision avoidance * **Unique per message** within a session * **Stable across chunks** - all chunks belonging to the same message share the same `messageId` * **Opaque** - Implementations treat it as an identifier without parsing its structure * **Dual-origin** - Clients generate IDs for user messages, agents generate IDs for agent messages ### [​](https://agentclientprotocol.com/rfds/message-id#message-id-acknowledgment) Message ID Acknowledgment When a Client includes `messageId` in a `session/prompt` request, the Agent’s response behavior indicates whether message IDs are supported: * **If the Agent supports message IDs** and records the client-provided ID, it MUST include `userMessageId` in the response with the same value. * **If the Agent assigns its own ID** (when the client didn’t provide one), it SHOULD include `userMessageId` in the response so the client knows the assigned ID. * **If the Agent does not support message IDs** or chooses not to record it, it MUST omit `userMessageId` from the response. Clients MUST interpret the absence of `userMessageId` in the response as confirmation that the message ID was **not recorded**. Clients SHOULD NOT rely on that ID for subsequent operations (e.g., message editing, truncation, or forking) when `userMessageId` is absent. This creates predictable behavior: the presence of `userMessageId` in the response is an explicit acknowledgment that the Agent recorded the ID and will recognize it in future operations. [​](https://agentclientprotocol.com/rfds/message-id#shiny-future) Shiny future --------------------------------------------------------------------------------- Once this feature exists: 1. **Clear message boundaries** - Clients can reliably render distinct message bubbles in the UI, even when multiple messages of the same type are sent consecutively. 2. **Better streaming UX** - Clients know exactly which message element to append chunks to, enabling smoother visual updates. 3. **Foundation for editing** - With stable message identifiers, future protocol versions could add: * `message/edit` - Agent updates the content of a previously sent message * `message/delete` - Agent removes a message from the conversation * `message/replace` - Agent replaces an entire message with new content 4. **Message metadata** - Future capabilities could reference messages by ID: * Annotations or reactions to specific messages * Citation or cross-reference between messages * Tool calls that reference which message triggered them 5. **Enhanced debugging** - Implementations can trace message flow more easily with explicit IDs in logs and debugging tools. Example future editing capability: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "message_update", "messageId": "ea87d0e7-beb8-484a-a404-94a30b78a5a8", "updateType": "replace", "content": { "type": "text", "text": "Actually, let me correct that analysis..." } } } } [​](https://agentclientprotocol.com/rfds/message-id#implementation-details-and-plan) Implementation details and plan ----------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/message-id#phase-1-core-protocol-changes) Phase 1: Core Protocol Changes 1. **Update schema** (`schema/schema.json`): * Add optional `messageId` field (type: `string`) to `ContentChunk` (used by `AgentMessageChunk`, `UserMessageChunk`, `AgentThoughtChunk`) * Add optional `messageId` field (type: `string`) to `PromptRequest` (client-provided) * Add optional `userMessageId` field (type: `string`) to `PromptResponse` (echoed or agent-assigned) 2. **Update Rust SDK** (`rust/client.rs` and `rust/agent.rs`): * Add `message_id: Option` field to `ContentChunk` struct * Add `message_id: Option` field to `PromptRequest` struct * Add `user_message_id: Option` field to `PromptResponse` struct * Update serialization to include `messageId`/`userMessageId` in JSON output when present 3. **Update TypeScript SDK** (if applicable): * Add `messageId` field to corresponding types 4. **Update documentation** (`docs/protocol/prompt-turn.mdx`): * Document the `messageId` and `userMessageId` fields and their semantics * Clarify that clients can provide `messageId` for user messages in prompt requests * Clarify that agents echo the ID as `userMessageId` in prompt responses * Clarify that agents generate `messageId` for agent messages in chunks * Add examples showing message boundaries * Explain that `messageId` changes indicate new messages ### [​](https://agentclientprotocol.com/rfds/message-id#phase-2-reference-implementation) Phase 2: Reference Implementation 5. **Update example agents**: * Modify example agents to generate and include `messageId` in chunks * Use simple ID generation (e.g., incrementing counter, UUID) * Demonstrate consistent IDs across chunks of the same message 6. **Update example clients**: * Update clients to consume `messageId` field * Use IDs to properly group chunks into messages * Demonstrate clear message boundary rendering ### [​](https://agentclientprotocol.com/rfds/message-id#backward-compatibility) Backward Compatibility The `messageId` field is **optional** to ensure this is a non-breaking change. Agents SHOULD include the `messageId` field, but it is not required for v1 compatibility. Features that rely on `messageId` (such as future message editing capabilities) will implicitly require the field to be present - Agents that don’t provide it simply won’t support those features. Making this field required will be considered for a future v2 version of the protocol after wide adoption. [​](https://agentclientprotocol.com/rfds/message-id#frequently-asked-questions) Frequently asked questions ------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/message-id#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? 1. **Continue using `_meta` field** - This is the current workaround but: * Not standardized across implementations * Doesn’t signal semantic importance * Easy to overlook or implement inconsistently 2. **Detect message boundaries heuristically** - Clients could infer boundaries from timing, content types, or session state: * Unreliable and fragile * Doesn’t work for all scenarios (e.g., consecutive same-type messages) * Creates inconsistent behavior across implementations 3. **Use explicit “message start/end” markers** - Wrap messages with begin/end notifications: * More complex protocol interaction * Requires additional notifications * More state to track on both sides 4. **Agent-only message IDs** - Have the Agent generate all IDs (including for user messages): * Consistent with protocol patterns (`sessionId`, `terminalId`, `toolCallId`) * But creates complexity for returning user message IDs (response comes after streaming) * Not all agents support passing user message IDs through * Clients may need IDs immediately for deduplication or multi-client scenarios The proposed approach with `messageId` is: * **Simple** - Just one new field with clear semantics * **Flexible** - Enables future capabilities without further protocol changes * **Practical** - Clients generate IDs for their messages, agents for theirs * **Collision-safe** - UUID format ensures uniqueness across both sides ### [​](https://agentclientprotocol.com/rfds/message-id#who-generates-message-ids) Who generates message IDs? **Both clients and agents can generate message IDs**, each for their own messages: * **For user messages**: The Client generates a UUID and includes it as `messageId` in the `session/prompt` request. The Agent echoes this ID as `userMessageId` in the response to confirm it was recorded. If the client doesn’t provide one, the Agent MAY assign one and return it in the response so the client knows the assigned ID. * **For agent messages**: The Agent generates the UUID when creating its response and includes it in session update chunks. This differs from other protocol identifiers (`sessionId`, `terminalId`, `toolCallId`) which are agent-generated, but provides practical benefits: * **Immediate availability** - Clients have the ID as soon as they send the message, without waiting for a response * **Deduplication** - Clients can use IDs to deduplicate messages on `session/load` or when echoing to multiple clients * **Collision-safe** - UUID format ensures uniqueness without coordination * **Adapter-friendly** - Adapters for agents that don’t support message IDs can simply not pass them through ### [​](https://agentclientprotocol.com/rfds/message-id#should-this-field-be-required-or-optional) Should this field be required or optional? The field is **optional** for v1 to ensure backward compatibility. Agents SHOULD include `messageId`, but it is not required. Features that depend on `messageId` (such as message editing) will implicitly require it - if an Agent doesn’t provide `messageId`, those features simply won’t be available. Making this field required will be considered for a future v2 version of the protocol. ### [​](https://agentclientprotocol.com/rfds/message-id#what-format-should-message-ids-use) What format should message IDs use? Both clients and agents **MUST** use UUID format for message IDs. This is required because both sides can generate IDs, and UUID format ensures: * **No collisions** - UUIDs are globally unique without coordination between client and agent * **Interoperability** - Both sides use the same format, so either side can rely on uniqueness guarantees * **Simplicity** - Standard libraries available in all languages While `messageId` values are UUIDs, implementations **SHOULD** treat them as opaque strings when reading/comparing them, and not parse or interpret their internal structure. ### [​](https://agentclientprotocol.com/rfds/message-id#what-about-message-ids-across-session-loads) What about message IDs across session loads? When a session is loaded via `session/load`, the Agent may: * Preserve original message IDs if replaying the conversation history * Generate new message IDs if only exposing current state The protocol doesn’t require message IDs to be stable across session loads, though Agents MAY choose to make them stable if their implementation supports it. ### [​](https://agentclientprotocol.com/rfds/message-id#does-this-apply-to-other-session-updates-like-tool-calls-or-plan-updates) Does this apply to other session updates like tool calls or plan updates? This RFD addresses `agent_message_chunk`, `user_message_chunk`, and `agent_thought_chunk` updates. Other session update types (like `tool_call`, `plan`) already have their own identification mechanisms: * Tool calls use `toolCallId` * Plan entries can be tracked by their position in the `entries` array Future RFDs may propose extending `messageId` to other update types if use cases emerge. [​](https://agentclientprotocol.com/rfds/message-id#revision-history) Revision history ----------------------------------------------------------------------------------------- * **2026-02-17**: Added “Message ID Acknowledgment” section to clarify that presence/absence of `userMessageId` in response indicates whether the Agent recorded the ID; clarified that UUID format is MUST (not SHOULD) since both sides generate IDs; renamed response field to `userMessageId` for clarity (request keeps `messageId`) * **2026-01-29**: Updated to allow both clients and agents to generate message IDs using UUID format * **2025-11-09**: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/session-delete) [Represent deleted files in diff\ \ Next](https://agentclientprotocol.com/rfds/diff-delete) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/message-id#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/message-id#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/message-id#what-we-propose-to-do-about-it) * [Proposed Structure](https://agentclientprotocol.com/rfds/message-id#proposed-structure) * [Message ID Acknowledgment](https://agentclientprotocol.com/rfds/message-id#message-id-acknowledgment) * [Shiny future](https://agentclientprotocol.com/rfds/message-id#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/message-id#implementation-details-and-plan) * [Phase 1: Core Protocol Changes](https://agentclientprotocol.com/rfds/message-id#phase-1-core-protocol-changes) * [Phase 2: Reference Implementation](https://agentclientprotocol.com/rfds/message-id#phase-2-reference-implementation) * [Backward Compatibility](https://agentclientprotocol.com/rfds/message-id#backward-compatibility) * [Frequently asked questions](https://agentclientprotocol.com/rfds/message-id#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/message-id#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Who generates message IDs?](https://agentclientprotocol.com/rfds/message-id#who-generates-message-ids) * [Should this field be required or optional?](https://agentclientprotocol.com/rfds/message-id#should-this-field-be-required-or-optional) * [What format should message IDs use?](https://agentclientprotocol.com/rfds/message-id#what-format-should-message-ids-use) * [What about message IDs across session loads?](https://agentclientprotocol.com/rfds/message-id#what-about-message-ids-across-session-loads) * [Does this apply to other session updates like tool calls or plan updates?](https://agentclientprotocol.com/rfds/message-id#does-this-apply-to-other-session-updates-like-tool-calls-or-plan-updates) * [Revision history](https://agentclientprotocol.com/rfds/message-id#revision-history) --- # Forking of existing sessions - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-fork#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Forking of existing sessions [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@josevalim](https://github.com/josevalim) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/session-fork#elevator-pitch) Elevator pitch --------------------------------------------------------------------------------------- > What are you proposing to change? We propose adding the ability to “fork” a new session based on an existing one. This will allow us to use the current conversation as context to generate pull request descriptions, summaries, etc. without polluting the user history. [​](https://agentclientprotocol.com/rfds/session-fork#status-quo) Status quo ------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? Imagine we want to summarize the current conversation to use it in a future chat. If we send a message asking for the summary, it will become part of its context, affecting future user interactions. Therefore we want to be able to fork a session, issue additional messages, and then close the fork. [​](https://agentclientprotocol.com/rfds/session-fork#what-we-propose-to-do-about-it) What we propose to do about it ----------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? To add a “session/fork” method. [​](https://agentclientprotocol.com/rfds/session-fork#shiny-future) Shiny future ----------------------------------------------------------------------------------- > How will things will play out once this feature exists? We will be able to implement functionality that requires using the current chat without polluting its history, ranging from summaries to potentially subagents. I can also see this feature being extended in the future to support an optional message ID, so the fork happens at a specific message, allowing clients to implement functionality like editing previous messages and similar. [​](https://agentclientprotocol.com/rfds/session-fork#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? We propose to add a new “session/fork” method. Agents must declare this option is available by returning `session: { fork : {} }` in its capabilities. The object is reserved to declare future capabilities, such as forking from a specific message, a tool call, or similar. Then the client would be able to request a fork of the given session: { "jsonrpc": "2.0", "id": 1, "method": "session/fork", "params": { "sessionId": "sess_789xyz", "cwd": "...", "mcpServers": [...] } } The request expects the same options as `session/load`, such as `cwd` and `mcpServers`. Similarly, the agent would respond with optional data such as config options, the same as `session/load`. Agents may reply with an error if forking of that specific session or with the given options is not supported, for example if the agent does not support forking with a different working directory than the initial session. [​](https://agentclientprotocol.com/rfds/session-fork#frequently-asked-questions) Frequently asked questions --------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? **Q: Should a new method be introduced or should “session/new” be expanded?** They must be different because they will effectively require different options. For example, “session/new” has options such as capabilities and MCP which are not recommended to be set when forking, as the context being forked was built with other tools, and forking may accept a messageId for checkpoints. **Q: Should fork only accept the `sessionId` or also other options, similar to `session/load`?** Initially, we proposed to only accept the `sessionId`, but this would make it more difficult to allow forking of inactive sessions in agents like `claude-agent-acp`, as Claude does not retain the configured MCP servers of a session. Limiting fork to only already active sessions would limit its usefulness. Moreover, allowing to pass different options also allows features like dynamically adding MCP servers to existing sessions to work by forking them with the new options, if the agent supports it. If it does not, the client can still show an appropriate error message. ### [​](https://agentclientprotocol.com/rfds/session-fork#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? None. This proposal is inspired by the abilities exposed in Claude Agent SDK. It must be validated against other agents too. [​](https://agentclientprotocol.com/rfds/session-fork#revision-history) Revision history ------------------------------------------------------------------------------------------- * 2025-11-17: Mentioned capabilities format, updated FAQ. * 2025-11-20: Added request format and updated capabilities format. * 2025-12-10: Adjust fork options to align with `session/load`. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/updates) [Request Cancellation Mechanism\ \ Next](https://agentclientprotocol.com/rfds/request-cancellation) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-fork#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-fork#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-fork#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/session-fork#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-fork#implementation-details-and-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-fork#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/session-fork#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/session-fork#revision-history) --- # Request Cancellation Mechanism - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/request-cancellation#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Request Cancellation Mechanism [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [Artem Bukhonov](https://github.com/nerzhulart) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/request-cancellation#elevator-pitch) Elevator pitch ----------------------------------------------------------------------------------------------- Introduce a standardized per-request cancellation mechanism for the Agent Client Protocol, inspired by the [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#cancelRequest) , to enable a more granular cancellation of requests where individual JSON-RPC requests can be cancelled one by one. [​](https://agentclientprotocol.com/rfds/request-cancellation#status-quo) Status quo --------------------------------------------------------------------------------------- The JSON-RPC specification doesn’t define any standard mechanism for request cancellation and leaves it up to the implementation. Currently, ACP has some ad-hoc cancellation mechanisms for specific features (like prompt turn cancellation via `session/cancel`), but lacks a general-purpose, per-request cancellation mechanism. This creates the following inconveniences: * cancellation should be handled for each feature separately * some languages that support handy cancellation mechanisms (C#, Kotlin, etc.) can’t implement general-purpose request cancellation using ACP low-level machinery, and rather developers should manually call per-feature cancellation methods [​](https://agentclientprotocol.com/rfds/request-cancellation#what-we-propose-to-do-about-it) What we propose to do about it ------------------------------------------------------------------------------------------------------------------------------- Implement an **optional** `$/cancel_request` notification method (inspired by the Language Server Protocol) to both Agent and Client that uses JSON-RPC 2.0 notification format, allowing either party (client or agent) to cancel any outstanding request by its ID. The mechanism will be: * **Optional**: Not all implementations may support this feature, but it is recommended for those that do. * **Flexible**: Provides two response options when cancellation is received: 1. An error response with the standard cancellation error code (-32800) 2. A valid response with partial or cancelled data (when meaningful partial results exist) This approach balances flexibility with standardization, allowing implementations to opt-in to cancellation support while providing predictable behavior when enabled. [​](https://agentclientprotocol.com/rfds/request-cancellation#shiny-future) Shiny future ------------------------------------------------------------------------------------------- Once implemented, this enables: * **SDK integration layer**: Default mechanism that ACP SDKs can automatically wire to native language cancellation (C# CancellationToken, Kotlin Job, Go context.Context, JavaScript AbortController, etc.) * Individual JSON-RPC request cancellation without affecting other concurrent requests * Universal fallback for any request when feature-specific cancellation methods don’t exist * Consistent cancellation behavior from both external `$/cancel_request` and internal cancellation triggers * Standard error response (`-32800`) or partial results when requests are cancelled regardless of cancellation source In a future version, we could potentially deprecate the `session/cancel` notification in favor of the more general approach, as it would still provide the same functionality but with more flexibility and consistency. [​](https://agentclientprotocol.com/rfds/request-cancellation#implementation-details-and-plan) Implementation details and plan --------------------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/request-cancellation#protocol-changes) Protocol Changes #### [​](https://agentclientprotocol.com/rfds/request-cancellation#cancellation-method) Cancellation Method Add the `$/cancel_request` notification method to the JSON-RPC protocol: interface CancelNotification { method: "$/cancel_request"; params: { requestId: string | number; // ID of request to cancel }; } ### [​](https://agentclientprotocol.com/rfds/request-cancellation#cancellation-behavior) Cancellation Behavior Either party can send `$/cancel_request` to cancel requests. Notifications whose methods start with ‘/′aremessageswhichareprotocolimplementationdependentandmightnotbeimplementableinallclientsoragents.Forexampleiftheimplementationusesasinglethreadedsynchronousprogramminglanguagethenthereislittleitcandotoreacttoa‘/' are messages which are protocol implementation dependent and might not be implementable in all clients or agents. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a \`/′aremessageswhichareprotocolimplementationdependentandmightnotbeimplementableinallclientsoragents.Forexampleiftheimplementationusesasinglethreadedsynchronousprogramminglanguagethenthereislittleitcandotoreacttoa‘/cancel\_request\` notification. If an agent or client receives notifications starting with ’$/’ it is free to ignore the notification. The **receiving party** is **NOT** required to: * Perform special handling for unsupported cancellation requests * Return custom errors for unsupported `$/cancel_request` notifications #### [​](https://agentclientprotocol.com/rfds/request-cancellation#cancellation-processing) Cancellation Processing When a `$/cancel_request` notification is received by a supporting implementation, it: * **MUST** cancel the corresponding request activity and all nested activities related to that request * **MAY** finish sending any pending notifications before responding * **MUST** send one of these responses for the original request: * A valid response with appropriate data (such as partial results or cancellation marker) * An error response with code [`-32800` (Request Cancelled)](https://agentclientprotocol.com/rfds/schema#errorcode) #### [​](https://agentclientprotocol.com/rfds/request-cancellation#internal-cancellation) Internal Cancellation Requests can also be cancelled internally by the executing party without receiving `$/cancel_request`: * **Client-side examples**: User closes IDE, switches to different project, file becomes unavailable * **Agent-side examples**: LLM context limit reached, internal timeout, resource constraints When internal cancellation occurs, the executing party **SHOULD**: 1. Send the same `-32800` (Cancelled) error response as if `$/cancel_request` was received 2. Ensure consistent behavior regardless of cancellation source ### [​](https://agentclientprotocol.com/rfds/request-cancellation#error-code) Error Code Add standard JSON-RPC error code `-32800` for cancelled requests: * Code: `-32800` * Message: “Request cancelled” * Meaning: Execution of the method was aborted either due to a cancellation request from the caller or because of resource constraints or shutdown. [​](https://agentclientprotocol.com/rfds/request-cancellation#frequently-asked-questions) Frequently asked questions ----------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/request-cancellation#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? The core need is to add **granular cancellation** as a general mechanism for individual JSON-RPC requests, while **feature-specific cancellation methods** (like `session/cancel`) remain useful for cases requiring additional domain semantics. We selected the **LSP-style `$/cancel_request`** approach because: * Serves as a **default cancellation layer** that SDK implementations can easily map to native language cancellation mechanisms * Proven pattern familiar to developers from LSP ecosystem * Works across all JSON-RPC transports (HTTP, WebSocket, stdio, pipes) * Provides universal fallback when feature-specific cancellation doesn’t exist * Complements existing feature-specific methods rather than replacing them ### [​](https://agentclientprotocol.com/rfds/request-cancellation#how-does-this-relate-to-existing-cancellation-mechanisms-like-session/cancel) How does this relate to existing cancellation mechanisms like `session/cancel`? The `$/cancel_request` mechanism is complementary to feature-specific cancellation: * `$/cancel_request`: Generic cancellation for any JSON-RPC request by ID * `session/cancel`: Feature-specific cancellation with additional semantics (e.g., cancels entire prompt turn context, triggers specific cleanup logic) Both mechanisms serve different purposes: **Feature-specific methods** like `session/cancel` provide: * Domain-specific semantics and behavior * Structured cleanup for complex operations * Context-aware cancellation logic **Generic `$/cancel_request`** provides: * Default cancellation layer that bridges programming language cancellation mechanisms (C# CancellationToken, Kotlin Job, Go context.Context, etc.) with ACP * Universal fallback for any request when no feature-specific method exists * Simple ID-based targeting for SDK convenience * Standardized error responses Implementations can use both: feature-specific methods for rich semantics, and `$/cancel_request` for simple per-request cancellation. Note: it is possible that `session/cancel` could be replaced by the more generic `$/cancel_request` in future versions of the protocol. #### [​](https://agentclientprotocol.com/rfds/request-cancellation#example-cascading-cancellation-flow) Example: Cascading Cancellation Flow ### [​](https://agentclientprotocol.com/rfds/request-cancellation#what-happens-if-a-request-completes-before-the-cancellation-is-processed) What happens if a request completes before the cancellation is processed? If a request completes normally before the cancellation notification is processed, the implementation should: 1. Send the normal response (not a cancellation error) 2. Ignore the subsequent cancellation notification for that request ID This ensures clients always receive meaningful responses and prevents race conditions. ### [​](https://agentclientprotocol.com/rfds/request-cancellation#how-should-implementations-handle-cascading-cancellation) How should implementations handle cascading cancellation? When a request is cancelled, implementations should: 1. Cancel the primary request activity 2. Propagate cancellation to any nested/child requests 3. Clean up resources associated with the entire request tree 4. Send cancellation responses for all affected requests This ensures complete cleanup and prevents resource leaks. [​](https://agentclientprotocol.com/rfds/request-cancellation#revision-history) Revision history --------------------------------------------------------------------------------------------------- * 2025-11-13: Initial version converted from PR #183 * 2025-12-05: Updated with current implementation. * 2025-12-09: Mirror LSP behavior. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/session-fork) [Meta Field Propagation Conventions\ \ Next](https://agentclientprotocol.com/rfds/meta-propagation) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/request-cancellation#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/request-cancellation#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/request-cancellation#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/request-cancellation#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/request-cancellation#implementation-details-and-plan) * [Protocol Changes](https://agentclientprotocol.com/rfds/request-cancellation#protocol-changes) * [Cancellation Method](https://agentclientprotocol.com/rfds/request-cancellation#cancellation-method) * [Cancellation Behavior](https://agentclientprotocol.com/rfds/request-cancellation#cancellation-behavior) * [Cancellation Processing](https://agentclientprotocol.com/rfds/request-cancellation#cancellation-processing) * [Internal Cancellation](https://agentclientprotocol.com/rfds/request-cancellation#internal-cancellation) * [Error Code](https://agentclientprotocol.com/rfds/request-cancellation#error-code) * [Frequently asked questions](https://agentclientprotocol.com/rfds/request-cancellation#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/request-cancellation#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [How does this relate to existing cancellation mechanisms like session/cancel?](https://agentclientprotocol.com/rfds/request-cancellation#how-does-this-relate-to-existing-cancellation-mechanisms-like-session%2Fcancel) * [Example: Cascading Cancellation Flow](https://agentclientprotocol.com/rfds/request-cancellation#example-cascading-cancellation-flow) * [What happens if a request completes before the cancellation is processed?](https://agentclientprotocol.com/rfds/request-cancellation#what-happens-if-a-request-completes-before-the-cancellation-is-processed) * [How should implementations handle cascading cancellation?](https://agentclientprotocol.com/rfds/request-cancellation#how-should-implementations-handle-cascading-cancellation) * [Revision history](https://agentclientprotocol.com/rfds/request-cancellation#revision-history) --- # Agent Extensions via ACP Proxies - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/proxy-chains#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Agent Extensions via ACP Proxies [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [nikomatsakis](https://github.com/nikomatsakis) [​](https://agentclientprotocol.com/rfds/proxy-chains#elevator-pitch) Elevator pitch --------------------------------------------------------------------------------------- > What are you proposing to change? Enable a universal agent extension mechanism via ACP proxies, components that sit between a client and an agent. Proxies can intercept and transform messages, enabling composable architectures where techniques like context injection, tool coordination, and response filtering can be extracted into reusable components. [​](https://agentclientprotocol.com/rfds/proxy-chains#status-quo) Status quo ------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? The AI agent ecosystem has developed many extension mechanisms: AGENTS.md files, Claude Code plugins, rules files, hooks, MCP servers, etc. Of these, only MCP servers have achieved real standardization across the ecosystem. However, MCP servers are fundamentally limited because they sit “behind” the agent. They can provide tools and respond to function calls, but they cannot: * **Inject or modify prompts** before they reach the agent * **Add global context** that persists across conversations * **Transform responses** before they reach the user * **Coordinate between multiple agents** or manage conversation flow As a result, valuable techniques like context management and response processing remain locked within individual agent implementations, with no way to extract and reuse them across different agents. [​](https://agentclientprotocol.com/rfds/proxy-chains#what-we-propose-to-do-about-it) What we propose to do about it ----------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? We propose implementing _agent extensions_ via ACP _proxies_, a new kind of component that sits between the client and the agent, forwarding (and potentially altering or introducing) messages. Because proxies can do anything a client could do, they serve as a universal extension mechanism that can subsume AGENTS.md, hooks, MCP servers, etc. Proxies are limited to the customizations exposed by ACP itself, so they would benefit from future ACP extensions like mechanisms to customize system prompts. However, they can already handle the majority of common extension use cases through message interception and transformation. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#proxying-in-theory) Proxying in theory Conceptually, proxies work like a chain where messages flow through each component: ### [​](https://agentclientprotocol.com/rfds/proxy-chains#proxying-in-practice-the-role-of-the-conductor) Proxying in practice: the role of the conductor To allow for proxy isolation, our design does not have proxies communicate directly with their successor in the chain. Instead, there is a central _conductor_ component that orchestrates messages moving between components. We add one ACP method for proxy communication: * **`proxy/successor`**: Used bidirectionally - proxies send it to forward messages to their successor, and the conductor sends it to deliver messages from the successor back to the proxy Here’s how a single message flows through the system: [​](https://agentclientprotocol.com/rfds/proxy-chains#shiny-future) Shiny future ----------------------------------------------------------------------------------- > How will things play out once this feature exists? ### [​](https://agentclientprotocol.com/rfds/proxy-chains#user-experience-and-editor-integration) User experience and editor integration We expect editors to expose the ability to install proxies in the same way they currently support adding MCP servers - in fact, the distinction probably doesn’t matter to users. Both are “extensions” that add capabilities to their AI workflow. When proxies are installed, editors would not start the agent directly, but instead invoke the conductor with the configured proxy chain. From the user’s perspective, they’re just getting enhanced agent capabilities - the proxy chain architecture remains transparent. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#language-specific-proxy-ecosystems) Language-specific proxy ecosystems The monolithic nature of agent development has meant that most of the “action” happens within agents. We wish to invert this, with agents trending towards simple agentic loops, and the creativity being pushed outwards into the broader ecosystem. The Symposium project is one example exploring this concept, with a focus on Rust. The idea is to give Rust users an automatic set of extensions based on the dependencies they are using. These extensions would be packaged up as SACP proxies using WebAssembly for portability and sandboxing. Symposium aims to become the standard “Rust ACP experience” by providing both core Rust tooling and a framework for Rust libraries to contribute their own proxy components. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#standardized-ide-capabilities) Standardized IDE capabilities Proxy infrastructure could also enable editors to expose standardized IDE capabilities (diagnostics, file system access, terminal APIs) to agents via MCP servers provided by proxies. This keeps the core ACP protocol focused on agent communication while allowing rich IDE integration through the proxy layer. [​](https://agentclientprotocol.com/rfds/proxy-chains#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/proxy-chains#component-roles) Component roles Each ACP proxy chain forms a sequence of components: The **client** and **agent** are _terminal_ roles - the client has only a successor (no predecessor), and the agent has only a predecessor (no successor). Proxies are _non-terminal_ - they have both a predecessor and a successor, forwarding messages between them. The **conductor** is a special component that orchestrates proxy chains. It spawns and manages proxy components, routes messages between them, and handles initialization. From the client’s perspective, the conductor appears to be an ordinary agent: We provide a canonical conductor implementation in Rust (`sacp-conductor`). Most editors would use this conductor directly to host proxies and agents, though they could also reimplement conductor functionality if needed. ACP defines client and agent as superroles, each with two specializations: **Example Architecture:** ### [​](https://agentclientprotocol.com/rfds/proxy-chains#proxy-initialization-protocol) Proxy initialization protocol Components discover their role from the initialization method they receive: * **Proxies** receive `proxy/initialize` - they have a successor and should forward messages * **Agents** receive `initialize` - they are terminal (no successor) and process messages directly The `proxy/initialize` request has the same parameters as `initialize` and expects a standard `InitializeResponse`. The only difference is the method name, which signals to the component that it should operate as a proxy. **Conductor behavior:** * The conductor MUST send `proxy/initialize` to all proxy components * The conductor MUST send `initialize` to the final agent component (if any) * When a proxy forwards an `initialize` via `proxy/successor`, the conductor determines whether the successor is another proxy or the agent, and sends `proxy/initialize` or `initialize` respectively. **Proxy behavior:** * A proxy that receives `proxy/initialize` knows it has a successor * The proxy SHOULD forward requests it does not understand * The proxy SHOULD preserve metadata fields when forwarding messages Note: A conductor can be configured to run in either terminal mode (expecting `initialize`) or proxy mode (expecting `proxy/initialize`), enabling nested proxy chains. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#mcp-over-acp-support) MCP-over-ACP support Proxies that provide MCP servers use the [MCP-over-ACP transport](https://agentclientprotocol.com/rfds/mcp-over-acp) mechanism. The conductor always advertises `mcpCapabilities.acp: true` to proxies and handles bridging for agents that don’t support native ACP transport. All proxies MUST respond to `proxy/initialize` with the MCP-over-ACP capability enabled. When the conductor sends `proxy/initialize`, proxies should be prepared to handle `mcp/connect`, `mcp/message`, and `mcp/disconnect` messages for any MCP servers they provide. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#message-reference) Message reference **Initialization:** // Conductor initializes a proxy (proxy knows it has a successor) {"method": "proxy/initialize", "params": } // Conductor initializes the agent (standard ACP) {"method": "initialize", "params": } Both methods use the same parameters as the standard ACP `InitializeRequest` and expect a standard `InitializeResponse`. **Proxy messages:** // Proxy sends message to successor, or conductor delivers message from successor // (same method, direction determined by sender) { "method": "proxy/successor", "params": { "method": "", "params": , "meta": { ... } // optional metadata } } The inner message fields (`method`, `params`) are flattened into the params object. Whether the wrapped message is a request or notification is determined by the presence of an `id` field in the outer JSON-RPC envelope, following JSON-RPC conventions. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#examples-non-normative) Examples (non-normative) The following sequence diagrams illustrate common proxy chain scenarios for implementers. #### [​](https://agentclientprotocol.com/rfds/proxy-chains#initialization-of-a-4-component-proxy-chain) Initialization of a 4-component proxy chain This shows the initialization flow for: Terminal Client → Conductor → Context Proxy → Tool Filter Proxy → Terminal Agent #### [​](https://agentclientprotocol.com/rfds/proxy-chains#context-providing-proxy-with-session-notifications) Context-providing proxy with session notifications This example shows how a proxy can handle initialization and forward session notifications. Sparkle (a collaborative AI framework) runs an embodiment sequence during session creation. This demonstrates how proxies can run initialization sequences during session creation while transparently forwarding all session notifications back to the client. [​](https://agentclientprotocol.com/rfds/proxy-chains#frequently-asked-questions) Frequently asked questions --------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/proxy-chains#why-use-a-separate-proxy/initialize-method-instead-of-a-capability) Why use a separate `proxy/initialize` method instead of a capability? Earlier designs used a `"proxy": true` capability in the `InitializeRequest` and required proxies to echo it back in the response. This felt awkward because it wasn’t really a capability negotiation - it was more of a “you must operate as a proxy” directive. Using a distinct method makes the contract clearer: if you receive `proxy/initialize`, you’re a proxy with a successor; if you receive `initialize`, you’re the terminal agent. There’s no capability dance, no risk of misconfiguration, and components know their role immediately from the method name. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#how-do-proxies-subsume-existing-agent-extension-mechanisms) How do proxies subsume existing agent extension mechanisms? Because proxies sit between the client and agent, they can replicate the functionality of existing extension mechanisms: * **AGENTS.md files**: Proxies can inject context and instructions into prompts before they reach the agent * **Claude Code plugins/skills**: Proxies can add contextual data for available skills and provide MCP resources with detailed skill instructions that are provided on-demand when requested by the agent * **MCP servers**: Proxies can provide tools via [MCP-over-ACP](https://agentclientprotocol.com/rfds/mcp-over-acp) and handle tool callbacks * **Subagents**: Proxies can create “subagents” by initiating new sessions and coordinating between multiple agent instances * **Hooks and steering files**: Proxies can modify conversation flow by intercepting requests and responses * **System prompt customization**: Proxies can switch between predefined session modes or prepend system messages to prompts The key advantage is that proxy-based extensions work with any ACP-compatible agent without requiring agent-specific integration or modification. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#how-do-proxies-work-with-mcp-servers) How do proxies work with MCP servers? Proxies can provide MCP servers via [MCP-over-ACP transport](https://agentclientprotocol.com/rfds/mcp-over-acp) , enabling a single proxy to add context, provide tools, and handle callbacks with full awareness of the conversation state. The conductor always advertises `mcpCapabilities.acp: true` to proxies, regardless of whether the downstream agent supports it natively. When the agent doesn’t support ACP transport, the conductor handles bridging transparently - spawning stdio shims or HTTP servers that the agent connects to normally, then relaying messages to/from the proxy’s ACP channel. This means proxy authors don’t need to worry about agent compatibility - they implement MCP-over-ACP, and the conductor handles the rest. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#are-there-any-limitations-to-what-proxies-can-do) Are there any limitations to what proxies can do? Yes, proxies are limited to what is available through the ACP protocol itself. They can intercept and transform any ACP message, but they cannot access capabilities that ACP doesn’t expose. For example, proxies cannot directly modify an agent’s system prompt or context window - they can only switch between predefined session modes (which may affect system prompts) or prepend additional messages to prompts. Similarly, proxies cannot access internal agent state, model parameters, or other implementation details that aren’t exposed through ACP messages. This is actually a feature - it ensures that proxy-based extensions remain portable across different agent implementations and don’t rely on agent-specific internals. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#why-not-just-cascade-acp-commands-without-protocol-changes) Why not just cascade ACP commands without protocol changes? One alternative is to make proxies be ordinary agents that internally create and manage their successors. This works (HTTP proxies operate this way) but requires each proxy to understand the full chain and know how to start its successors. This couples proxies to transport mechanisms, process management, and chain configuration. Changing transports, reordering the chain, or inserting a new proxy requires modifying predecessor configurations. The conductor design decouples proxies from their successors. Proxies send messages “to successor” and receive messages “from successor” without knowing who that successor is, how it’s started, or what transport it uses. This enables: * Changing transport protocols or process management without recompiling proxies * Shipping proxies as low-capability WASM containers that need only a single communication channel * Reordering, adding, or removing proxies through configuration rather than code changes The tradeoff is protocol complexity, but this complexity lives in the conductor (implemented once) rather than being duplicated across proxy implementations. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#why-do-all-messages-go-through-the-conductor-instead-of-direct-proxy-to-proxy-communication) Why do all messages go through the conductor instead of direct proxy-to-proxy communication? Even with a conductor, proxies could communicate directly with their successors after the conductor sets up connections. Routing all messages through the conductor further minimizes proxy responsibilities to a single communication channel. This supports running proxies as isolated WebAssembly components with minimal capabilities. It also removes redundant logic: without the conductor routing messages, each proxy would need to manage connections to its successor. The conductor handles process management, capability negotiation, and message routing, allowing proxies to focus on transformation logic. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#how-does-the-standard-conductor-implementation-work) How does the standard conductor implementation work? The `sacp-conductor` reference implementation can form trees of proxy chains. It can be configured to run in proxy mode (expecting `proxy/initialize`) or terminal mode (expecting `initialize`). When the last proxy in its managed chain sends a message to its successor, the conductor forwards that message to its own parent conductor (if in proxy mode) or to the final agent (if in terminal mode). This enables hierarchical structures like: client → conductor1 → final-agent ↓ manages proxy-a → conductor2 → proxy-d ↓ manages proxy-b → proxy-c The conductor handles process management, capability negotiation, and message routing, but these are implementation details - the protocol only specifies the message formats and capability requirements. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#what-about-security-concerns-with-proxy-chains) What about security concerns with proxy chains? Proxy components can intercept and modify all communication, so trust is essential - similar to installing any software. Users are responsible for the components they choose to run. We plan to explore WebAssembly-based proxies which will offer some measure of sandboxing but such components could still modify prompts in unknown or malicious ways. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#what-about-performance-implications-of-the-proxy-chain) What about performance implications of the proxy chain? Our architecture does introduce additional message passing - each proxy in the chain adds extra hops as messages flow through the conductor. However, these messages are typically small and inexpensive, particularly when compared to the latency of actual LLM inference. For messages that contain significant quantities of data (large file contents, extensive context), we may wish to have the conductor store that data centrally and introduce a “reference” mechanism so that most proxies don’t have to inspect or copy large payloads unless they specifically need to transform them. The benefits of composability typically outweigh the minimal latency costs for human-paced development interactions. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#what-happens-when-proxy-components-crash-or-misbehave) What happens when proxy components crash or misbehave? The conductor manages component lifecycles: * Failed components are restarted automatically where possible * Component crashes don’t affect the rest of the chain * Graceful degradation by bypassing failed components * Clear error reporting to help users debug configuration issues ### [​](https://agentclientprotocol.com/rfds/proxy-chains#can-proxy-chains-be-nested-or-form-trees) Can proxy chains be nested or form trees? Yes! The conductor can itself run in proxy mode, enabling hierarchical structures: client → proxy1 → conductor (proxy mode) → final-agent ↓ manages p1 → p2 → p3 This enables complex compositions while maintaining clean interfaces. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#how-could-proxy-chains-support-multi-agent-scenarios-in-the-future) How could proxy chains support multi-agent scenarios in the future? The current design assumes a linear chain where each proxy has a single successor. To support M:N topologies where a proxy communicates with multiple peers (e.g., a research coordinator dispatching to multiple specialized agents), we could extend `proxy/successor` with an optional `peer` field: { "method": "proxy/successor", "params": { "method": "prompt", "params": { ... }, "peer": "research-agent" } } When `peer` is omitted, the message goes to the default successor (backwards compatible with the current linear chain model). When present, it specifies which peer the message is intended for. The `proxy/initialize` response could be extended to enumerate available peers, enabling proxies to discover and coordinate between multiple downstream components. ### [​](https://agentclientprotocol.com/rfds/proxy-chains#what%E2%80%99s-the-current-implementation-status) What’s the current implementation status? A prototype version of this proposal has been implemented and is available on crates.io as the crates: * `sacp` — base ACP protocol SDK * `sacp-tokio` — adds specific utilities for use with the `tokio` runtime * `sacp-proxy` — extensions for implementing a proxy * `sacp-rmcp` — adds specific proxy extension traits for bridging to the rmcp crate * `sacp-conductor` — reference conductor implementation The canonical sources for those crates is currently the \[symposium-dev/symposium-acp\] repository. However, copies have been upstreamed to the [agentclientprotocol/rust-sdk](https://github.com/agentclientprotocol/rust-sdk/tree/main/src/sacp-conductor) repository and, if and when this RFD is accepted, that will become the canonical home. [​](https://agentclientprotocol.com/rfds/proxy-chains#revision-history) Revision history ------------------------------------------------------------------------------------------- * Initial draft based on working implementation in symposium-acp repository. * Split MCP-over-ACP transport into [separate RFD](https://agentclientprotocol.com/rfds/mcp-over-acp) to enable independent use by any ACP component. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/agent-telemetry-export) [MCP-over-ACP: MCP Transport via ACP Channels\ \ Next](https://agentclientprotocol.com/rfds/mcp-over-acp) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/proxy-chains#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/proxy-chains#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/proxy-chains#what-we-propose-to-do-about-it) * [Proxying in theory](https://agentclientprotocol.com/rfds/proxy-chains#proxying-in-theory) * [Proxying in practice: the role of the conductor](https://agentclientprotocol.com/rfds/proxy-chains#proxying-in-practice-the-role-of-the-conductor) * [Shiny future](https://agentclientprotocol.com/rfds/proxy-chains#shiny-future) * [User experience and editor integration](https://agentclientprotocol.com/rfds/proxy-chains#user-experience-and-editor-integration) * [Language-specific proxy ecosystems](https://agentclientprotocol.com/rfds/proxy-chains#language-specific-proxy-ecosystems) * [Standardized IDE capabilities](https://agentclientprotocol.com/rfds/proxy-chains#standardized-ide-capabilities) * [Implementation details and plan](https://agentclientprotocol.com/rfds/proxy-chains#implementation-details-and-plan) * [Component roles](https://agentclientprotocol.com/rfds/proxy-chains#component-roles) * [Proxy initialization protocol](https://agentclientprotocol.com/rfds/proxy-chains#proxy-initialization-protocol) * [MCP-over-ACP support](https://agentclientprotocol.com/rfds/proxy-chains#mcp-over-acp-support) * [Message reference](https://agentclientprotocol.com/rfds/proxy-chains#message-reference) * [Examples (non-normative)](https://agentclientprotocol.com/rfds/proxy-chains#examples-non-normative) * [Initialization of a 4-component proxy chain](https://agentclientprotocol.com/rfds/proxy-chains#initialization-of-a-4-component-proxy-chain) * [Context-providing proxy with session notifications](https://agentclientprotocol.com/rfds/proxy-chains#context-providing-proxy-with-session-notifications) * [Frequently asked questions](https://agentclientprotocol.com/rfds/proxy-chains#frequently-asked-questions) * [Why use a separate proxy/initialize method instead of a capability?](https://agentclientprotocol.com/rfds/proxy-chains#why-use-a-separate-proxy%2Finitialize-method-instead-of-a-capability) * [How do proxies subsume existing agent extension mechanisms?](https://agentclientprotocol.com/rfds/proxy-chains#how-do-proxies-subsume-existing-agent-extension-mechanisms) * [How do proxies work with MCP servers?](https://agentclientprotocol.com/rfds/proxy-chains#how-do-proxies-work-with-mcp-servers) * [Are there any limitations to what proxies can do?](https://agentclientprotocol.com/rfds/proxy-chains#are-there-any-limitations-to-what-proxies-can-do) * [Why not just cascade ACP commands without protocol changes?](https://agentclientprotocol.com/rfds/proxy-chains#why-not-just-cascade-acp-commands-without-protocol-changes) * [Why do all messages go through the conductor instead of direct proxy-to-proxy communication?](https://agentclientprotocol.com/rfds/proxy-chains#why-do-all-messages-go-through-the-conductor-instead-of-direct-proxy-to-proxy-communication) * [How does the standard conductor implementation work?](https://agentclientprotocol.com/rfds/proxy-chains#how-does-the-standard-conductor-implementation-work) * [What about security concerns with proxy chains?](https://agentclientprotocol.com/rfds/proxy-chains#what-about-security-concerns-with-proxy-chains) * [What about performance implications of the proxy chain?](https://agentclientprotocol.com/rfds/proxy-chains#what-about-performance-implications-of-the-proxy-chain) * [What happens when proxy components crash or misbehave?](https://agentclientprotocol.com/rfds/proxy-chains#what-happens-when-proxy-components-crash-or-misbehave) * [Can proxy chains be nested or form trees?](https://agentclientprotocol.com/rfds/proxy-chains#can-proxy-chains-be-nested-or-form-trees) * [How could proxy chains support multi-agent scenarios in the future?](https://agentclientprotocol.com/rfds/proxy-chains#how-could-proxy-chains-support-multi-agent-scenarios-in-the-future) * [What’s the current implementation status?](https://agentclientprotocol.com/rfds/proxy-chains#what%E2%80%99s-the-current-implementation-status) * [Revision history](https://agentclientprotocol.com/rfds/proxy-chains#revision-history) --- # Additional Workspace Roots for Session Lifecycle Requests - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/additional-directories#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Additional Workspace Roots for Session Lifecycle Requests [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [egor-baranov](https://github.com/egor-baranov) * Champion: [benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/additional-directories#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------------------- > What are you proposing to change? ACP currently standardizes `cwd` on session lifecycle requests, but does not define a standard way to declare additional filesystem roots for a session. This RFD proposes an optional field: additionalDirectories?: string[] on: * `NewSessionRequest` * `ResumeSessionRequest` * `ForkSessionRequest` * `LoadSessionRequest` and an optional capability: sessionCapabilities.additionalDirectories?: {} `cwd` remains the primary working directory. `additionalDirectories` expands filesystem scope only. It does not replace `cwd`, define directory contents, or introduce new RPC methods. [​](https://agentclientprotocol.com/rfds/additional-directories#status-quo) Status quo ----------------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? ACP currently allows a client to identify one primary workspace root through `cwd`. That is sufficient for single-root projects, but it does not provide a standard way to expose additional roots in multi-root repositories or environments where project code, shared instructions, skills, or mounted workspaces live at separate absolute paths. Without a standardized field, clients and agents must rely on implementation-specific conventions. `_meta` is not appropriate for interoperable workspace-root semantics. This leaves multi-root behavior fragmented and less predictable across implementations. [​](https://agentclientprotocol.com/rfds/additional-directories#what-we-propose-to-do-about-it) What we propose to do about it --------------------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? Add `additionalDirectories?: string[]` to the session lifecycle request schemas listed above and to `session/list`, and define protocol-level validation and semantics for it. The proposal is scoped to session lifecycle requests, session discovery requests, and session discovery metadata only: * no new RPC methods are added; * `cwd` remains unchanged as the primary root; and * ACP remains agnostic to directory naming and directory contents. Agents advertise support with `sessionCapabilities.additionalDirectories`. Clients MUST gate usage on that capability. This proposal also extends `SessionInfo` returned by `session/list` with authoritative `additionalDirectories` state, and allows `session/list` to filter on `cwd` plus `additionalDirectories`, so clients that support session discovery can recover and query the active root set for listed sessions. `session/load` and `session/resume` nevertheless remain explicit-list only: omitting `additionalDirectories` or supplying an empty array means no additional roots are activated for the resulting session, while a non-empty array-valued `additionalDirectories` becomes the complete resulting additional-root list for that request. [​](https://agentclientprotocol.com/rfds/additional-directories#shiny-future) Shiny future --------------------------------------------------------------------------------------------- > How will things will play out once this feature exists? Clients can declare multi-root workspace scope in a standard way while preserving existing `cwd` behavior. Agents can treat a session as an ordered root set starting with `cwd` and followed by any array-valued `additionalDirectories` entries, and apply the same discovery and resource-handling behavior they already apply under `cwd` to the other declared roots. Security boundaries remain explicit: declared roots communicate intended scope, while sandboxing, approvals, and OS permissions continue to govern actual access. [​](https://agentclientprotocol.com/rfds/additional-directories#implementation-details-and-plan) Implementation details and plan ----------------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/additional-directories#goals-/-non-goals) Goals / Non-goals #### [​](https://agentclientprotocol.com/rfds/additional-directories#goals) Goals * Standardize additional workspace roots on session lifecycle entry points. * Preserve `cwd` as the primary working directory for the session. * Define clear validation and error-handling rules. * Enable generic multi-root discovery and resource handling by agents across all declared roots. * Expand the filesystem scope without changing the existing RPC method structure. #### [​](https://agentclientprotocol.com/rfds/additional-directories#non-goals) Non-goals * Defining any required directory names or layouts, such as `.agents/`, `skills/`, or `./`. * Defining a standard instruction, skill, or configuration file format. * Replacing `cwd` with a list-valued field. * Changing relative-path semantics. * Adding new RPC methods. * Defining per-root read/write permissions in the protocol. ### [​](https://agentclientprotocol.com/rfds/additional-directories#schema-changes) Schema changes The following optional property is added to each request type named above: additionalDirectories?: string[] The following optional property is also added to `ListSessionsRequest`: additionalDirectories?: string[] The following optional property is also added to `SessionInfo`: additionalDirectories?: string[] The following capability is added to `SessionCapabilities`: additionalDirectories?: {} Clients MUST send `additionalDirectories` only when `sessionCapabilities.additionalDirectories` is present. If an agent advertises `sessionCapabilities.additionalDirectories` and also supports `session/list`, any `SessionInfo.additionalDirectories` value it returns is the authoritative ordered additional-root list for that session. Agents MAY omit the field when there are no additional roots, and clients MUST treat an omitted field the same as `[]`. If an agent advertises `sessionCapabilities.additionalDirectories` and also supports `session/list`, `ListSessionsRequest.additionalDirectories` filters sessions by exact match on the authoritative ordered additional-root list when the field is present and non-empty. When both `cwd` and a non-empty `additionalDirectories` are present on `session/list`, both filters apply. Omitting the field or supplying an empty array means no additional-root filter is applied. If adopted, the session-setup, session-list, and filesystem documentation will need corresponding updates so they describe the effective root set rather than `cwd` alone as the session filesystem context or boundary. ### [​](https://agentclientprotocol.com/rfds/additional-directories#capability-advertisement-example) Capability advertisement example { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "additionalDirectories": {} } } } } ### [​](https://agentclientprotocol.com/rfds/additional-directories#session/list-example) `session/list` example When an agent supports both `sessionCapabilities.additionalDirectories` and `session/list`, clients may filter by `cwd`, `additionalDirectories`, or both. Each returned `SessionInfo` includes the authoritative additional-root list for that session: { "jsonrpc": "2.0", "id": 5, "method": "session/list", "params": { "cwd": "/home/user/project", "additionalDirectories": [\ "/home/user/shared-lib",\ "/home/user/product-docs"\ ] } } { "jsonrpc": "2.0", "id": 5, "result": { "sessions": [\ {\ "sessionId": "sess_abc123",\ "cwd": "/home/user/project",\ "additionalDirectories": [\ "/home/user/shared-lib",\ "/home/user/product-docs"\ ],\ "updatedAt": "2026-03-24T12:00:00Z"\ }\ ] } } ### [​](https://agentclientprotocol.com/rfds/additional-directories#field-definition) Field definition `additionalDirectories` has the following properties: * The field MUST be an array of strings when present. * Each entry MUST be an absolute path under the same platform path rules used for `cwd`. * Empty strings MUST be rejected. * `null` is not a valid value for the field or for any entry. ACP does not define a wire-level lexical normalization algorithm for `cwd` or `additionalDirectories`. Clients SHOULD remove exact duplicate path strings before sending the request. Clients SHOULD also avoid entries whose path string exactly matches `cwd`. Overlapping or nested roots are not semantically redundant for ACP purposes: because discovery across the effective ordered root list is ordered and implementation-defined, such entries MAY affect behavior even when they do not change the union of accessible paths. Agents MAY remove exact duplicate path strings, including entries identical to `cwd`, provided doing so preserves the first occurrence order of the remaining entries and does not expand scope. For `session/list` filtering, matching is against the session’s authoritative ordered additional-root list as surfaced in `SessionInfo.additionalDirectories`. Implementations that normalize or canonicalize path strings for comparison SHOULD apply the same platform-appropriate rule consistently to stored session state, `SessionInfo.additionalDirectories`, and `ListSessionsRequest.additionalDirectories`. ### [​](https://agentclientprotocol.com/rfds/additional-directories#semantics) Semantics `cwd` remains the primary working directory for the session. It continues to define: * the default base for relative-path resolution; * the primary working directory semantics already defined by ACP; and * the primary workspace root for clients or agents that distinguish one root as primary. `additionalDirectories` defines zero or more extra filesystem roots that are part of the same session workspace scope. The effective ordered root list for a session is: * `[cwd]` when `additionalDirectories` is omitted or is an empty array * `[cwd, ...additionalDirectories]` when `additionalDirectories` is a non-empty array This ordered root list has the following semantics: * The session workspace is a multi-root workspace. * The roots form a logical union of accessible roots. * The roots are not a virtual overlay filesystem. * ACP does not define shadowing, mount, or merge semantics between roots. * Relative paths MUST continue to resolve only against `cwd`. A file path is in scope for the session if, after platform-appropriate path resolution for access control, it is contained within at least one declared root. This proposal expands workspace scope only. It does not imply that all in-scope paths are writable, nor does it bypass client capability checks, user approvals, sandbox rules, or operating-system permissions. ### [​](https://agentclientprotocol.com/rfds/additional-directories#request-specific-behavior) Request-specific behavior For `NewSessionRequest`, the resulting additional root list is: * `additionalDirectories` when present with a non-empty array value; * otherwise `[]`. For `LoadSessionRequest` and `ResumeSessionRequest`: * when `additionalDirectories` is present with a non-empty array value, it is the complete resulting list of additional roots for the active session, even if that list differs from the session’s previously stored additional roots; * when omitted or present as an empty array, the resulting additional root list is `[]`. Agents MUST NOT implicitly reactivate stored additional roots that were not supplied on the `session/load` or `session/resume` request. Supplying `additionalDirectories` on `session/load` or `session/resume` is always allowed when the capability is advertised, and doing so may preserve, replace, reduce, or expand the session’s previously stored additional-root list for the resulting active session, subject to validation and policy checks. Clients that need to preserve a session’s additional roots across restarts or across client instances MUST obtain, persist, or reconstruct the full list and resend it on load or resume. When `session/list` is available, `SessionInfo.additionalDirectories` provides the authoritative current additional-root list for that purpose. For `ForkSessionRequest`: * when `additionalDirectories` is present with a non-empty array value, it is a full replacement list for the forked session; * when omitted or present as an empty array, the resulting additional root list is `[]`. Agents MUST NOT implicitly inherit additional roots from the source session unless the implementation can prove that the active root list is already authoritative to the requesting client on the current connection. Otherwise, the agent MUST fail the request or require the client to provide the full list explicitly. For all lifecycle methods, an agent MAY reject the request if the resulting roots are incompatible with stored session state, fork semantics, sandbox policy, or other implementation constraints. An agent MUST NOT silently drop unsupported or unauthorized roots. This RFD defines lifecycle-time workspace scope only. It does not define mid-session mutation of `additionalDirectories`. ### [​](https://agentclientprotocol.com/rfds/additional-directories#agent-behavior-expectations) Agent behavior expectations Agents MUST treat paths under `additionalDirectories` as part of the session’s accessible workspace scope in the same sense as paths under `cwd`, subject to capabilities and permissions actually available for that session. For any discovery, indexing, or resource-loading behavior an agent applies under `cwd` such as instructions, skills, configuration, or other agent-specific artifacts, the agent SHOULD apply the same behavior to each declared root in `additionalDirectories`, subject to the same capabilities and permissions. If an implementation resolves conflicts across multiple roots, earlier roots in the effective ordered root list SHOULD take precedence over later roots. Conflict resolution within a single root remains implementation-defined. ACP does not define: * required directory names or layouts; * the contents or file formats of discovered artifacts; * whether an agent MUST perform any discovery at all; or * how discovered artifacts affect prompting or execution. Implementations MAY define such behavior independently, but ACP remains agnostic to directory contents. ### [​](https://agentclientprotocol.com/rfds/additional-directories#validation-and-error-handling) Validation and error handling An agent receiving a session lifecycle request with `additionalDirectories` MUST validate the field before creating, loading, resuming, or forking the session. The agent MUST reject the request if: * `additionalDirectories` is not an array; * any entry is not a string; * any entry is empty; * any entry is not absolute. `invalid_params` is the RECOMMENDED error class for malformed values. If an entry is syntactically valid but cannot be granted under the implementation’s policy, sandbox, or user-consent model, the agent MUST fail the request with an appropriate error. The agent MUST NOT silently ignore invalid, unauthorized, or unsupported entries and proceed with a reduced root set. ACP does not require a specific lexical normalization algorithm for validating `cwd` or `additionalDirectories`. Implementations that normalize or canonicalize path strings for comparison, deduplication, or storage SHOULD apply the same platform-appropriate rule consistently to both fields, but authorization and containment checks MUST NOT rely solely on lexical normalization. When enforcing root boundaries for subsequent file access, implementations SHOULD use canonical or real paths where available and MUST prevent escapes through symlinks, junctions, mount points, or equivalent mechanisms. If the implementation cannot safely determine whether a path is within an allowed root, it MUST fail closed. ### [​](https://agentclientprotocol.com/rfds/additional-directories#client-responsibilities) Client responsibilities A client that sends `additionalDirectories`: * MUST send only paths it intends to expose to the session; * MUST ensure those paths are absolute; * MUST send the full intended active additional root list on `session/load` and `session/resume`; * SHOULD obtain user consent or otherwise act consistently with the client’s trust and permission model; * SHOULD remove exact duplicate path strings and entries identical to `cwd` before sending; and * MUST NOT assume an agent will infer extra roots from project metadata, directory conventions, or prior session state. If a client mediates filesystem access through ACP client capabilities such as `fs/read_text_file` and `fs/write_text_file`, it MUST enforce the effective root set for that session when authorizing path-based access. ACP’s filesystem methods are client-mediated and operate on absolute paths, so the client remains responsible for boundary enforcement in those flows. When the client learns about an existing session through `session/list`, it SHOULD use `SessionInfo.additionalDirectories` together with `cwd` as the authoritative current root set for those checks until a subsequent lifecycle request establishes a different one. If a client launches an agent with direct filesystem access, `additionalDirectories` is not, by itself, a sandbox. Clients that need root boundaries to be enforced in that deployment model SHOULD apply operating-system or runtime sandboxing consistent with the declared root set. ### [​](https://agentclientprotocol.com/rfds/additional-directories#examples) Examples #### [​](https://agentclientprotocol.com/rfds/additional-directories#session/new) `session/new` { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "additionalDirectories": [\ "/home/user/shared-lib",\ "/home/user/product-docs"\ ], "mcpServers": [] } } #### [​](https://agentclientprotocol.com/rfds/additional-directories#session/load) `session/load` { "jsonrpc": "2.0", "id": 2, "method": "session/load", "params": { "sessionId": "sess_abc123", "cwd": "/home/user/project", "additionalDirectories": [\ "/home/user/shared-lib",\ "/home/user/product-docs"\ ], "mcpServers": [] } } #### [​](https://agentclientprotocol.com/rfds/additional-directories#session/resume) `session/resume` { "jsonrpc": "2.0", "id": 3, "method": "session/resume", "params": { "sessionId": "sess_abc123", "cwd": "/home/user/project", "additionalDirectories": [\ "/home/user/shared-lib",\ "/home/user/product-docs"\ ], "mcpServers": [] } } #### [​](https://agentclientprotocol.com/rfds/additional-directories#session/fork) `session/fork` { "jsonrpc": "2.0", "id": 4, "method": "session/fork", "params": { "sessionId": "sess_abc123", "cwd": "/home/user/project", "additionalDirectories": [\ "/home/user/shared-lib",\ "/home/user/product-docs"\ ], "mcpServers": [] } } ### [​](https://agentclientprotocol.com/rfds/additional-directories#security-considerations) Security considerations `additionalDirectories` increases the set of filesystem paths the agent may be able to inspect or modify. This increases the potential impact of user error, client misconfiguration, or insufficient sandboxing. Clients MUST NOT send directories that the user has not granted to the session under the client’s trust model. Clients SHOULD default to explicit selection or other clear workspace-grant semantics for roots outside the primary project directory. Agents and clients MUST treat root enforcement as a security boundary when they claim to enforce it. Boundary checks MUST account for symlink and path-resolution attacks. Ambiguous cases MUST fail closed. This field does not create a new privilege model. All existing permission prompts, approval flows, filesystem capabilities, sandbox controls, and operating-system access rules continue to apply. Because ACP does not define directory contents, agents SHOULD avoid assuming that any discovered file under an additional root is safe, authoritative, or intended for automatic execution. Discovery is not equivalent to trust. ### [​](https://agentclientprotocol.com/rfds/additional-directories#backward-compatibility) Backward compatibility This proposal is additive at the schema level. Requests that omit `additionalDirectories` behave exactly as they do today. Existing clients that do not need multi-root support require no changes. Updated agents MUST continue to accept requests that do not include the field. Older implementations may validate request objects strictly against older schemas and MAY reject unknown fields. Clients therefore MUST gate usage on `sessionCapabilities.additionalDirectories`. This proposal intentionally does not extend the responses to `session/new`, `session/load`, `session/resume`, or `session/fork` to surface authoritative additional-root state directly. That remains consistent with existing ACP response shapes, which also do not return `cwd`. Instead, when `session/list` is supported, `SessionInfo.additionalDirectories` exposes the authoritative ordered additional-root list for listed sessions. `SessionInfoUpdate` remains unchanged because this RFD does not define mid-session mutation of `additionalDirectories`. Clients that need multi-root continuity across `session/load` or `session/resume` MUST still send the full intended list explicitly. `session/list` filtering no longer remains `cwd`\-only: sessions may be filtered by `cwd`, by `additionalDirectories`, or by both together. Sessions that differ by `additionalDirectories` are therefore both distinguishable and filterable through `SessionInfo.additionalDirectories` and `ListSessionsRequest.additionalDirectories`. This RFD does not add a new RPC method. It also does not change the meaning of `cwd`, `sessionId`, or `mcpServers`. ### [​](https://agentclientprotocol.com/rfds/additional-directories#drawbacks) Drawbacks * It expands the workspace surface area and therefore the risk of accidental data exposure. * It introduces another dimension of interoperability for clients and agents to test. * It does not standardize discovery behavior, so implementations may still differ in how they use additional roots. * Older strict validators may reject the new field until they adopt the updated schema. [​](https://agentclientprotocol.com/rfds/additional-directories#frequently-asked-questions) Frequently asked questions ------------------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/additional-directories#why-not-use-_meta) Why not use `_meta`? `_meta` is intended for implementation-specific custom data. A standardized workspace-root concept should be protocol-level, typed, and interoperable across implementations. ### [​](https://agentclientprotocol.com/rfds/additional-directories#why-not-replace-cwd-with-workspaceroots) Why not replace `cwd` with `workspaceRoots`? `cwd` already has established semantics as the primary working directory. Replacing it with an array would blur relative-path behavior, reduce clarity for existing implementations, and create a larger migration surface. ### [​](https://agentclientprotocol.com/rfds/additional-directories#does-acp-define-agents-skills-or-instruction-directory-conventions) Does ACP define `.agents`, `skills`, or instruction directory conventions? No. ACP does not define `.agents`, `skills`, or other instruction directory conventions. This proposal only defines additional accessible roots. Agents SHOULD handle resources under `additionalDirectories` the same way they handle analogous resources under `cwd`, but the names, layouts, and file formats of those resources remain implementation-defined. ### [​](https://agentclientprotocol.com/rfds/additional-directories#how-should-clients-handle-older-agents-that-may-not-support-this-field) How should clients handle older agents that may not support this field? Clients MUST gate `additionalDirectories` on `sessionCapabilities.additionalDirectories`. If support is absent, clients SHOULD omit the field and preserve existing behavior. ### [​](https://agentclientprotocol.com/rfds/additional-directories#why-not-restore-stored-roots-on-session/load-or-session/resume-when-the-field-is-omitted) Why not restore stored roots on `session/load` or `session/resume` when the field is omitted? Even with `SessionInfo.additionalDirectories` available through `session/list`, implicit restoration would still let an agent reactivate filesystem scope that the current request did not state explicitly. That is undesirable for clients that do not use `session/list`, for clients resuming a session by ID without first listing it, and for clients that want request-time control over the active root set. This proposal therefore keeps load and resume explicit-list only for additional roots: omitting the field or supplying an empty array activates none, while supplying a non-empty array is explicitly allowed and sets the complete resulting additional-root list for that request. ### [​](https://agentclientprotocol.com/rfds/additional-directories#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? Alternatives considered: * putting extra roots in `_meta`; * adding a new workspace-configuration RPC method; and * requiring clients to copy or mount everything under `cwd`. This proposal is preferred because it is additive, keeps `cwd` semantics stable, avoids new methods, and standardizes multi-root scope at session lifecycle boundaries. [​](https://agentclientprotocol.com/rfds/additional-directories#revision-history) Revision history ----------------------------------------------------------------------------------------------------- * 2026-03-24: Initial draft. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/next-edit-suggestions) [Configurable LLM Providers\ \ Next](https://agentclientprotocol.com/rfds/custom-llm-endpoint) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/additional-directories#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/additional-directories#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/additional-directories#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/additional-directories#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/additional-directories#implementation-details-and-plan) * [Goals / Non-goals](https://agentclientprotocol.com/rfds/additional-directories#goals-%2F-non-goals) * [Goals](https://agentclientprotocol.com/rfds/additional-directories#goals) * [Non-goals](https://agentclientprotocol.com/rfds/additional-directories#non-goals) * [Schema changes](https://agentclientprotocol.com/rfds/additional-directories#schema-changes) * [Capability advertisement example](https://agentclientprotocol.com/rfds/additional-directories#capability-advertisement-example) * [session/list example](https://agentclientprotocol.com/rfds/additional-directories#session%2Flist-example) * [Field definition](https://agentclientprotocol.com/rfds/additional-directories#field-definition) * [Semantics](https://agentclientprotocol.com/rfds/additional-directories#semantics) * [Request-specific behavior](https://agentclientprotocol.com/rfds/additional-directories#request-specific-behavior) * [Agent behavior expectations](https://agentclientprotocol.com/rfds/additional-directories#agent-behavior-expectations) * [Validation and error handling](https://agentclientprotocol.com/rfds/additional-directories#validation-and-error-handling) * [Client responsibilities](https://agentclientprotocol.com/rfds/additional-directories#client-responsibilities) * [Examples](https://agentclientprotocol.com/rfds/additional-directories#examples) * [session/new](https://agentclientprotocol.com/rfds/additional-directories#session%2Fnew) * [session/load](https://agentclientprotocol.com/rfds/additional-directories#session%2Fload) * [session/resume](https://agentclientprotocol.com/rfds/additional-directories#session%2Fresume) * [session/fork](https://agentclientprotocol.com/rfds/additional-directories#session%2Ffork) * [Security considerations](https://agentclientprotocol.com/rfds/additional-directories#security-considerations) * [Backward compatibility](https://agentclientprotocol.com/rfds/additional-directories#backward-compatibility) * [Drawbacks](https://agentclientprotocol.com/rfds/additional-directories#drawbacks) * [Frequently asked questions](https://agentclientprotocol.com/rfds/additional-directories#frequently-asked-questions) * [Why not use \_meta?](https://agentclientprotocol.com/rfds/additional-directories#why-not-use-_meta) * [Why not replace cwd with workspaceRoots?](https://agentclientprotocol.com/rfds/additional-directories#why-not-replace-cwd-with-workspaceroots) * [Does ACP define .agents, skills, or instruction directory conventions?](https://agentclientprotocol.com/rfds/additional-directories#does-acp-define-agents-skills-or-instruction-directory-conventions) * [How should clients handle older agents that may not support this field?](https://agentclientprotocol.com/rfds/additional-directories#how-should-clients-handle-older-agents-that-may-not-support-this-field) * [Why not restore stored roots on session/load or session/resume when the field is omitted?](https://agentclientprotocol.com/rfds/additional-directories#why-not-restore-stored-roots-on-session%2Fload-or-session%2Fresume-when-the-field-is-omitted) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/additional-directories#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/additional-directories#revision-history) --- # Configurable LLM Providers - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/custom-llm-endpoint#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Configurable LLM Providers [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@anna239](https://github.com/anna239) , [@xtmq](https://github.com/xtmq) [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#elevator-pitch) Elevator pitch ---------------------------------------------------------------------------------------------- > What are you proposing to change? Add the ability for clients to discover and configure agent LLM providers (identified by `id`) via dedicated provider methods: * `providers/list` * `providers/set` * `providers/disable` This allows clients to route LLM requests through their own infrastructure (proxies, gateways, or self-hosted models) without agents needing to know about this configuration in advance. [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#status-quo) Status quo -------------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? ACP does not currently define a standard method for configuring LLM providers. In practice, provider configuration is usually done via environment variables or agent-specific config files. That creates several problems: * No standard way for clients to discover what providers an agent exposes * No standard way to update one specific provider by id * No standard way to disable a specific provider at runtime while preserving provider discoverability * Secret-bearing values in headers are difficult to handle safely when configuration must be round-tripped This particularly affects: * **Client proxies**: clients want to route agent traffic through their own proxies, for example to add headers or logging * **Enterprise deployments**: organizations want to route LLM traffic through internal gateways for compliance, logging, and cost controls * **Self-hosted models**: users running local servers (vLLM, Ollama, etc.) need to redirect agent traffic to local infrastructure * **API gateways**: organizations using multi-provider routing, rate limiting, and caching need standardized endpoint configuration [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#shiny-future) Shiny future ------------------------------------------------------------------------------------------ > How will things play out once this feature exists? Clients will be able to: 1. Understand whether an agent supports client-managed LLM routing 2. See where the agent is currently sending LLM requests (for example in settings UI) 3. Route agent LLM traffic through their own infrastructure (enterprise proxy, gateway, self-hosted stack) 4. Update routing settings from the client instead of relying on agent-specific env vars 5. Disable a provider when needed and later re-enable it explicitly 6. Apply these settings before starting new work in sessions [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#implementation-details-and-plan) Implementation details and plan -------------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#intended-flow) Intended flow 1. Client initializes and checks `agentCapabilities.providers`. 2. Client calls `providers/list` to discover available providers, their current routing targets (or disabled state), supported protocol types, and whether they are required. 3. Client calls `providers/set` to apply new (required) configuration for a specific provider id. 4. Client may call `providers/disable` when a non-required provider should be disabled. 5. Client creates or loads sessions. ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#capability-advertisement) Capability advertisement The agent advertises support with an empty object capability: interface AgentCapabilities { // ... existing fields ... /** * Provider configuration support. * If present, the agent supports providers/list, providers/set, and providers/disable. */ providers?: {}; } If `providers` is absent, clients must treat provider methods as unsupported. ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#types) Types /** * Well-known API protocol identifiers for LLM providers. * * This is an open string type: agents and clients MUST handle unknown * protocol identifiers gracefully. * * Protocol names beginning with `_` are free for custom use, like other * ACP extension methods. Protocol names that do not begin with `_` are * reserved for the ACP spec. */ type LlmProtocol = | "anthropic" | "openai" | "azure" | "vertex" | "bedrock" | string; interface ProviderCurrentConfig { /** Protocol currently used by this provider. */ apiType: LlmProtocol; /** Base URL currently used by this provider. */ baseUrl: string; } interface ProviderInfo { /** Provider identifier, for example "main" or "openai". */ id: string; /** Supported protocol types for this provider. */ supported: LlmProtocol[]; /** * Whether this provider is mandatory and cannot be disabled via providers/disable. * If true, clients must not call providers/disable for this id. */ required: boolean; /** * Current effective non-secret routing config. * Null or omitted means provider is disabled. */ current?: ProviderCurrentConfig | null; /** Extension metadata */ _meta?: Record; } ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#providers/list) `providers/list` interface ProvidersListRequest { /** Extension metadata */ _meta?: Record; } interface ProvidersListResponse { /** Configurable providers with current routing info suitable for UI display. */ providers: ProviderInfo[]; /** Extension metadata */ _meta?: Record; } ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#providers/set) `providers/set` `providers/set` updates the full configuration for one provider id. interface ProvidersSetRequest { /** Provider id to configure. */ id: string; /** Protocol type for this provider. */ apiType: LlmProtocol; /** Base URL for requests sent through this provider. */ baseUrl: string; /** * Full headers map for this provider. * May include authorization, routing, or other integration-specific headers. * Omitting this field is equivalent to an empty map (no headers). */ headers?: Record; /** Extension metadata */ _meta?: Record; } interface ProvidersSetResponse { /** Extension metadata */ _meta?: Record; } ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#providers/disable) `providers/disable` interface ProvidersDisableRequest { /** Provider id to disable. */ id: string; /** Extension metadata */ _meta?: Record; } interface ProvidersDisableResponse { /** Extension metadata */ _meta?: Record; } ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#example-exchange) Example exchange **initialize Response:** { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentInfo": { "name": "MyAgent", "version": "2.0.0" }, "agentCapabilities": { "providers": {}, "sessionCapabilities": {} } } } **providers/list Request:** { "jsonrpc": "2.0", "id": 1, "method": "providers/list", "params": {} } **providers/list Response:** { "jsonrpc": "2.0", "id": 1, "result": { "providers": [\ {\ "id": "main",\ "supported": ["bedrock", "vertex", "azure", "anthropic"],\ "required": true,\ "current": {\ "apiType": "anthropic",\ "baseUrl": "http://localhost/anthropic"\ }\ },\ {\ "id": "openai",\ "supported": ["openai"],\ "required": false,\ "current": null\ }\ ] } } **providers/set Request:** { "jsonrpc": "2.0", "id": 2, "method": "providers/set", "params": { "id": "main", "apiType": "anthropic", "baseUrl": "https://llm-gateway.corp.example.com/anthropic/v1", "headers": { "X-Request-Source": "my-ide" } } } **providers/set Response:** { "jsonrpc": "2.0", "id": 2, "result": {} } **providers/disable Request:** { "jsonrpc": "2.0", "id": 3, "method": "providers/disable", "params": { "id": "openai" } } **providers/disable Response:** { "jsonrpc": "2.0", "id": 3, "result": {} } ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#behavior) Behavior 1. **Capability discovery**: agents that support provider methods MUST advertise `agentCapabilities.providers: {}` in `initialize`. Clients SHOULD only call `providers/*` when this capability is present. 2. **Timing and session impact**: provider methods MUST be called after `initialize`. Clients SHOULD configure providers before creating or loading sessions. Agents MAY choose not to apply changes to already running sessions, but SHOULD apply them to sessions created or loaded after the change. 3. **List semantics**: `providers/list` returns configurable providers, their supported protocol types, current effective routing, and `required` flag. Providers SHOULD remain discoverable in list after `providers/disable`. 4. **Client behavior for required providers**: clients SHOULD NOT call `providers/disable` for providers where `required: true`. 5. **Disabled state encoding**: in `providers/list`, `current` omitted or `current: null` means the provider is disabled and MUST NOT be used by the agent for LLM calls. 6. **Set semantics and validation**: `providers/set` replaces the full configuration for the target `id` (`apiType`, `baseUrl`, `headers`); an omitted `headers` field is treated as an empty map. If `id` is unknown, `apiType` is unsupported for that provider, or params are malformed, agents SHOULD return `invalid_params`. 7. **Disable semantics**: `providers/disable` disables the target provider at runtime. A disabled provider MUST appear in `providers/list` with `current` omitted or `current: null`. If target provider has `required: true`, agents MUST return `invalid_params`. Disabling an unknown `id` SHOULD be treated as success (idempotent behavior). 8. **Scope and persistence**: provider configuration is process-scoped and SHOULD NOT be persisted to disk. [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#frequently-asked-questions) Frequently asked questions ---------------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document? ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#what-does-null-mean-in-providers/list) What does `null` mean in `providers/list`? `current` omitted or `current: null` means the provider is disabled. When disabled, the agent MUST NOT route LLM calls through that provider until the client enables it again with `providers/set`. ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-is-there-a-required-flag) Why is there a `required` flag? Some providers are mandatory for agent operation and must not be disabled. `required` lets clients hide or disable the provider-disable action in UI and avoid calling `providers/disable` for those ids. ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-not-a-single-providers/update-method-for-full-list-replacement) Why not a single `providers/update` method for full list replacement? A full-list update means the client must send complete configuration (including `headers`) for all providers every time. If the client wants to change only one provider, it may not know headers for the others. In that case it cannot safely build a correct full-list payload. Also, `providers/list` does not return headers, so the client cannot simply “take what the agent returned” and send it back with one edit. Per-provider methods (`set` and `disable`) avoid this problem and keep updates explicit. ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-doesn%E2%80%99t-providers/list-return-headers) Why doesn’t `providers/list` return headers? Header values may contain secrets and should not be echoed by the agent. `providers/list` is intentionally limited to non-secret routing information (`current.apiType`, `current.baseUrl`). ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-are-providers/list-and-providers/set-payloads-different) Why are `providers/list` and `providers/set` payloads different? `providers/set` accepts `headers`, including secrets, and is write-oriented. `providers/list` is read-oriented and returns only non-secret routing summary (`current`) for UI and capability discovery. ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-is-this-separate-from-initialize-params) Why is this separate from `initialize` params? Clients need capability discovery first, then provider discovery, then configuration. A dedicated method family keeps initialization focused on negotiation and leaves provider mutation to explicit steps. ### [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-not-use-session-config-with-a-provider-category-instead) Why not use `session-config` with a `provider` category instead? `session-config` is a possible alternative, and we may revisit it as the spec evolves. We did not choose it as the primary approach in this proposal because provider routing here needs dedicated semantics that are difficult to express with today’s session config model: * Multiple providers identified by `id`, each with its own lifecycle * Structured payloads (`apiType`, `baseUrl`, full `headers` map) rather than simple scalar values * Explicit discoverable (`providers/list`) and disable (`providers/disable`) semantics Today, `session-config` values are effectively string-oriented and do not define a standard multi-value/structured model for this use case. [​](https://agentclientprotocol.com/rfds/custom-llm-endpoint#revision-history) Revision history -------------------------------------------------------------------------------------------------- * 2026-04-19: Made `ProviderInfo.current` optional in `providers/list`; disabled state may be encoded as omitted `current` or `current: null` * 2026-03-22: Finalized provider disable semantics - `providers/remove` renamed to `providers/disable`, required providers are non-disableable, and disabled state is represented as `current: null` * 2026-03-21: Initial draft of provider configuration API (`providers/list`, `providers/set`, `providers/remove`) * 2026-03-07: Rename “provider” to “protocol” to reflect API compatibility level; make `LlmProtocol` an open string type with well-known values; resolve open questions on identifier standardization and model availability * 2026-03-04: Revised to use dedicated `setLlmEndpoints` method with capability advertisement * 2026-02-02: Initial draft - preliminary proposal to start discussion Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/additional-directories) [Streamable HTTP & WebSocket Transport\ \ Next](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/custom-llm-endpoint#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/custom-llm-endpoint#status-quo) * [Shiny future](https://agentclientprotocol.com/rfds/custom-llm-endpoint#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/custom-llm-endpoint#implementation-details-and-plan) * [Intended flow](https://agentclientprotocol.com/rfds/custom-llm-endpoint#intended-flow) * [Capability advertisement](https://agentclientprotocol.com/rfds/custom-llm-endpoint#capability-advertisement) * [Types](https://agentclientprotocol.com/rfds/custom-llm-endpoint#types) * [providers/list](https://agentclientprotocol.com/rfds/custom-llm-endpoint#providers%2Flist) * [providers/set](https://agentclientprotocol.com/rfds/custom-llm-endpoint#providers%2Fset) * [providers/disable](https://agentclientprotocol.com/rfds/custom-llm-endpoint#providers%2Fdisable) * [Example exchange](https://agentclientprotocol.com/rfds/custom-llm-endpoint#example-exchange) * [Behavior](https://agentclientprotocol.com/rfds/custom-llm-endpoint#behavior) * [Frequently asked questions](https://agentclientprotocol.com/rfds/custom-llm-endpoint#frequently-asked-questions) * [What does null mean in providers/list?](https://agentclientprotocol.com/rfds/custom-llm-endpoint#what-does-null-mean-in-providers%2Flist) * [Why is there a required flag?](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-is-there-a-required-flag) * [Why not a single providers/update method for full list replacement?](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-not-a-single-providers%2Fupdate-method-for-full-list-replacement) * [Why doesn’t providers/list return headers?](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-doesn%E2%80%99t-providers%2Flist-return-headers) * [Why are providers/list and providers/set payloads different?](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-are-providers%2Flist-and-providers%2Fset-payloads-different) * [Why is this separate from initialize params?](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-is-this-separate-from-initialize-params) * [Why not use session-config with a provider category instead?](https://agentclientprotocol.com/rfds/custom-llm-endpoint#why-not-use-session-config-with-a-provider-category-instead) * [Revision history](https://agentclientprotocol.com/rfds/custom-llm-endpoint#revision-history) --- # MCP-over-ACP: MCP Transport via ACP Channels - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/mcp-over-acp#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft MCP-over-ACP: MCP Transport via ACP Channels [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [nikomatsakis](https://github.com/nikomatsakis) [​](https://agentclientprotocol.com/rfds/mcp-over-acp#elevator-pitch) Elevator pitch --------------------------------------------------------------------------------------- > What are you proposing to change? Add support for MCP servers that communicate over ACP channels instead of stdio or HTTP. This enables any ACP component to provide MCP tools and handle callbacks through the existing ACP connection, without spawning separate processes or managing additional transports. [​](https://agentclientprotocol.com/rfds/mcp-over-acp#status-quo) Status quo ------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? ACP and MCP each solve different halves of the problem of interacting with an agent. ACP stands in “front” of the agent, managing sessions, sending prompts, and receiving responses. MCP stands “behind” the agent, providing tools that the agent can use to do its work. Many applications would benefit from being able to be both “in front” of the agent and “behind” it. This would allow a client, for example, to create custom MCP tools that are tailored to a specific request and which live in the client’s address space. The only way to combine ACP and MCP today is to use some sort of “backdoor”, such as opening an HTTP port for the agent to connect to or providing a binary that communicates with IPC. This is inconvenient to implement but also means that clients cannot be properly abstracted and sandboxed, as some of the communication with the agent is going through side channels. Imagine trying to host an ACP component (client, agent, or [agent extension](https://agentclientprotocol.com/rfds/proxy-chains.mdx) ) that runs in a WASM sandbox or even on another machine: for that to work, the ACP protocol has to encompass all of the relevant interactions so that messages can be transmitted properly. [​](https://agentclientprotocol.com/rfds/mcp-over-acp#what-we-propose-to-do-about-it) What we propose to do about it ----------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? We propose adding `"acp"` as a new MCP transport type. When an ACP component (client or proxy) adds an MCP server with ACP transport to a session, tool invocations for that server are routed back through the ACP channel to the component that provided it. This enables patterns like: * A **client** that injects project-aware tools into every session and handles callbacks directly * An **[agent extension](https://agentclientprotocol.com/rfds/proxy-chains.mdx) ** that adds context-aware tools based on the conversation state * A **bridge** that translates ACP-transport MCP servers to stdio for agents that don’t support native ACP transport ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#how-it-works) How it works When the client connects, the agent advertises MCP-over-ACP support via `mcpCapabilities.acp` in its `InitializeResponse`. If supported, the client can add MCP servers to a `session/new` request with `"transport": "acp"` and an `id` that identifies the server: { "tools": { "mcpServers": { "project-tools": { "transport": "acp", "id": "550e8400-e29b-41d4-a716-446655440000" } } } } The `id` is generated by the component providing the MCP server. When the agent connects to the MCP server, an `mcp/connect` message is sent with the MCP server’s `id`. This returns a fresh `connectionId`. MCP messages are then sent back and forth using `mcp/message` requests. Finally, `mcp/disconnect` signals that the connection is closing. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#bridging-and-compatibility) Bridging and compatibility Existing agents don’t support ACP transport for MCP servers. To bridge this gap, a wrapper component can translate between ACP-transport MCP servers and the stdio/HTTP transports that agents already support. The wrapper spawns shim processes or HTTP servers that the agent connects to normally, then relays messages to/from the ACP channel. We’ve implemented this bridging as part of the conductor described in the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains) . The conductor always advertises `mcpCapabilities.acp: true` to its clients, handling the translation transparently regardless of whether the downstream agent supports native ACP transport. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#message-flow-example) Message flow example [​](https://agentclientprotocol.com/rfds/mcp-over-acp#shiny-future) Shiny future ----------------------------------------------------------------------------------- > How will things play out once this feature exists? ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#seamless-tool-injection) Seamless tool injection Components can provide tools without any process management. A Rust development environment could inject cargo-aware tools, a cloud IDE could inject deployment tools, and a security scanner could inject vulnerability checking - all through the same ACP connection they’re already using. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#webassembly-based-tooling) WebAssembly-based tooling Components running in sandboxed environments (like WASM) can provide MCP tools without needing filesystem or process spawning capabilities. The ACP channel is their only interface, and that’s sufficient. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#transparent-bridging) Transparent bridging For agents that don’t natively support ACP transport, intermediaries can transparently bridge: accepting MCP-over-ACP from clients and spawning stdio- or HTTP-based MCP servers that the agent can use normally. This provides backwards compatibility while allowing the ecosystem to adopt ACP transport incrementally. [​](https://agentclientprotocol.com/rfds/mcp-over-acp#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#capability-advertising) Capability advertising Agents advertise MCP-over-ACP support via the [`mcpCapabilities`](https://agentclientprotocol.com/protocol/schema#mcpcapabilities) field in their `InitializeResponse`. We propose adding an `acp` field to this existing structure: { "capabilities": { "mcpCapabilities": { "http": false, "sse": false, "acp": true } } } When `mcpCapabilities.acp` is `true`, the agent can handle MCP servers declared with `"transport": "acp"` natively - it will send `mcp/connect`, `mcp/message`, and `mcp/disconnect` messages through the ACP channel. Clients don’t need to advertise anything - they simply check the agent’s capabilities to determine whether bridging is needed. **Bridging intermediaries**: An intermediary that provides bridging can present `mcpCapabilities.acp: true` to its clients regardless of whether the downstream agent supports it, handling bridging transparently (see [Bridging](https://agentclientprotocol.com/rfds/mcp-over-acp#bridging-for-agents-without-native-support) below). ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#mcp-transport-schema-extension) MCP transport schema extension We extend the MCP JSON schema to include ACP as a transport option: { "type": "object", "properties": { "transport": { "type": "string", "enum": ["stdio", "http", "acp"] } }, "allOf": [\ {\ "if": { "properties": { "transport": { "const": "acp" } } },\ "then": {\ "properties": {\ "id": {\ "type": "string"\ }\ },\ "required": ["id"]\ }\ }\ ] } ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#message-reference) Message reference **Connection lifecycle:** // Establish MCP connection { "method": "mcp/connect", "params": { "acpId": "550e8400-e29b-41d4-a716-446655440000", "meta": { ... } } } // Response: { "connectionId": "conn-123", "meta": { ... } } // Close MCP connection { "method": "mcp/disconnect", "params": { "connectionId": "conn-123", "meta": { ... } } } **MCP message exchange:** // Send MCP message (bidirectional - works agent→client or client→agent) { "method": "mcp/message", "params": { "connectionId": "conn-123", "method": "", "params": { ... }, "meta": { ... } } } The inner MCP message fields (`method`, `params`) are flattened into the params object. Whether the wrapped message is a request or notification is determined by the presence of an `id` field in the outer JSON-RPC envelope, following JSON-RPC conventions. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#routing-by-id) Routing by ID The `acpId` in `mcp/connect` matches the `id` that was provided by the component when it declared the MCP server in `session/new`. The receiving side uses this `id` to route messages to the correct handler. When a component provides multiple MCP servers in a single session, each gets a unique `id`, enabling proper message routing. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#connection-multiplexing) Connection multiplexing Multiple connections to the same MCP server are supported - each `mcp/connect` returns a unique `connectionId`. This allows scenarios where an agent opens multiple concurrent connections to the same tool server. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#bridging-for-agents-without-native-support) Bridging for agents without native support Not all agents will support MCP-over-ACP natively. To maintain compatibility, it is possible to write a bridge that translates ACP-transport MCP servers to transports the agent does support. **Bridging approaches:** * **Stdio shim**: Spawn a small shim process that the agent connects to via stdio. The shim relays MCP messages to/from the ACP channel. This is the most compatible approach since all MCP-capable agents support stdio. * **HTTP bridge**: Run a local HTTP server that the agent connects to. MCP messages are relayed to/from the ACP channel. This works for agents that prefer HTTP transport. **How bridging works:** When a client provides an MCP server with `"transport": "acp"`, and the agent doesn’t advertise `mcpCapabilities.acp: true`, a bridge can: 1. Rewrite the MCP server declaration in `session/new` to use stdio or HTTP transport 2. Spawn the appropriate shim process or HTTP server 3. Relay messages between the shim and the ACP channel From the agent’s perspective, it’s talking to a normal stdio/HTTP MCP server. From the client’s perspective, it’s handling MCP-over-ACP messages. The bridge handles the translation transparently. A first implementation of this bridging exists in the `sacp-conductor` crate, part of the proposed new version of the [ACP Rust SDK](https://github.com/anthropics/rust-sdk) . [​](https://agentclientprotocol.com/rfds/mcp-over-acp#frequently-asked-questions) Frequently asked questions --------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#why-use-a-separate-id-instead-of-server-names) Why use a separate `id` instead of server names? Server names in `mcpServers` are chosen by whoever adds them to the session, and could potentially collide if multiple components add servers. A component-generated `id` provides guaranteed uniqueness and allows the providing component to correlate incoming messages back to the correct session context. This also avoids a potential deadlock: some agents don’t return the session ID until after MCP servers have been initialized. Using a component-generated `id` avoids any dependency on agent-provided identifiers. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#how-does-this-relate-to-proxy-chains) How does this relate to proxy chains? MCP-over-ACP is a transport mechanism that works independently of proxy chains. However, proxy chains are a natural use case: a proxy can inject MCP servers into sessions it forwards, handle the tool callbacks, and use the results to enhance its transformations. See the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains) for details on how MCP-over-ACP enables context-aware tooling. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#what-if-the-agent-doesn%E2%80%99t-support-acp-transport) What if the agent doesn’t support ACP transport? See the [Bridging for agents without native support](https://agentclientprotocol.com/rfds/mcp-over-acp#bridging-for-agents-without-native-support) section above. A bridge can transparently translate ACP-transport MCP servers to stdio or HTTP for agents that don’t advertise `mcpCapabilities.acp` support. ### [​](https://agentclientprotocol.com/rfds/mcp-over-acp#what-about-security) What about security? MCP-over-ACP has the same trust model as regular MCP: you’re allowing a component to handle tool invocations. The difference is transport, not trust. Components should only add MCP servers from sources they trust, same as with stdio or HTTP transport. [​](https://agentclientprotocol.com/rfds/mcp-over-acp#revision-history) Revision history ------------------------------------------------------------------------------------------- Split from proxy-chains RFD to enable independent use of MCP-over-ACP transport by any ACP component, not just proxies. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/proxy-chains) [Session Usage and Context Status\ \ Next](https://agentclientprotocol.com/rfds/session-usage) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/mcp-over-acp#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/mcp-over-acp#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/mcp-over-acp#what-we-propose-to-do-about-it) * [How it works](https://agentclientprotocol.com/rfds/mcp-over-acp#how-it-works) * [Bridging and compatibility](https://agentclientprotocol.com/rfds/mcp-over-acp#bridging-and-compatibility) * [Message flow example](https://agentclientprotocol.com/rfds/mcp-over-acp#message-flow-example) * [Shiny future](https://agentclientprotocol.com/rfds/mcp-over-acp#shiny-future) * [Seamless tool injection](https://agentclientprotocol.com/rfds/mcp-over-acp#seamless-tool-injection) * [WebAssembly-based tooling](https://agentclientprotocol.com/rfds/mcp-over-acp#webassembly-based-tooling) * [Transparent bridging](https://agentclientprotocol.com/rfds/mcp-over-acp#transparent-bridging) * [Implementation details and plan](https://agentclientprotocol.com/rfds/mcp-over-acp#implementation-details-and-plan) * [Capability advertising](https://agentclientprotocol.com/rfds/mcp-over-acp#capability-advertising) * [MCP transport schema extension](https://agentclientprotocol.com/rfds/mcp-over-acp#mcp-transport-schema-extension) * [Message reference](https://agentclientprotocol.com/rfds/mcp-over-acp#message-reference) * [Routing by ID](https://agentclientprotocol.com/rfds/mcp-over-acp#routing-by-id) * [Connection multiplexing](https://agentclientprotocol.com/rfds/mcp-over-acp#connection-multiplexing) * [Bridging for agents without native support](https://agentclientprotocol.com/rfds/mcp-over-acp#bridging-for-agents-without-native-support) * [Frequently asked questions](https://agentclientprotocol.com/rfds/mcp-over-acp#frequently-asked-questions) * [Why use a separate id instead of server names?](https://agentclientprotocol.com/rfds/mcp-over-acp#why-use-a-separate-id-instead-of-server-names) * [How does this relate to proxy chains?](https://agentclientprotocol.com/rfds/mcp-over-acp#how-does-this-relate-to-proxy-chains) * [What if the agent doesn’t support ACP transport?](https://agentclientprotocol.com/rfds/mcp-over-acp#what-if-the-agent-doesn%E2%80%99t-support-acp-transport) * [What about security?](https://agentclientprotocol.com/rfds/mcp-over-acp#what-about-security) * [Revision history](https://agentclientprotocol.com/rfds/mcp-over-acp#revision-history) --- # Session Usage and Context Status - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-usage#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Session Usage and Context Status [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/session-usage#elevator-pitch) Elevator pitch ---------------------------------------------------------------------------------------- > What are you proposing to change? Add standardized usage and context window tracking to the Agent Client Protocol, enabling agents to report token consumption, cost estimates, and context window utilization in a consistent way across implementations. [​](https://agentclientprotocol.com/rfds/session-usage#status-quo) Status quo -------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? Currently, the ACP protocol has no standardized way for agents to communicate: 1. **Token usage** - How many tokens were consumed in a turn or cumulatively 2. **Context window status** - How much of the model’s context window is being used 3. **Cost information** - Estimated costs for API usage 4. **Prompt caching metrics** - Cache hits/misses for models that support caching This creates several problems: * **No visibility into resource consumption** - Clients can’t show users how much of their context budget is being used * **No cost transparency** - Users can’t track spending or estimate costs before operations * **No context management** - Clients can’t warn users when approaching context limits or suggest compaction * **Inconsistent implementations** - Each agent implements usage tracking differently (if at all) Industry research shows common patterns across AI coding tools: * LLM providers return cumulative token counts in API responses * IDE extensions display context percentage prominently (e.g., radial progress showing “19%”) * Clients show absolute numbers on hover/detail (e.g., “31.4K of 200K tokens”) * Tools warn users at threshold percentages (75%, 90%, 95%) * Auto-compaction features trigger when approaching context limits * Cost tracking focuses on cumulative session totals rather than per-turn breakdowns [​](https://agentclientprotocol.com/rfds/session-usage#what-we-propose-to-do-about-it) What we propose to do about it ------------------------------------------------------------------------------------------------------------------------ > What are you proposing to improve the situation? We propose separating usage tracking into two distinct concerns: 1. **Token usage** - Reported in `PromptResponse` after each turn (per-turn data) 2. **Context window and cost** - Reported via `session/update` notifications with `sessionUpdate: "usage_update"` (session state) This separation reflects how users consume this information: * Token counts are tied to specific turns and useful immediately after a prompt * Context window and cost are cumulative session state that agents push proactively when available Agents send context updates at appropriate times: * On `session/new` response (if agent can query usage immediately) * On `session/load` / `session/resume` (for resumed/forked sessions) * After each `session/prompt` response (when usage data becomes available) * Anytime context window state changes significantly This approach provides flexibility for different agent implementations: * Agents that support getting current usage without a prompt can immediately send updates when creating, resuming, or forking chats * Agents that only provide usage when actively prompting can send updates after sending a new prompt ### [​](https://agentclientprotocol.com/rfds/session-usage#token-usage-in-promptresponse) Token Usage in `PromptResponse` Add a `usage` field to `PromptResponse` for token consumption tracking: { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123", "stopReason": "end_turn", "usage": { "total_tokens": 53000, "input_tokens": 35000, "output_tokens": 12000, "thought_tokens": 5000, "cached_read_tokens": 5000, "cached_write_tokens": 1000 } } } #### [​](https://agentclientprotocol.com/rfds/session-usage#usage-fields) Usage Fields * `total_tokens` (number, required) - Sum of all token types across session * `input_tokens` (number, required) - Total input tokens across all turns * `output_tokens` (number, required) - Total output tokens across all turns * `thought_tokens` (number, optional) - Total thought/reasoning tokens * `cached_read_tokens` (number, optional) - Total cache read tokens * `cached_write_tokens` (number, optional) - Total cache write tokens ### [​](https://agentclientprotocol.com/rfds/session-usage#context-window-and-cost-via-session/update) Context Window and Cost via `session/update` Agents send context window and cost information via `session/update` notifications with `sessionUpdate: "usage_update"`: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123", "update": { "sessionUpdate": "usage_update", "used": 53000, "size": 200000 } } } #### [​](https://agentclientprotocol.com/rfds/session-usage#context-window-fields-required) Context Window Fields (required) * `used` (number, required) - Tokens currently in context * `size` (number, required) - Total context window size in tokens Note: Clients can compute `remaining` as `size - used` and `percentage` as `used / size * 100` if needed. #### [​](https://agentclientprotocol.com/rfds/session-usage#cost-fields-optional) Cost Fields (optional) * `cost` (object, optional) - Cumulative session cost * `amount` (number, required) - Total cumulative cost for session * `currency` (string, required) - ISO 4217 currency code (e.g., “USD”, “EUR”) Example with optional cost: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123", "update": { "sessionUpdate": "usage_update", "used": 53000, "size": 200000, "cost": { "amount": 0.045, "currency": "USD" } } } } ### [​](https://agentclientprotocol.com/rfds/session-usage#design-principles) Design Principles 1. **Separation of concerns** - Token usage is per-turn data, context window and cost are session state 2. **Agent-pushed notifications** - Agents proactively send context updates when data becomes available, following the same pattern as other dynamic session properties (`available_commands_update`, `current_mode_update`, `session_info_update`) 3. **Agent calculates, client can verify** - Agent knows its model best and provides calculations, but includes raw data for client verification 4. **Flexible cost reporting** - Cost is optional since not all agents track it. Support any currency, don’t assume USD 5. **Prompt caching support** - Include cache read/write tokens for models that support it 6. **Optional but recommended** - Usage tracking is optional to maintain backward compatibility 7. **Flexible timing** - Agents send updates when they can: immediately for agents with on-demand APIs, or after prompts for agents that only provide usage during active prompting [​](https://agentclientprotocol.com/rfds/session-usage#shiny-future) Shiny future ------------------------------------------------------------------------------------ > How will things will play out once this feature exists? **For Users:** * **Visibility**: Users see real-time context window usage with percentage indicators * **Cost awareness**: Users can track spending and check cumulative cost at any time * **Better planning**: Users know when to start new sessions or compact context * **Transparency**: Clear understanding of resource consumption **For Client Implementations:** * **Consistent UI**: All clients can show usage in a standard way (progress bars, percentages, warnings) * **Smart warnings**: Clients can warn users at 75%, 90% context usage * **Cost controls**: Clients can implement budget limits and alerts * **Analytics**: Clients can track usage patterns and optimize * **Reactive updates**: Clients receive context updates reactively via notifications, updating UI immediately when agents push new data * **No polling needed**: Updates arrive automatically when agents have new information, eliminating the need for clients to poll **For Agent Implementations:** * **Standard reporting**: Clear contract for what to report and when * **Flexibility**: Optional fields allow agents to report what they can calculate * **Model diversity**: Works with any model (GPT, Claude, Llama, etc.) * **Caching support**: First-class support for prompt caching [​](https://agentclientprotocol.com/rfds/session-usage#implementation-details-and-plan) Implementation details and plan -------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? 1. **Update schema.json** to add: * `Usage` type with token fields * `Cost` type with `amount` and `currency` fields * `ContextUpdate` type with `used`, `size` (required) and optional `cost` field * Add optional `usage` field to `PromptResponse` * Add `UsageUpdate` variant to `SessionUpdate` oneOf array (with `sessionUpdate: "usage_update"`) 2. **Update protocol documentation**: * Document `usage` field in `/docs/protocol/prompt-turn.mdx` * Document `session/update` notification with `sessionUpdate: "usage_update"` variant * Add examples showing typical usage patterns and when agents send context updates [​](https://agentclientprotocol.com/rfds/session-usage#frequently-asked-questions) Frequently asked questions ---------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/session-usage#why-separate-token-usage-from-context-window-and-cost) Why separate token usage from context window and cost? Different users care about different things at different times: * **Token counts**: Relevant immediately after a turn completes to understand the breakdown * **Context window remaining**: Relevant at any time, especially before issuing a large prompt. “Do I need to handoff or compact?” * **Cumulative cost**: Session-level state that agents push when available Separating them allows: * Cleaner data model where per-turn data stays in turn responses * Agents to push context updates proactively when data becomes available * Clients to receive updates reactively without needing to poll ### [​](https://agentclientprotocol.com/rfds/session-usage#why-is-cost-in-session/update-instead-of-promptresponse) Why is cost in session/update instead of PromptResponse? Cost is cumulative session state, similar to context window: * Users want to track total spending, not just per-turn costs * Keeps `PromptResponse` focused on per-turn token breakdown * Both cost and context window are session-level metrics that belong together * Cost is optional since not all agents track it ### [​](https://agentclientprotocol.com/rfds/session-usage#how-do-users-know-when-to-handoff-or-compact-the-context) How do users know when to handoff or compact the context? The context update notification provides everything needed: * `used` and `size` give absolute numbers for precise tracking * Clients can compute `remaining` as `size - used` and `percentage` as `used / size * 100` * `size` lets clients understand the total budget **Recommended client behavior:** | Percentage | Action | | --- | --- | | < 75% | Normal operation | | 75-90% | Yellow indicator, suggest “Context filling up” | | 90-95% | Orange indicator, recommend “Start new session or summarize” | | \> 95% | Red indicator, warn “Next prompt may fail - handoff recommended” | Clients can also: * Offer “Compact context” or “Summarize conversation” actions * Auto-suggest starting a new session * Implement automatic handoff when approaching limits ### [​](https://agentclientprotocol.com/rfds/session-usage#why-not-assume-usd-for-cost) Why not assume USD for cost? Agents may bill in different currencies: * European agents might bill in EUR * Asian agents might bill in JPY or CNY * Some agents might use credits or points * Currency conversion rates change Better to report actual billing currency and let clients convert if needed. ### [​](https://agentclientprotocol.com/rfds/session-usage#what-if-the-agent-can%E2%80%99t-calculate-some-fields) What if the agent can’t calculate some fields? All fields except the basic token counts are optional. Agents report what they can calculate. Clients handle missing fields gracefully. ### [​](https://agentclientprotocol.com/rfds/session-usage#how-does-this-work-with-streaming-responses) How does this work with streaming responses? * During streaming: Agents may send progressive context updates via `session/update` notifications as usage changes * Final response: Include complete token usage in `PromptResponse` * Context window and cost: Agents send `session/update` notifications with `sessionUpdate: "usage_update"` when data becomes available (after prompt completion, on session creation/resume, or when context state changes significantly) ### [​](https://agentclientprotocol.com/rfds/session-usage#what-about-models-without-fixed-context-windows) What about models without fixed context windows? * Report effective context window size * For models with dynamic windows, report current limit * Update size if it changes * Set to `null` if truly unlimited (rare) ### [​](https://agentclientprotocol.com/rfds/session-usage#what-about-rate-limits-and-quotas) What about rate limits and quotas? This RFD focuses on token usage and context windows. Rate limits and quotas are a separate concern that could be addressed in a future RFD. However, the cost tracking here helps users understand their usage against quota limits. ### [​](https://agentclientprotocol.com/rfds/session-usage#should-cached-tokens-count-toward-context-window) Should cached tokens count toward context window? Yes, cached tokens still occupy context window space. They’re just cheaper to process. The context window usage should include all tokens (regular + cached). ### [​](https://agentclientprotocol.com/rfds/session-usage#why-notification-instead-of-request) Why notification instead of request? Using `session/update` notifications instead of a `session/status` request provides several benefits: 1. **Consistency**: Follows the same pattern as other dynamic session properties (`available_commands_update`, `current_mode_update`, `session_info_update`) 2. **Agent flexibility**: Agents can send updates when they have data available, whether that’s immediately (for agents with on-demand APIs) or after prompts (for agents that only provide usage during active prompting) 3. **No polling**: Clients receive updates reactively without needing to poll 4. **Real-time updates**: Updates flow naturally as part of the session lifecycle ### [​](https://agentclientprotocol.com/rfds/session-usage#what-if-the-client-connects-mid-session) What if the client connects mid-session? When a client connects to an existing session (via `session/load` or `session/resume`), agents **SHOULD** send a context update notification if they have current usage data available. This ensures the client UI can immediately display accurate context window and cost information. For agents that only provide usage during active prompting, the client UI may not show usage until after the first prompt is sent, which is acceptable given the agent’s capabilities. ### [​](https://agentclientprotocol.com/rfds/session-usage#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? **Alternatives considered:** 1. **Everything in PromptResponse** - Simpler, but context window and cost are session state that users may want to track independently of turns. 2. **Request/response (`session/status`)** - Requires clients to poll, and some agents don’t have APIs to query current status without a prompt. The notification approach is more flexible and consistent with other dynamic session properties. 3. **Client calculates everything** - Rejected because client doesn’t know model’s tokenizer, exact context window size, or pricing. 4. **Only percentage, no raw tokens** - Rejected because users want absolute numbers, clients can’t verify calculations, and it’s less transparent. [​](https://agentclientprotocol.com/rfds/session-usage#revision-history) Revision history -------------------------------------------------------------------------------------------- * 2025-12-07: Initial draft * 2025-12-13: Changed from `session/status` request method to `session/update` notification with `sessionUpdate: "context_update"`. Made `cost` optional and removed `remaining` field (clients can compute as `size - used`). This approach provides more flexibility for agents and follows the same pattern as other dynamic session properties. * 2025-12-17: Renamed `reasoning_tokens` to `thought_tokens` for consistency with ACP terminology. Removed `percentage` field (clients can compute as `used / size * 100`). * 2025-12-19: Renamed `sessionUpdate: "context_update"` to `sessionUpdate: "usage_update"` to better reflect the payload semantics (includes both context window info and cumulative cost). Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/mcp-over-acp) [Authentication Methods\ \ Next](https://agentclientprotocol.com/rfds/auth-methods) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-usage#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-usage#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-usage#what-we-propose-to-do-about-it) * [Token Usage in PromptResponse](https://agentclientprotocol.com/rfds/session-usage#token-usage-in-promptresponse) * [Usage Fields](https://agentclientprotocol.com/rfds/session-usage#usage-fields) * [Context Window and Cost via session/update](https://agentclientprotocol.com/rfds/session-usage#context-window-and-cost-via-session%2Fupdate) * [Context Window Fields (required)](https://agentclientprotocol.com/rfds/session-usage#context-window-fields-required) * [Cost Fields (optional)](https://agentclientprotocol.com/rfds/session-usage#cost-fields-optional) * [Design Principles](https://agentclientprotocol.com/rfds/session-usage#design-principles) * [Shiny future](https://agentclientprotocol.com/rfds/session-usage#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-usage#implementation-details-and-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-usage#frequently-asked-questions) * [Why separate token usage from context window and cost?](https://agentclientprotocol.com/rfds/session-usage#why-separate-token-usage-from-context-window-and-cost) * [Why is cost in session/update instead of PromptResponse?](https://agentclientprotocol.com/rfds/session-usage#why-is-cost-in-session%2Fupdate-instead-of-promptresponse) * [How do users know when to handoff or compact the context?](https://agentclientprotocol.com/rfds/session-usage#how-do-users-know-when-to-handoff-or-compact-the-context) * [Why not assume USD for cost?](https://agentclientprotocol.com/rfds/session-usage#why-not-assume-usd-for-cost) * [What if the agent can’t calculate some fields?](https://agentclientprotocol.com/rfds/session-usage#what-if-the-agent-can%E2%80%99t-calculate-some-fields) * [How does this work with streaming responses?](https://agentclientprotocol.com/rfds/session-usage#how-does-this-work-with-streaming-responses) * [What about models without fixed context windows?](https://agentclientprotocol.com/rfds/session-usage#what-about-models-without-fixed-context-windows) * [What about rate limits and quotas?](https://agentclientprotocol.com/rfds/session-usage#what-about-rate-limits-and-quotas) * [Should cached tokens count toward context window?](https://agentclientprotocol.com/rfds/session-usage#should-cached-tokens-count-toward-context-window) * [Why notification instead of request?](https://agentclientprotocol.com/rfds/session-usage#why-notification-instead-of-request) * [What if the client connects mid-session?](https://agentclientprotocol.com/rfds/session-usage#what-if-the-client-connects-mid-session) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/session-usage#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/session-usage#revision-history) --- # Session List - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-list#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Completed Session List [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/session-list#elevator-pitch) Elevator pitch --------------------------------------------------------------------------------------- Add a `session/list` endpoint to the ACP protocol that allows clients to query and enumerate existing sessions from an agent, enabling session management features like session history, session switching, and session cleanup. [​](https://agentclientprotocol.com/rfds/session-list#status-quo) Status quo ------------------------------------------------------------------------------- Currently, the ACP protocol provides session management through `session/new` and `session/load` endpoints. However, there is no way for clients to: 1. **Discover existing sessions** - Clients cannot query what sessions exist on an agent 2. **Display session history** - Users cannot see a list of their past conversations 3. **Manage multiple sessions** - Switching between sessions requires clients to track session IDs themselves 4. **Clean up old sessions** - No way to discover stale or abandoned sessions for cleanup This creates several problems: * **Poor user experience** - Users cannot browse their conversation history or resume previous sessions easily * **Client-side complexity** - Each client must implement its own session tracking and persistence * **Inconsistent behavior** - Different clients handle session management differently, leading to fragmented experiences The current workaround is for clients to maintain their own session registry, but this: * Requires persistent storage on the client side * Can get out of sync if sessions are created/destroyed outside the client * Doesn’t work across different client instances or devices * Cannot leverage agent-side session metadata or state [​](https://agentclientprotocol.com/rfds/session-list#what-we-propose-to-do-about-it) What we propose to do about it ----------------------------------------------------------------------------------------------------------------------- Add a new `session/list` JSON-RPC method to the protocol that returns metadata about sessions known to the agent. This endpoint would: 1. **Return a list of sessions** with essential metadata: * `sessionId` - Unique identifier * `cwd` - Working directory for the session * `title` - Optional human-readable title (could be auto-generated from first prompt) * `updatedAt` - Timestamp of last update to the session * `_meta` - Optional agent-specific metadata 2. **Support filtering and pagination**: * Filter by working directory * Agent provides an optional cursor for retrieving the next page of results 3. **Be an optional capability**: * Agents advertise `sessionCapabilities: { list: {} }` in initialization if they support this feature * Clients check for this capability before attempting to call `session/list` * Agents without persistent session storage don’t need to implement this ### [​](https://agentclientprotocol.com/rfds/session-list#json-rpc-request) JSON-RPC Request The client calls `session/list` with optional filtering and pagination parameters: { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": { "cwd": "/home/user/project", "cursor": "eyJwYWdlIjogMn0=" } } #### [​](https://agentclientprotocol.com/rfds/session-list#request-parameters) Request Parameters All parameters are optional: * `cwd` (string) - Filter sessions by working directory * `cursor` (string) - Opaque cursor token from a previous response’s `nextCursor` field for cursor-based pagination #### [​](https://agentclientprotocol.com/rfds/session-list#minimal-request-example) Minimal Request Example A request with no filters returns all sessions with default sorting: { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": {} } ### [​](https://agentclientprotocol.com/rfds/session-list#json-rpc-response) JSON-RPC Response The agent responds with a list of sessions and cursor pagination metadata: { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [\ {\ "sessionId": "sess_abc123def456",\ "updatedAt": "2025-10-29T14:22:15Z",\ "cwd": "/home/user/project",\ "title": "Implement session list API",\ "_meta": {\ "messageCount": 12,\ "hasErrors": false\ }\ },\ {\ "sessionId": "sess_xyz789ghi012",\ "updatedAt": "2025-10-28T16:45:30Z",\ "cwd": "/home/user/another-project",\ "title": "Debug authentication flow"\ },\ {\ "sessionId": "sess_uvw345rst678",\ "updatedAt": "2025-10-27T15:30:00Z",\ "cwd": "/home/user/project"\ }\ ], "nextCursor": "eyJwYWdlIjogM30=" } } #### [​](https://agentclientprotocol.com/rfds/session-list#response-fields) Response Fields **Response object:** * `sessions` (array) - Array of session information objects * `nextCursor` (string, optional) - Opaque cursor token. If present, pass this in the next request’s `cursor` parameter to fetch the next page. If absent, there are no more results. **SessionInfo object:** * `sessionId` (string, required) - Unique identifier for the session * `cwd` (string, required) - Working directory for the session * `title` (string, optional) - Human-readable title (may be auto-generated from first prompt) * `updatedAt` (string, optional) - ISO 8601 timestamp of last activity * `_meta` (object, optional) - Agent-specific metadata (e.g., message count, error status, tags) #### [​](https://agentclientprotocol.com/rfds/session-list#empty-result-example) Empty Result Example When no sessions match the criteria: { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [] } } [​](https://agentclientprotocol.com/rfds/session-list#shiny-future) Shiny future ----------------------------------------------------------------------------------- Once this feature exists: 1. **Clients can build session browsers** - Users can view a list of all their conversations, sorted by recency or relevance 2. **Session switching becomes seamless** - Users can easily switch between ongoing conversations 3. **Better resource management** - Clients can identify and clean up old or inactive sessions 4. **Cross-device continuity** - Users could potentially access their sessions from different devices (if agent supports it) 5. **Improved UX patterns**: * “Recent conversations” sidebar * Search through past sessions * Archive/delete old sessions * Resume interrupted work easily Agents that implement this feature gain: * Better visibility into active sessions * Opportunity to implement session lifecycle policies * Foundation for future features like session sharing or collaboration [​](https://agentclientprotocol.com/rfds/session-list#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/session-list#phase-1-core-protocol-changes) Phase 1: Core Protocol Changes 1. **Update schema.json** to add: * `session/list` method definition * `ListSessionsRequest` and `ListSessionsResponse` types * `SessionInfo` type * `sessionCapabilities/list` capability flag 2. **Update protocol documentation** in `/docs/protocol/session-setup.mdx`: * Document the new endpoint * Explain when to use it vs. maintaining client-side session tracking * Provide examples of common use cases ### [​](https://agentclientprotocol.com/rfds/session-list#phase-2-reference-implementation) Phase 2: Reference Implementation 3. **Implement in Rust SDK** (`src/agent.rs` and `src/client.rs`): * Add `list_sessions` method to agent trait * Provide default implementation (empty list) for agents without persistence * Add client method to call `session/list` 4. **Add to TypeScript SDKs** (if applicable): * Update TypeScript types * Add client methods ### [​](https://agentclientprotocol.com/rfds/session-list#phase-3-example-implementation) Phase 3: Example Implementation 5. **Create example agent** that demonstrates: * In-memory session registry * Automatic title generation from first prompt * Session lifecycle management (cleanup after N days) * Pagination and filtering ### [​](https://agentclientprotocol.com/rfds/session-list#compatibility-considerations) Compatibility Considerations * **Backward compatible**: Existing agents continue working without implementing this * **Capability-based**: Clients check for `sessionCapabilities.list` capability before using * **No breaking changes**: No modifications to existing endpoints ### [​](https://agentclientprotocol.com/rfds/session-list#security-considerations) Security Considerations * **Session isolation**: Agents must ensure sessions are only listed for the authenticated client * **Resource limits**: Agents should enforce reasonable page sizes internally to prevent abuse [​](https://agentclientprotocol.com/rfds/session-list#frequently-asked-questions) Frequently asked questions --------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/session-list#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? Several alternatives were considered: 1. **Client-side session tracking only** - This is the current approach, but it has limitations: * Doesn’t work across devices * Can get out of sync * Adds complexity to every client implementation 2. **Session events/notifications** - Push notifications when sessions are created/destroyed: * More complex to implement * Requires long-lived connections * Still requires client-side state management * Better suited as a future enhancement, not a replacement 3. **File-based session manifest** - Agent writes session list to a file that clients read: * Couples agent and client file system access * Doesn’t work for remote agents * No standard format The proposed RPC approach is: * **Consistent with existing protocol design** - Uses same RPC patterns as other endpoints * **Flexible** - Supports filtering, pagination, and agent-specific metadata * **Optional** - Agents can opt-in based on their architecture * **Simple** - Single request/response pattern, easy to implement and use ### [​](https://agentclientprotocol.com/rfds/session-list#why-not-make-this-mandatory-for-all-agents) Why not make this mandatory for all agents? Many agents may not have persistent storage or multi-session capabilities. Making this optional: * Allows simple, stateless agents to remain compliant * Reduces implementation burden * Lets agents evolve session management over time ### [​](https://agentclientprotocol.com/rfds/session-list#how-does-this-interact-with-session/load) How does this interact with `session/load`? `session/load` remains the mechanism to actually restore a session. `session/list` is for discovery only: 1. Client calls `session/list` to get available sessions 2. User selects a session 3. Client calls `session/load` with the chosen `sessionId` Agents may support `session/list` without supporting `session/load` (e.g., for read-only session browsing). ### [​](https://agentclientprotocol.com/rfds/session-list#should-we-include-session-content-in-the-list-response) Should we include session content in the list response? No, for several reasons: * **Performance** - Full conversation history could be large * **Privacy** - Listing sessions might be less sensitive than exposing full content * **Separation of concerns** - Use `session/load` to get full session content ### [​](https://agentclientprotocol.com/rfds/session-list#what-about-session-deletion) What about session deletion? Session deletion is intentionally left out of this RFD to keep scope focused. A future `session/delete` endpoint could be proposed separately. For now, agents can implement their own lifecycle policies. ### [​](https://agentclientprotocol.com/rfds/session-list#how-should-pagination-work-for-large-session-lists) How should pagination work for large session lists? We use cursor-based pagination: * Request includes an optional `cursor` * Response includes `nextCursor` when more results are available * Clients should treat a missing `nextCursor` as the end of results * Clients MUST treat cursors as opaque tokens: don’t parse, modify, or persist them across sessions * The cursor MUST be a string; never send a raw JSON object as the cursor * Servers SHOULD provide stable cursors and handle invalid cursors gracefully Good request example: { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": { "cwd": "/home/user/project", "createdAfter": "2025-10-20T00:00:00Z", "cursor": "eyJwYWdlIjogMn0=", "search": "auth" } } Corresponding response example: { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [\ /* ... */\ ], "nextCursor": "eyJwYWdlIjogM30=" } } [​](https://agentclientprotocol.com/rfds/session-list#revision-history) Revision history ------------------------------------------------------------------------------------------- * **2025-10-29**: Initial draft proposal * **2025-10-30**: Update to use `_meta` field for agent-specific metadata * **2025-10-30**: Switch from offset-based to cursor-based pagination using continuation tokens * **2025-10-30**: Rename `lastAccessedAt` to `updatedAt` for consistency * **2025-10-30**: Remove `preview` field from SessionInfo (out of scope) * **2025-10-30**: Remove session orphaning from problem statement * **2025-10-30**: Replace `sortBy`/`sortOrder` with `search` parameter; remove `total` count from response * **2025-10-31**: Update pagination: `continuationToken` → `cursor`, `nextContinuationToken` → `nextCursor`, remove `hasMore` * **2025-11-11**: Remove `createdAt`, `updatedAt`, and `search` filters from the request parameters * **2025-11-23**: Remove `limit` parameter from request; make `createdAt` and `updatedAt` optional in SessionInfo * **2025-11-24**: Update capabilities schema, consolidate to single `updatedAt` timestamp Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/session-config-options) [Session Info Update\ \ Next](https://agentclientprotocol.com/rfds/session-info-update) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-list#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-list#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-list#what-we-propose-to-do-about-it) * [JSON-RPC Request](https://agentclientprotocol.com/rfds/session-list#json-rpc-request) * [Request Parameters](https://agentclientprotocol.com/rfds/session-list#request-parameters) * [Minimal Request Example](https://agentclientprotocol.com/rfds/session-list#minimal-request-example) * [JSON-RPC Response](https://agentclientprotocol.com/rfds/session-list#json-rpc-response) * [Response Fields](https://agentclientprotocol.com/rfds/session-list#response-fields) * [Empty Result Example](https://agentclientprotocol.com/rfds/session-list#empty-result-example) * [Shiny future](https://agentclientprotocol.com/rfds/session-list#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-list#implementation-details-and-plan) * [Phase 1: Core Protocol Changes](https://agentclientprotocol.com/rfds/session-list#phase-1-core-protocol-changes) * [Phase 2: Reference Implementation](https://agentclientprotocol.com/rfds/session-list#phase-2-reference-implementation) * [Phase 3: Example Implementation](https://agentclientprotocol.com/rfds/session-list#phase-3-example-implementation) * [Compatibility Considerations](https://agentclientprotocol.com/rfds/session-list#compatibility-considerations) * [Security Considerations](https://agentclientprotocol.com/rfds/session-list#security-considerations) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-list#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/session-list#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Why not make this mandatory for all agents?](https://agentclientprotocol.com/rfds/session-list#why-not-make-this-mandatory-for-all-agents) * [How does this interact with session/load?](https://agentclientprotocol.com/rfds/session-list#how-does-this-interact-with-session%2Fload) * [Should we include session content in the list response?](https://agentclientprotocol.com/rfds/session-list#should-we-include-session-content-in-the-list-response) * [What about session deletion?](https://agentclientprotocol.com/rfds/session-list#what-about-session-deletion) * [How should pagination work for large session lists?](https://agentclientprotocol.com/rfds/session-list#how-should-pagination-work-for-large-session-lists) * [Revision history](https://agentclientprotocol.com/rfds/session-list#revision-history) --- # RFD Updates - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/updates#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation RFD Updates [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](https://agentclientprotocol.com/updates) . [​](https://agentclientprotocol.com/rfds/updates#april-22-2026) April 22, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#streamable-http-&-websocket-transport-rfd-moves-to-draft-stage) Streamable HTTP & WebSocket Transport RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for standardizing a remote ACP transport based on MCP Streamable HTTP with a WebSocket upgrade has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#april-14-2026) April 14, 2026 Preview [​](https://agentclientprotocol.com/rfds/updates#session/resume-rfd-moves-to-preview-stage) session/resume RFD moves to Preview stage ---------------------------------------------------------------------------------------------------------------------------------------- The RFD for adding a `session/resume` method to the protocol has been moved to Preview stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-resume) for more information on the current proposal and provide feedback before the feature is stabilized. [​](https://agentclientprotocol.com/rfds/updates#april-14-2026-2) April 14, 2026 Preview [​](https://agentclientprotocol.com/rfds/updates#session/close-rfd-moves-to-preview-stage) session/close RFD moves to Preview stage -------------------------------------------------------------------------------------------------------------------------------------- The RFD for allowing agents to close a given session has been moved to Preview stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-close) for more information on the current proposal and provide feedback before the feature is stabilized. [​](https://agentclientprotocol.com/rfds/updates#march-27-2026) March 27, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#custom-llm-endpoint-rfd-moves-to-draft-stage) Custom LLM Endpoint RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------------------- The RFD for allowing clients to specify custom provider configuration has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/custom-llm-endpoint) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#march-24-2026) March 24, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#additional-directories-rfd-moves-to-draft-stage) Additional Directories RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for allowing clients to specify additional directories for the agent to access has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/additional-directories) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#march-9-2026) March 9, 2026 Completed [​](https://agentclientprotocol.com/rfds/updates#acp-registry-rfd-moves-to-completed) ACP Registry RFD moves to Completed ---------------------------------------------------------------------------------------------------------------------------- The RFD for the initial version of the ACP Registry has been completed. Please review the [documentation](https://agentclientprotocol.com/get-started/registry) for more information. [​](https://agentclientprotocol.com/rfds/updates#session_info_update-notification-rfd-moves-to-completed) session\_info\_update Notification RFD moves to Completed ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for the session\_info\_update notification has been stabilized and is now a part of the protocol. Please review the [documentation](https://agentclientprotocol.com/protocol/session-list#updating-session-metadata) for more information. [​](https://agentclientprotocol.com/rfds/updates#session/list-rfd-moves-to-completed) session/list RFD moves to Completed ---------------------------------------------------------------------------------------------------------------------------- The RFD for the session/list method has been stabilized and is now a part of the protocol. Please review the [documentation](https://agentclientprotocol.com/protocol/session-list) for more information. [​](https://agentclientprotocol.com/rfds/updates#february-24-2026) February 24, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#next-edit-suggestions-rfd-moves-to-draft-stage) Next Edit Suggestions RFD moves to Draft stage -------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for allowing agents to provide next edit suggestions has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/next-edit-suggestions) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#session/close-rfd-moves-to-draft-stage) session/close RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------- The RFD for allowing agents to close a given session has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-close) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#elicitation-rfd-moves-to-draft-stage) Elicitation RFD moves to Draft stage ------------------------------------------------------------------------------------------------------------------------------ The RFD for allowing agents to elicit user input has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/elicitation) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#boolean-config-option-rfd-moves-to-draft-stage) Boolean Config Option RFD moves to Draft stage -------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for adding boolean config options to the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/boolean-config-option) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#february-20-2026) February 20, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#delete-in-diff-rfd-moves-to-draft-stage) Delete in Diff RFD moves to Draft stage ------------------------------------------------------------------------------------------------------------------------------------ The RFD for indicating whether a diff resulted in a file deletion has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/diff-delete) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#february-18-2026) February 18, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#message-id-rfd-moves-to-draft-stage) Message ID RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------- The RFD for adding message ids to the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/message-id) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#february-18-2026-2) February 18, 2026 Preview [​](https://agentclientprotocol.com/rfds/updates#session/list-rfd-moves-to-preview-stage) session/list RFD moves to Preview stage ------------------------------------------------------------------------------------------------------------------------------------ The RFD for the session/list method has been moved to Preview stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-list) for more information on the current proposal and provide feedback before the feature is stabilized. [​](https://agentclientprotocol.com/rfds/updates#session_info_update-rfd-moves-to-preview-stage) session\_info\_update RFD moves to Preview stage ---------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for the session\_info\_update notification has been moved to Preview stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-info-update) for more information on the current proposal and provide feedback before the feature is stabilized. [​](https://agentclientprotocol.com/rfds/updates#february-10-2026) February 10, 2026 Preview [​](https://agentclientprotocol.com/rfds/updates#acp-registry-rfd-moves-to-preview-stage) ACP Registry RFD moves to Preview stage ------------------------------------------------------------------------------------------------------------------------------------ The RFD for the ACP Registry has been moved to Preview stage. Please review the [RFD](https://agentclientprotocol.com/rfds/acp-agent-registry) for more information on the current proposal and provide feedback before the feature is stabilized. [​](https://agentclientprotocol.com/rfds/updates#february-4-2026) February 4, 2026 Completed [​](https://agentclientprotocol.com/rfds/updates#session-config-options-rfd-moves-to-completed) Session Config Options RFD moves to Completed ------------------------------------------------------------------------------------------------------------------------------------------------ The RFD for adding more generic Session Config Options to the protocol has been stabilized and is now a part of the protocol. Please review the [documentation](https://agentclientprotocol.com/protocol/session-config-options) for more information. [​](https://agentclientprotocol.com/rfds/updates#february-4-2026-2) February 4, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#session/delete-moves-to-draft-stage) session/delete moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------- The RFD for allowing clients to delete a given session has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-delete) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#logout-method-moves-to-draft-stage) Logout method moves to Draft stage -------------------------------------------------------------------------------------------------------------------------- The RFD for allowing clients to logout from an agent connection has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/logout-method) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#january-15-2026) January 15, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#rust-sdk-based-on-sacp-rfd-moves-to-draft-stage) Rust SDK based on SACP RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for basing the Rust SDK on SACP has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/rust-sdk-v1) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#january-15-2026-2) January 15, 2026 Preview [​](https://agentclientprotocol.com/rfds/updates#session-config-options-rfd-moves-to-preview-stage) Session Config Options RFD moves to Preview stage -------------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for adding more generic Session Config Options to the protocol has been moved to Preview stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-config-options) for more information on the current proposal and provide feedback before the feature is stabilized. [​](https://agentclientprotocol.com/rfds/updates#january-14-2026) January 14, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#authentication-methods-rfd-moves-to-draft-stage) Authentication Methods RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for creating additional types of authentication methods has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/auth-methods) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#january-1-2026) January 1, 2026 Draft [​](https://agentclientprotocol.com/rfds/updates#agent-registry-rfd-moves-to-draft-stage) Agent Registry RFD moves to Draft stage ------------------------------------------------------------------------------------------------------------------------------------ The RFD for creating an Agent Registry has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/acp-agent-registry) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#session-usage-rfd-moves-to-draft-stage) Session Usage RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------- The RFD for adding a new usage\_update variant on the session/update notification and usage field on prompt responses in the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-usage) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#december-31-2025) December 31, 2025 Draft [​](https://agentclientprotocol.com/rfds/updates#proxy-chains-rfd-moves-to-draft-stage) Proxy Chains RFD moves to Draft stage -------------------------------------------------------------------------------------------------------------------------------- The RFD for adding proxy chain functionality in the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/proxy-chains) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#december-11-2025) December 11, 2025 Draft [​](https://agentclientprotocol.com/rfds/updates#agent-telemetry-export-rfd-moves-to-draft-stage) Agent Telemetry Export RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for providing more guidance on how agents should export telemetry has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/agent-telemetry-export) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#december-3-2025) December 3, 2025 Draft [​](https://agentclientprotocol.com/rfds/updates#session_info_update-notification-rfd-moves-to-draft-stage) session\_info\_update notification RFD moves to Draft stage -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for adding a new session\_info\_update variant on the session/update notification in the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-info-update) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#_meta-propagation-rfd-moves-to-draft-stage) \_meta Propagation RFD moves to Draft stage ------------------------------------------------------------------------------------------------------------------------------------------- The RFD for providing more guidance on how the \_meta parameter should be used within the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/meta-propagation) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#november-26-2025) November 26, 2025 Draft [​](https://agentclientprotocol.com/rfds/updates#session/resume-rfd-moves-to-draft-stage) session/resume RFD moves to Draft stage ------------------------------------------------------------------------------------------------------------------------------------ The RFD for adding a session/resume method to the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-resume) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#november-20-2025) November 20, 2025 Draft [​](https://agentclientprotocol.com/rfds/updates#$/cancelrequest-rfd-moves-to-draft-stage) $/cancelRequest RFD moves to Draft stage -------------------------------------------------------------------------------------------------------------------------------------- The RFD for adding a $/cancelRequest method to the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/request-cancellation) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#session/fork-rfd-moves-to-draft-stage) session/fork RFD moves to Draft stage -------------------------------------------------------------------------------------------------------------------------------- The RFD for adding a session/fork method to the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-fork) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#november-3-2025) November 3, 2025 Draft [​](https://agentclientprotocol.com/rfds/updates#session-config-options-rfd-moves-to-draft-stage) Session Config Options RFD moves to Draft stage ---------------------------------------------------------------------------------------------------------------------------------------------------- The RFD for adding more generic Session Config Options to the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-config-options) for more information on the current proposal and provide feedback as work on the implementation begins. [​](https://agentclientprotocol.com/rfds/updates#october-31-2025) October 31, 2025 Draft [​](https://agentclientprotocol.com/rfds/updates#session/list-rfd-moves-to-draft-stage) session/list RFD moves to Draft stage -------------------------------------------------------------------------------------------------------------------------------- The RFD for adding a session/list method to the protocol has been moved to Draft stage. Please review the [RFD](https://agentclientprotocol.com/rfds/session-list) for more information on the current proposal and provide feedback as work on the implementation begins. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/about) [Forking of existing sessions\ \ Next](https://agentclientprotocol.com/rfds/session-fork) ⌘I FiltersClear DraftPreviewCompleted --- # Streamable HTTP & WebSocket Transport - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Streamable HTTP & WebSocket Transport [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [alexhancock](https://github.com/alexhancock) , [jh-block](https://github.com/jh-block) * Champion: [anna239](https://github.com/anna239) [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#elevator-pitch) Elevator pitch -------------------------------------------------------------------------------------------------------------- > What are you proposing to change? ACP needs a standard remote transport. We propose adopting **MCP Streamable HTTP** (2025-11-25) with ACP-specific headers, and extending it with a **WebSocket upgrade** on the same endpoint. A single `/acp` endpoint supports two connectivity profiles: * **Streamable HTTP (POST/GET/DELETE)** — stateless-friendly, SSE-based streaming, aligned with MCP Streamable HTTP. * **WebSocket upgrade (GET with `Upgrade: websocket`)** — persistent, full-duplex, low-latency bidirectional messaging. Clients that support remote ACP over HTTP MUST support both Streamable HTTP and WebSocket. This allows servers to support only WebSocket if they choose, simplifying deployment. Both profiles share the same JSON-RPC message format and ACP lifecycle as the existing **stdio** local subprocess transport. [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#status-quo) Status quo ------------------------------------------------------------------------------------------------------ > How do things work today and what problems does this cause? Why would we change things? ACP only has stdio (inherited from MCP). There is no standard remote transport, which causes: 1. **Fragmentation** — implementers invent their own HTTP layers, leading to incompatible SDKs and deployments. 2. **Missed alignment** — MCP Streamable HTTP is well-designed; ACP should adopt it rather than diverge. [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#what-we-propose-to-do-about-it) What we propose to do about it ---------------------------------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#1-mostly-adopts-mcp-streamable-http-semantics-with-acp-specific-headers) 1\. Mostly adopts MCP Streamable HTTP semantics with ACP-specific headers Follows the MCP 2025-11-25 Streamable HTTP spec with these adaptations: * Connection header: `Acp-Connection-Id` (similar to `Mcp-Session-Id`) * Session header: `Acp-Session-Id` (new, no MCP equivalent) * Protocol version header: `Acp-Protocol-Version` * Endpoint path: conventionally `/acp` ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#2-separates-connection-identity-from-session-identity-with-two-headers) 2\. Separates connection identity from session identity with two headers ACP introduces two HTTP headers that together identify the full request context: * **`Acp-Connection-Id`** (HTTP header) — A transport-level identifier returned by the server in the `initialize` response. It binds all subsequent HTTP requests to the initialized connection and its negotiated capabilities. This is analogous to `Mcp-Session-Id` in MCP Streamable HTTP. Required on all requests after `initialize`. * **`Acp-Session-Id`** (HTTP header) — A session-level identifier returned by the server in the `session/new` response (both in the `Acp-Session-Id` response header and the JSON-RPC result body). It identifies a specific conversation. Clients MUST include it on all subsequent requests that operate within a session (e.g., `session/prompt`, `session/cancel`). The same value appears in JSON-RPC params as `sessionId` for methods that require it. A single `Acp-Connection-Id` may span multiple ACP sessions. Before `session/new` is called, only `Acp-Connection-Id` is present. After `session/new`, both headers are included. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#3-adds-websocket-as-a-first-class-upgrade-on-the-same-endpoint) 3\. Adds WebSocket as a first-class upgrade on the same endpoint A GET with `Upgrade: websocket` upgrades to a persistent bidirectional channel — same endpoint, same lifecycle model. This is important for ACP, as it is more bidirectional in its nature as a protocol. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#4-requires-cookie-support-on-http-transports) 4\. Requires cookie support on HTTP transports Clients MUST accept, store, and return cookies set by the server on all HTTP-based transports (Streamable HTTP and WebSocket). Cookies MUST be sent on subsequent requests to the server for the duration of the connection. Clients MAY discard all cookies when a connection is terminated. This allows servers to rely on cookies for session affinity (e.g., sticky sessions behind a load balancer) and other small amounts of per-connection state. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#5-defines-a-unified-routing-model) 5\. Defines a unified routing model | Method | Upgrade Header? | Behavior | | --- | --- | --- | | `POST` | — | Send JSON-RPC request/notification/response (Streamable HTTP) | | `GET` | No | Open session-scoped SSE stream for server-initiated messages (Streamable HTTP). Requires `Acp-Connection-Id` and `Acp-Session-Id`. | | `GET` | `Upgrade: websocket` | Upgrade to WebSocket for full-duplex messaging | | `DELETE` | — | Terminate the connection | ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#6-preserves-the-full-acp-lifecycle) 6\. Preserves the full ACP lifecycle The `initialize` → `initialized` → messages → close lifecycle is identical regardless of transport. The `Acp-Connection-Id` header binds requests to the initialized connection and its negotiated capabilities. The `Acp-Session-Id` header (introduced after `session/new`) identifies an active ACP session. [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#shiny-future) Shiny future ---------------------------------------------------------------------------------------------------------- > How will things play out once this feature exists? * **SDK implementers** get a clear, testable transport spec — Rust, TypeScript, and Python SDKs can all interoperate. * **Desktop clients** use WebSocket for low-latency streaming; all clients support it as a baseline. * **Cloud deployments** expose agents behind standard HTTP load balancers using the stateless-friendly HTTP mode, with cookie-based sticky sessions guaranteed by client support. * **Proxy chains** can route ACP traffic over HTTP for multi-hop agent topologies. [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------------------------------ > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#transport-architecture) Transport Architecture ┌─────────────────────────────────┐ │ /acp endpoint │ └──────┬──────────┬───────────────┘ │ │ ┌───────────▼──┐ ┌────▼──────────────┐ │ HTTP State │ │ WebSocket State │ │(connections) │ │ (connections) │ └───────┬──────┘ └────┬──────────────┘ │ │ ┌───────▼──────────────▼───────────────┐ │ ACP Agent (JSON-RPC handler) │ │ serve(agent, read, write) │ └─────────────────────────────────────┘ ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#identity-model) Identity Model ACP over Streamable HTTP uses two HTTP headers that together identify the full request context: | | `Acp-Connection-Id` | `Acp-Session-Id` | | --- | --- | --- | | **Purpose** | Binds HTTP requests to an initialized connection | Identifies an ACP conversation/session | | **Created by** | Server, on `initialize` response | Server, on `session/new` response | | **Location** | HTTP header (all requests after `initialize`) | HTTP header (all requests after `session/new`) + JSON-RPC body as `sessionId` | | **Scope** | One per `initialize` handshake | One per `session/new` call | | **Multiplicity** | May span multiple sessions | Belongs to exactly one connection | | **Used for** | Request routing, capability lookup | Session-scoped request routing, session-scoped GET listener filtering | | **Required** | After `initialize` | After `session/new` | ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#streamable-http-message-flow) Streamable HTTP Message Flow Client Server │ │ │ ═══ Connection Initialization ═══│ │ │ │─── POST /acp ─────────────────────>│ { method: "initialize", id: 1 } │ Accept: application/json, │ (no Acp-Connection-Id header) │ text/event-stream │ │ ┌─────────────────────│ Server creates connection │ │ (SSE stream open) │ │<─────────────│─ SSE event ─────────│ { id: 1, result: { capabilities } } │ │ │ Response includes Acp-Connection-Id header │ ▼ │ │ │ │ ═══ Session Creation ═══ │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/new", id: 2, │ Acp-Connection-Id: │ params: { cwd, mcpServers } } │ ┌─────────────────────│ Opens new SSE stream for response │<─────────────│─ SSE event ─────────│ { id: 2, result: { sessionId: "sess_abc123" } } │ │ │ Response includes Acp-Session-Id header │ ▼ │ │ │ │ ═══ Optional: GET Listener ════════│ │ │ │─── GET /acp ──────────────────────>│ Open SSE listener for │ Acp-Connection-Id: │ server-initiated messages │ Acp-Session-Id: │ (scoped to this session) │ Accept: text/event-stream │ │ ┌─────────────────────│ Only events for this session │ │ (SSE stream open) │ are delivered on this stream │ ▼ │ │ │ │ ═══ Prompt Flow ═══ │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/prompt", id: 3, │ Acp-Connection-Id: │ params: { sessionId: "sess_abc123", prompt } } │ Acp-Session-Id: │ │ ┌─────────────────────│ Opens new SSE stream for response │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk │<─────────────│─ SSE event ─────────│ notification: AgentThoughtChunk (if reasoning) │<─────────────│─ SSE event ─────────│ notification: ToolCall (status: pending) │<─────────────│─ SSE event ─────────│ notification: ToolCallUpdate (status: completed) │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk │<─────────────│─ SSE event ─────────│ { id: 3, result: { stop_reason: "end_turn" } } │ ▼ │ │ │ │ ═══ Permission Flow ═══ │ │ (when tool requires confirmation) │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/prompt", id: 4, ... } │ Acp-Connection-Id: │ │ Acp-Session-Id: │ │ ┌─────────────────────│ │<─────────────│─ SSE event ─────────│ notification: ToolCall (status: pending) │<─────────────│─ SSE event ─────────│ { method: "request_permission", id: 99, params: {...} } │ │ │ (server-to-client request) │ │ │ │─── POST /acp ┼────────────────────>│ { id: 99, result: { outcome: "allow_once" } } │ Acp-Connection-Id: │ (client response, returns 202 Accepted) │ Acp-Session-Id: │ │ │ │ │<─────────────│─ SSE event ─────────│ notification: ToolCallUpdate (status: completed) │<─────────────│─ SSE event ─────────│ { id: 4, result: { stop_reason: "end_turn" } } │ ▼ │ │ │ │ ═══ Cancel Flow ═══ │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/prompt", id: 5, ... } │ Acp-Connection-Id: │ │ Acp-Session-Id: │ │ ┌─────────────────────│ │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk │ │ │ │─── POST /acp ┼────────────────────>│ { method: "session/cancel" } │ Acp-Connection-Id: │ (notification, no id - returns 202 Accepted) │ Acp-Session-Id: │ │ │ │ │<─────────────│─ SSE event ─────────│ { id: 5, result: { stop_reason: "cancelled" } } │ ▼ │ │ │ │ ═══ Resume Session Flow ═══ │ │ (new connection, existing session)│ │ │ │─── POST /acp ─────────────────────>│ { method: "initialize", id: 1 } │ (no Acp-Connection-Id) │ New connection │ ┌─────────────────────│ │<─────────────│─ SSE event ─────────│ { id: 1, result: { capabilities } } │ │ │ Response includes new Acp-Connection-Id │ ▼ │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/load", id: 2, │ Acp-Connection-Id: │ params: { sessionId: "sess_abc123", cwd } } │ Acp-Session-Id: │ │ │ │ │ ┌─────────────────────│ Response includes Acp-Session-Id header │<─────────────│─ SSE event ─────────│ notification: UserMessageChunk (history replay) │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk (history replay) │<─────────────│─ SSE event ─────────│ notification: ToolCall (history replay) │<─────────────│─ SSE event ─────────│ notification: ToolCallUpdate (history replay) │<─────────────│─ SSE event ─────────│ { id: 2, result: {} } │ ▼ │ │ │ │ ═══ Connection Termination ═══ │ │ │ │─── DELETE /acp ───────────────────>│ Terminate connection │ Acp-Connection-Id: │ │<────────── 202 Accepted ───────────│ #### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#content-negotiation-and-validation) Content Negotiation and Validation * `Content-Type` **MUST** be `application/json` (415 otherwise). * `Accept` **MUST** include both `application/json` and `text/event-stream` (406 otherwise). * Batch JSON-RPC requests return 501. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#websocket-request-flow) WebSocket Request Flow #### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#connection-establishment-get-with-upgrade) Connection Establishment (GET with Upgrade) Client Server │ GET /acp │ │ Upgrade: websocket │ │────────────────────────────────────────►│ │ HTTP 101 Switching Protocols │ │ Acp-Connection-Id: │ │◄────────────────────────────────────────│ │ ══════ WebSocket Channel ══════════════│ A new connection is created on upgrade. The `Acp-Connection-Id` is returned in the upgrade response headers. The client must still send `initialize` as the first JSON-RPC message over the WebSocket to negotiate capabilities before creating sessions. #### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#bidirectional-messaging) Bidirectional Messaging All messages are WebSocket text frames containing JSON-RPC. Binary frames are ignored. On disconnect, the server cleans up the connection and any associated sessions. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#unified-endpoint-routing) Unified Endpoint Routing GET /acp ├── Has Upgrade: websocket? → WebSocket handler └── No → SSE stream handler (requires Acp-Connection-Id and Acp-Session-Id) ├── Missing Acp-Connection-Id or Acp-Session-Id? → 400 Bad Request └── Valid headers → Session-scoped stream (only events for that session) POST /acp ├── Initialize request? → Create connection, return SSE with Acp-Connection-Id ├── No Acp-Connection-Id? → 400 Bad Request ├── Unknown Acp-Connection-Id? → 404 Not Found └── Has valid Acp-Connection-Id ├── session/new or session/load → Forward, return SSE with Acp-Session-Id ├── Session method without Acp-Session-Id → 400 Bad Request ├── JSON-RPC request → Forward, return SSE └── Notification/response → Forward, return 202 DELETE /acp ├── Has Acp-Connection-Id? → Terminate connection and all associated sessions └── No → 400 Bad Request ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#session-model) Session Model Connection { connection_id: String, // Acp-Connection-Id capabilities: NegotiatedCapabilities, sessions: HashMap, // keyed by Acp-Session-Id to_agent_tx: mpsc::Sender, from_agent_rx: Arc>>, handle: JoinHandle<()>, } Session { session_id: String, // Acp-Session-Id / sessionId get_listeners: Vec, // GET SSE streams for this session } The agent task is spawned once per connection. Sessions are created within a connection via `session/new`, which returns the `Acp-Session-Id` in both the HTTP response header and the JSON-RPC result body. The transport layer adapts channels to the wire format (SSE events for HTTP, text frames for WebSocket). GET listeners are always session-scoped — both `Acp-Connection-Id` and `Acp-Session-Id` are required, and the server delivers only events belonging to that session. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#mcp-streamable-http-compliance) MCP Streamable HTTP Compliance | MCP Requirement | ACP Implementation | Status | | --- | --- | --- | | POST for all client→server messages | ✅ | Compliant | | Accept header validation (406) | ✅ | Compliant | | Notifications/responses return 202 | ✅ | Compliant | | Requests return SSE stream | ✅ | Compliant | | Session ID on initialize response | ✅ (`Acp-Connection-Id`) | Compliant (renamed) | | Session ID required on subsequent requests | ✅ (`Acp-Connection-Id` required; `Acp-Session-Id` required after `session/new`) | Compliant (extended) | | GET opens SSE stream | ✅ | Compliant | | DELETE terminates session | ✅ (terminates connection) | Compliant | | 404 for unknown sessions | ✅ (unknown connection IDs) | Compliant | | Batch requests | ❌ (returns 501) | Documented deviation | | Resumability (Last-Event-ID) | ❌ | Future work | | Protocol version header | ❌ | Future work | ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#deviations-from-mcp-streamable-http) Deviations from MCP Streamable HTTP 1. **Header naming**: `Acp-Connection-Id` / `Acp-Session-Id` / `Acp-Protocol-Version` instead of MCP equivalents. `Acp-Connection-Id` maps to MCP’s `Mcp-Session-Id` but is deliberately renamed to avoid confusion with ACP’s session concept (see [Identity Model](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#identity-model) ). 2. **Two-header model**: MCP uses a single `Mcp-Session-Id` for both transport binding and session identity. ACP separates these into `Acp-Connection-Id` (connection-scoped, from `initialize`) and `Acp-Session-Id` (session-scoped, from `session/new`), because ACP sessions are an explicit protocol concept with their own lifecycle (`session/new`, `session/load`, `session/cancel`). The `Acp-Session-Id` also enables session-scoped GET listener streams. 3. **Session-scoped GET streams**: GET listeners require both `Acp-Connection-Id` and `Acp-Session-Id`. The server MUST only deliver events belonging to that session. There is no connection-scoped GET stream. MCP has no equivalent concept. 4. **WebSocket extension**: MCP doesn’t define WebSocket. ACP adds it as a required client capability. Clients MUST support WebSocket, and servers MAY choose to only support WebSocket connections. 5. **Cookie support required**: Clients MUST handle cookies on HTTP transports for the duration of the connection, enabling sticky sessions and per-connection server state. 6. **No batch requests**: Returns 501. May be added later. 7. **No resumability yet in reference implementation**: SSE event IDs and `Last-Event-ID` resumption planned as follow-up. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#implementation-plan) Implementation Plan 1. **Phase 1 — Specification** (this RFD): Define the transport spec and align terminology. 2. **Phase 2 — Reference Implementation** (in progress): Working implementation in Goose (`block/goose`) at `crates/goose-acp/src/transport/` (`transport.rs`, `http.rs`, `websocket.rs`). 3. **Phase 3 — SDK Support**: Add Streamable HTTP and WebSocket client support to Rust SDK (`sacp`), then TypeScript SDK. 4. **Phase 4 — Hardening**: Origin validation, `Acp-Protocol-Version`, SSE resumability, batch requests, security audit. [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#frequently-asked-questions) Frequently asked questions -------------------------------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#why-not-just-use-mcp-streamable-http-as-is) Why not just use MCP Streamable HTTP as-is? We largely do. The differences are: header naming (`Acp-Connection-Id` + `Acp-Session-Id` vs MCP’s single `Mcp-Session-Id`), the WebSocket extension for long-running agent sessions, the two-header model that separates connection identity from session identity, and session-scoped GET listener streams. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#why-two-headers-acp-connection-id-and-acp-session-id-instead-of-one) Why two headers (`Acp-Connection-Id` and `Acp-Session-Id`) instead of one? MCP uses a single `Mcp-Session-Id` because MCP has no protocol-level concept of sessions. ACP does — `session/new` creates a conversation with its own lifecycle. Using one header for both would conflate the initialized connection (capabilities, protocol version, auth state) with the active session (conversation context, history). Two headers let the server immediately distinguish which connection _and_ which session a request belongs to, enable session-scoped GET listener streams, and support multiple concurrent sessions within a single connection. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#why-add-websocket-support) Why add WebSocket support? A single `prompt` can generate dozens of streaming updates and ACP is more bidirectional in nature than MCP. With Streamable HTTP, the server can only push via SSE on POST responses or a separate GET stream. WebSocket provides true bidirectional messaging, lower per-message overhead, and connection persistence. Clients MUST support WebSocket so that servers can choose to only support WebSocket connections, simplifying deployment. Streamable HTTP remains available as an additional option for environments where WebSocket is not viable on the server side (e.g., serverless). ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#how-does-the-server-distinguish-websocket-from-sse-on-get) How does the server distinguish WebSocket from SSE on GET? By inspecting the `Upgrade: websocket` header. This is standard HTTP behavior. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#can-a-client-have-multiple-sessions-on-one-connection) Can a client have multiple sessions on one connection? Yes. A client may call `session/new` multiple times within a single `Acp-Connection-Id`. Each returns a distinct `Acp-Session-Id`. The client includes the appropriate `Acp-Session-Id` header (and `sessionId` in the JSON-RPC params) on subsequent requests. The `Acp-Connection-Id` header remains the same across all of them. The client may also open separate GET listener streams per session, each requiring both `Acp-Connection-Id` and `Acp-Session-Id`. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? * **Separate endpoints** (`/acp/http`, `/acp/ws`): Rejected — single endpoint is simpler; WebSocket upgrade is natural HTTP. * **WebSocket only**: Rejected — doesn’t work through all proxies; Streamable HTTP is better for stateless/serverless. * **Single header for both connection and session**: Rejected — conflates connection lifecycle with session lifecycle, prevents session-scoped GET streams, and makes multi-session connections ambiguous. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#how-does-this-interact-with-authentication) How does this interact with authentication? Authentication (see auth-methods RFD) is orthogonal and layered on top via HTTP headers, query parameters, or WebSocket subprotocols. `Acp-Connection-Id` and `Acp-Session-Id` are transport-level identifiers, not auth tokens. ### [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#what-about-the-acp-protocol-version-header) What about the `Acp-Protocol-Version` header? Clients SHOULD include it on all requests after initialization. Not yet implemented; part of Phase 4 hardening. [​](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#revision-history) Revision history ------------------------------------------------------------------------------------------------------------------ * **2025-03-10**: Initial draft based on the RFC template and goose reference implementation. * **2026-04-01**: Introduced a two-header identity model: `Acp-Connection-Id` (returned at `initialize`, binds to the connection) and `Acp-Session-Id` (returned at `session/new`, scopes to a session). This addresses feedback that the original single `Acp-Session-Id` conflated transport binding with ACP session identity, and enables session-scoped GET listener streams for targeted server-to-client event delivery. Removed connection-scoped GET streams — all GET SSE listeners now require both `Acp-Connection-Id` and `Acp-Session-Id`. * **2026-04-15**: Minor edits Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/custom-llm-endpoint) [Closing active sessions\ \ Next](https://agentclientprotocol.com/rfds/session-close) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#what-we-propose-to-do-about-it) * [1\. Mostly adopts MCP Streamable HTTP semantics with ACP-specific headers](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#1-mostly-adopts-mcp-streamable-http-semantics-with-acp-specific-headers) * [2\. Separates connection identity from session identity with two headers](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#2-separates-connection-identity-from-session-identity-with-two-headers) * [3\. Adds WebSocket as a first-class upgrade on the same endpoint](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#3-adds-websocket-as-a-first-class-upgrade-on-the-same-endpoint) * [4\. Requires cookie support on HTTP transports](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#4-requires-cookie-support-on-http-transports) * [5\. Defines a unified routing model](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#5-defines-a-unified-routing-model) * [6\. Preserves the full ACP lifecycle](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#6-preserves-the-full-acp-lifecycle) * [Shiny future](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#implementation-details-and-plan) * [Transport Architecture](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#transport-architecture) * [Identity Model](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#identity-model) * [Streamable HTTP Message Flow](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#streamable-http-message-flow) * [Content Negotiation and Validation](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#content-negotiation-and-validation) * [WebSocket Request Flow](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#websocket-request-flow) * [Connection Establishment (GET with Upgrade)](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#connection-establishment-get-with-upgrade) * [Bidirectional Messaging](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#bidirectional-messaging) * [Unified Endpoint Routing](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#unified-endpoint-routing) * [Session Model](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#session-model) * [MCP Streamable HTTP Compliance](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#mcp-streamable-http-compliance) * [Deviations from MCP Streamable HTTP](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#deviations-from-mcp-streamable-http) * [Implementation Plan](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#implementation-plan) * [Frequently asked questions](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#frequently-asked-questions) * [Why not just use MCP Streamable HTTP as-is?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#why-not-just-use-mcp-streamable-http-as-is) * [Why two headers (Acp-Connection-Id and Acp-Session-Id) instead of one?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#why-two-headers-acp-connection-id-and-acp-session-id-instead-of-one) * [Why add WebSocket support?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#why-add-websocket-support) * [How does the server distinguish WebSocket from SSE on GET?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#how-does-the-server-distinguish-websocket-from-sse-on-get) * [Can a client have multiple sessions on one connection?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#can-a-client-have-multiple-sessions-on-one-connection) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [How does this interact with authentication?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#how-does-this-interact-with-authentication) * [What about the Acp-Protocol-Version header?](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#what-about-the-acp-protocol-version-header) * [Revision history](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport#revision-history) --- # Session Info Update - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-info-update#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Completed Session Info Update [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@ignatov](https://github.com/ignatov) [​](https://agentclientprotocol.com/rfds/session-info-update#elevator-pitch) Elevator pitch ---------------------------------------------------------------------------------------------- Add a `session_info_update` variant to the existing `SessionUpdate` notification type that allows agents to update session metadata (particularly title/name), enabling dynamic session identification in client UIs without requiring a new endpoint. [​](https://agentclientprotocol.com/rfds/session-info-update#status-quo) Status quo -------------------------------------------------------------------------------------- Currently, the ACP protocol provides session management through `session/new`, `session/load`, and `session/list` (unstable). The `session/list` endpoint returns `SessionInfo` objects that include an optional `title` field for displaying session names in client UIs. However, there are several problems: 1. **No way to communicate title updates** - The `title` field in `SessionInfo` is static in the list response. Agents cannot dynamically update it as the session evolves. 2. **No mechanism for real-time metadata updates** - Unlike commands (`available_commands_update`) or modes (`current_mode_update`), there’s no way for agents to: * Auto-generate titles after the first meaningful exchange * Update titles as conversation context shifts * Provide custom metadata that reflects session state 3. **Inconsistent with protocol patterns** - Other dynamic session properties use `session/update` notifications (commands, modes, plans), but metadata has no equivalent mechanism. The current workaround is for clients to: * Maintain their own title mapping (doesn’t persist or sync) * Only show static metadata from `session/list` * Have no way to receive agent-generated titles in real-time [​](https://agentclientprotocol.com/rfds/session-info-update#what-we-propose-to-do-about-it) What we propose to do about it ------------------------------------------------------------------------------------------------------------------------------ Add a new `session_info_update` variant to the existing `SessionUpdate` discriminated union that allows agents to notify clients about metadata changes. This update would: 1. **Follow the existing `SessionUpdate` pattern**: * Uses the same notification mechanism as `available_commands_update`, `current_mode_update`, etc. * Sent via `session/update` method * Agent-initiated, no request/response needed 2. **Align with `SessionInfo` structure**: * Contains the same fields as `SessionInfo` from `session/list` * All fields are optional (partial updates) * Enables incremental metadata updates * **Important**: `SessionInfoUpdate` must stay aligned with `SessionInfo` - when new fields are added to `SessionInfo`, they should also be added to `SessionInfoUpdate` as optional fields 3. **Support common use cases**: * Agent auto-generates title after first prompt * Agent updates title as conversation context shifts * Agent provides custom metadata for client features (tags, status, etc.) * User explicitly requests title change (agent responds with update notification) 4. **Integrate seamlessly**: * No new capability required (uses existing `session/update` mechanism) * Compatible with `session/list` - metadata should persist and be reflected in list responses * Works during active sessions ### [​](https://agentclientprotocol.com/rfds/session-info-update#notification-structure) Notification Structure The agent sends a `session/update` notification with `sessionUpdate: "session_info_update"`: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Implement user authentication", "_meta": { "tags": ["feature", "auth"], "priority": "high" } } } } ### [​](https://agentclientprotocol.com/rfds/session-info-update#sessioninfoupdate-type) SessionInfoUpdate Type The update type mirrors `SessionInfo` but with all fields optional: { sessionUpdate: "session_info_update", title?: string | null, // Update or clear the title updatedAt?: string | null, // ISO 8601 timestamp (usually agent sets this) _meta?: object | null // Custom metadata (merged with existing) } **Note:** `sessionId` and `cwd` are NOT included since: * `sessionId` is already in the notification’s `params` * `cwd` is immutable and set during `session/new` ### [​](https://agentclientprotocol.com/rfds/session-info-update#examples) Examples #### [​](https://agentclientprotocol.com/rfds/session-info-update#update-title-and-working-directory-metadata) Update title and working directory metadata After the user sends their first meaningful prompt, the agent can generate and send a title along with metadata about the working directory: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Debug authentication timeout", "_meta": { "projectName": "api-server", "branch": "main" } } } } #### [​](https://agentclientprotocol.com/rfds/session-info-update#update-title-as-conversation-evolves) Update title as conversation evolves As the conversation shifts focus: { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Debug authentication timeout → Add retry logic" } } } [​](https://agentclientprotocol.com/rfds/session-info-update#shiny-future) Shiny future ------------------------------------------------------------------------------------------ Once this feature exists: 1. **Dynamic session identification** - Agents can: * Auto-generate meaningful titles from conversation content * Update titles as conversations evolve * Provide rich metadata for better organization 2. **Improved client UIs** - Clients can: * Show real-time title updates in session lists * Display session status, tags, or other metadata * Update UI immediately without polling `session/list` 3. **Consistent protocol patterns** - Session metadata updates work like other dynamic session properties (commands, modes), creating a unified model 4. **Bidirectional workflows** - Combined with a potential future request method: * User renames session → client sends request → agent acknowledges with `session_info_update` notification * Agent auto-generates title → sends `session_info_update` notification → client displays it 5. **Enhanced use cases**: * Session templates that auto-set titles and tags * Progress indicators via `_meta` * Integration with external tools via metadata * Rich session browsing and filtering [​](https://agentclientprotocol.com/rfds/session-info-update#implementation-details-and-plan) Implementation details and plan -------------------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/session-info-update#phase-1-schema-changes) Phase 1: Schema Changes 1. **Update `schema.unstable.json`**: * Add `SessionInfoUpdate` type definition * Add new variant to `SessionUpdate` oneOf array * Align fields with `SessionInfo` but make all optional { "SessionInfoUpdate": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUpdate to session metadata. All fields are optional to support partial updates.", "properties": { "_meta": { "description": "Extension point for implementations" }, "title": { "description": "Human-readable title for the session", "type": ["string", "null"] }, "updatedAt": { "description": "ISO 8601 timestamp of last activity", "type": ["string", "null"] } }, "type": "object" } } Add to `SessionUpdate` oneOf: { "allOf": [\ {\ "$ref": "#/$defs/SessionInfoUpdate"\ }\ ], "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUpdate to session metadata", "properties": { "sessionUpdate": { "const": "session_info_update", "type": "string" } }, "required": ["sessionUpdate"], "type": "object" } ### [​](https://agentclientprotocol.com/rfds/session-info-update#phase-2-protocol-documentation) Phase 2: Protocol Documentation 2. **Create documentation** in `/docs/protocol/session-metadata.mdx`: * Explain the notification mechanism * Provide examples of common patterns * Document merge semantics for `_meta` * Clarify relationship with `session/list` 3. **Update existing docs**: * Reference in `/docs/protocol/session-setup.mdx` * Add to `/docs/protocol/prompt-turn.mdx` session update section ### [​](https://agentclientprotocol.com/rfds/session-info-update#phase-3-sdk-implementation) Phase 3: SDK Implementation 4. **Implement in Rust SDK**: * Add `SessionInfoUpdate` struct * Add variant to `SessionUpdate` enum * Update notification handling in agent and client traits * Add helper methods for common patterns 5. **Implement in TypeScript SDK** (if applicable): * Add TypeScript types * Update notification handlers * Add helper methods ### [​](https://agentclientprotocol.com/rfds/session-info-update#phase-4-example-implementation) Phase 4: Example Implementation 6. **Update example agents**: * Demonstrate auto-generating title from first prompt * Show updating metadata during session * Example of using `_meta` for custom fields ### [​](https://agentclientprotocol.com/rfds/session-info-update#compatibility-considerations) Compatibility Considerations * **Fully backward compatible**: This adds a new notification variant to an existing mechanism * **No breaking changes**: Existing agents and clients continue working * **Graceful degradation**: Clients that don’t handle this notification simply ignore it * **No new capability needed**: Uses existing `session/update` infrastructure ### [​](https://agentclientprotocol.com/rfds/session-info-update#design-decisions) Design Decisions **Why notification instead of request/response?** * Consistent with existing `SessionUpdate` patterns (`available_commands_update`, `current_mode_update`) * Agents initiate updates based on conversation state * Simpler than bidirectional request/response * Enables real-time updates without polling **Why make all fields optional?** * Allows partial updates (only update what changed) * More efficient - don’t resend unchanged data * Flexible for different use cases * Mirrors partial update patterns in other protocols **Why not include `sessionId` and `cwd` in the update?** * `sessionId` is already in the notification params * `cwd` is immutable (set in `session/new`, never changes) * Keeps update focused on mutable metadata **How do `_meta` updates work?** * **Merge semantics**: New `_meta` fields are merged with existing ones * To clear a specific field: `"_meta": { "fieldName": null }` * To clear all custom metadata: `"_meta": null` ### [​](https://agentclientprotocol.com/rfds/session-info-update#security-considerations) Security Considerations * **No additional security concerns**: Uses existing session authentication * **Input validation**: * Agents should validate title length (recommend 500 chars max) * Sanitize metadata to prevent injection * Validate `_meta` structure based on agent requirements * **Resource limits**: Agents should limit update frequency and metadata size [​](https://agentclientprotocol.com/rfds/session-info-update#frequently-asked-questions) Frequently asked questions ---------------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/session-info-update#why-not-create-a-new-endpoint-like-session/update-metadata) Why not create a new endpoint like `session/update-metadata`? The notification pattern is more appropriate because: 1. **Consistency**: Other dynamic session properties (commands, modes) use notifications 2. **Agent-initiated**: Agents typically generate titles from conversation context 3. **Real-time**: No request/response overhead, updates flow naturally 4. **Simpler**: Reuses existing `session/update` infrastructure ### [​](https://agentclientprotocol.com/rfds/session-info-update#how-does-this-work-with-session/list) How does this work with `session/list`? The updated metadata should persist and be reflected in subsequent `session/list` calls. The notification provides real-time updates to connected clients, while `session/list` provides the current state for discovery. ### [​](https://agentclientprotocol.com/rfds/session-info-update#can-clients-trigger-title-updates) Can clients trigger title updates? This RFD covers agent-initiated updates. Client-initiated updates could work by: 1. Client sends a prompt asking to rename session 2. Agent updates its internal state 3. Agent sends `session_info_update` notification 4. Client receives and displays the update A future RFD could add explicit request/response for this if needed. ### [​](https://agentclientprotocol.com/rfds/session-info-update#what-if-multiple-updates-are-sent-in-quick-succession) What if multiple updates are sent in quick succession? Clients should apply updates incrementally in order. Each notification represents a delta, not a full replacement (except for fields explicitly set to `null`). ### [​](https://agentclientprotocol.com/rfds/session-info-update#should-updatedat-be-automatically-set-by-the-agent) Should `updatedAt` be automatically set by the agent? Yes, typically the agent should update this timestamp when any session activity occurs, not just when metadata changes. However, including it in `session_info_update` allows agents to explicitly control it if needed. ### [​](https://agentclientprotocol.com/rfds/session-info-update#do-agents-need-a-new-capability-for-this) Do agents need a new capability for this? No. All agents that support `session/update` notifications can send this variant. Clients that don’t recognize it will ignore it (standard JSON-RPC behavior). ### [​](https://agentclientprotocol.com/rfds/session-info-update#how-does-this-interact-with-session/fork) How does this interact with `session/fork`? When forking, the parent session’s metadata could be copied (implementation choice). The forked session would have its own `sessionId` and could receive separate `session_info_update` notifications. ### [​](https://agentclientprotocol.com/rfds/session-info-update#what-happens-if-title-is-too-long) What happens if title is too long? This is an implementation choice. Agents MAY: * Truncate long titles * Reject updates (though this is a notification, so no error response) * Set a reasonable limit (e.g., 500 characters) Clients SHOULD handle long titles gracefully (truncate in UI, show tooltip, etc.). ### [​](https://agentclientprotocol.com/rfds/session-info-update#can-meta-have-nested-objects) Can `_meta` have nested objects? Yes, `_meta` is an arbitrary object. Agents define its structure. The merge semantics apply recursively - nested objects are merged, not replaced entirely. ### [​](https://agentclientprotocol.com/rfds/session-info-update#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? Several alternatives were considered: 1. **Add a new request/response endpoint (`session/update-metadata`)** - This would be inconsistent with how other dynamic session properties (commands, modes) are handled. The notification pattern is more appropriate for agent-initiated updates. 2. **Add title parameter to `session/new`** - Only allows setting title at creation time, doesn’t support dynamic updates as the conversation evolves. 3. **Client-side only metadata tracking** - Doesn’t work across devices, can get out of sync, and duplicates storage. This is the current workaround and has significant limitations. 4. **Generic `session/update` request for all properties** - Could conflict with immutable properties (sessionId, cwd) and has unclear semantics about what can be updated. The proposed notification-based approach: * **Consistent** with existing protocol patterns * **Flexible** for both agent-initiated and user-initiated updates * **Simple** to implement and understand * **Extensible** via `_meta` field [​](https://agentclientprotocol.com/rfds/session-info-update#revision-history) Revision history -------------------------------------------------------------------------------------------------- * **2025-11-28**: Initial draft proposal Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/session-list) [ACP Agent Registry\ \ Next](https://agentclientprotocol.com/rfds/acp-agent-registry) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-info-update#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-info-update#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-info-update#what-we-propose-to-do-about-it) * [Notification Structure](https://agentclientprotocol.com/rfds/session-info-update#notification-structure) * [SessionInfoUpdate Type](https://agentclientprotocol.com/rfds/session-info-update#sessioninfoupdate-type) * [Examples](https://agentclientprotocol.com/rfds/session-info-update#examples) * [Update title and working directory metadata](https://agentclientprotocol.com/rfds/session-info-update#update-title-and-working-directory-metadata) * [Update title as conversation evolves](https://agentclientprotocol.com/rfds/session-info-update#update-title-as-conversation-evolves) * [Shiny future](https://agentclientprotocol.com/rfds/session-info-update#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-info-update#implementation-details-and-plan) * [Phase 1: Schema Changes](https://agentclientprotocol.com/rfds/session-info-update#phase-1-schema-changes) * [Phase 2: Protocol Documentation](https://agentclientprotocol.com/rfds/session-info-update#phase-2-protocol-documentation) * [Phase 3: SDK Implementation](https://agentclientprotocol.com/rfds/session-info-update#phase-3-sdk-implementation) * [Phase 4: Example Implementation](https://agentclientprotocol.com/rfds/session-info-update#phase-4-example-implementation) * [Compatibility Considerations](https://agentclientprotocol.com/rfds/session-info-update#compatibility-considerations) * [Design Decisions](https://agentclientprotocol.com/rfds/session-info-update#design-decisions) * [Security Considerations](https://agentclientprotocol.com/rfds/session-info-update#security-considerations) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-info-update#frequently-asked-questions) * [Why not create a new endpoint like session/update-metadata?](https://agentclientprotocol.com/rfds/session-info-update#why-not-create-a-new-endpoint-like-session%2Fupdate-metadata) * [How does this work with session/list?](https://agentclientprotocol.com/rfds/session-info-update#how-does-this-work-with-session%2Flist) * [Can clients trigger title updates?](https://agentclientprotocol.com/rfds/session-info-update#can-clients-trigger-title-updates) * [What if multiple updates are sent in quick succession?](https://agentclientprotocol.com/rfds/session-info-update#what-if-multiple-updates-are-sent-in-quick-succession) * [Should updatedAt be automatically set by the agent?](https://agentclientprotocol.com/rfds/session-info-update#should-updatedat-be-automatically-set-by-the-agent) * [Do agents need a new capability for this?](https://agentclientprotocol.com/rfds/session-info-update#do-agents-need-a-new-capability-for-this) * [How does this interact with session/fork?](https://agentclientprotocol.com/rfds/session-info-update#how-does-this-interact-with-session%2Ffork) * [What happens if title is too long?](https://agentclientprotocol.com/rfds/session-info-update#what-happens-if-title-is-too-long) * [Can \_meta have nested objects?](https://agentclientprotocol.com/rfds/session-info-update#can-meta-have-nested-objects) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/session-info-update#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [Revision history](https://agentclientprotocol.com/rfds/session-info-update#revision-history) --- # Session Config Options - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/session-config-options#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Completed Session Config Options [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/session-config-options#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------------------- > What are you proposing to change? Allow Agents to provide an arbitrary list of configuration selectors for a given session. Rather than only supporting modes or models, we can allow each Agent to more flexibly specify which configurations to allow the Client to offer the user. [​](https://agentclientprotocol.com/rfds/session-config-options#status-quo) Status quo ----------------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? Currently, we allow Agents to [specify a list of modes](https://agentclientprotocol.com/protocol/session-modes) they can run in. The state of the currently selected item is allowed to be modified by both the [Client](https://agentclientprotocol.com/protocol/session-modes#from-the-client) and the [Agent](https://agentclientprotocol.com/protocol/session-modes#from-the-agent) . The obvious next selector was a [model selector](https://github.com/agentclientprotocol/agent-client-protocol/pull/182) . However, when implementing this, it became clear that even for our current agents, it is not just as simple as “which model do you want?”, but also which variant of a given model in terms of thinking parameters that might be better to express as yet another selector. Adding more hard-coded selector options would potentially lead the protocol to need to support many optional ones, or implementors would need to try to find the best existing selector to hack an option into if there wasn’t an obvious fit. And if, a few months from now, no agents support something like a mode or reasoning selector, the protocol is left with leftover methods no one really uses, cluttering the interface. Since this space is moving fast, we ideally would find a more flexible option with enough constraints to allow Clients and Agents to both reason about the options provided. [​](https://agentclientprotocol.com/rfds/session-config-options#what-we-propose-to-do-about-it) What we propose to do about it --------------------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? Instead, we can allow Agents to provide configuration options in the `session/new` response that not only provide a list of options, but also a `key` of some kind that is a unique identifier for that selector. Additionally, we can optionally allow an Agent to mark each option with a semantic category so that Clients can reliably distinguish broadly common option types (e.g. model selector vs session mode selector vs thought/reasoning level), without needing to infer meaning from the option `id` or `name`. This is intended for UX only (e.g. keyboard shortcuts, icons, preferred placement), and MUST NOT be required for correctness. When the Client receives or sends an update to this selector, it would require both the selector key and the key for the new value. To start, we could continue offering single-value selectors (dropdowns), but allow for the Agent to decide what those are for. [​](https://agentclientprotocol.com/rfds/session-config-options#shiny-future) Shiny future --------------------------------------------------------------------------------------------- > How will things will play out once this feature exists? The Agent provides a list of available configuration options. The Agent cannot rely on the Client to set or even display these options, as it may not support it. So an Agent MUST always have a default configuration value for every option it provides, and MUST be able to run a turn without these configuration options being set. The Client can render the options provided, send updated values to the Agent, and also display any changes the Agent made during the course of it’s execution (for example, if it changes modes or models because of fallbacks or a change in strategy, so that the user can always see the current state). Since we are moving to a world in which there are multiple configuration options, some of which may depend on each other, the Agent MUST provide the complete set of configuration options and their current values whenever a change is made. We would tradeoff some extra data being sent to the Client in order to help minimize the amount of state required to be managed by the Client. The Client would submit a new value, and receive back the full state of all configuration options that it can then replace it’s current state with and render. So if changing a model means there are no thinking options, or a new option becomes available, or another value needs to change because the values of an option are different, the Agent will reflect this in its response by providing the entire new state (or an error if it is somehow an invalid selection). [​](https://agentclientprotocol.com/rfds/session-config-options#implementation-details-and-plan) Implementation details and plan ----------------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? To start, we can implement this based on the [Session Modes](https://agentclientprotocol.com/protocol/session-modes) api. Something like an `InitializeResponse` that looks like: { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "configOptions": [\ {\ "id": "mode", // this is the unique `key` for communication about which option is being used\ "name": "Session Mode", // Human-readable label for the option\ "description": "Optional description for the Client to display to the user."\ "category": "mode",\ "type": "select",\ "currentValue": "ask",\ "options": [\ {\ "value": "ask",\ "name": "Ask",\ "description": "Request permission before making any changes"\ },\ {\ "value": "code",\ "name": "Code",\ "description": "Write and modify code with full tool access"\ }\ ]\ },\ {\ "id": "models",\ "name": "Model",\ "category": "model",\ "type": "select",\ "currentValue": "ask",\ "options": [\ {\ "value": "model-1",\ "name": "Model 1",\ "description": "The fastest model"\ },\ {\ "value": "model-2",\ "name": "Model 2",\ "description": "The most powerful model"\ }\ ]\ }\ ] } } ### [​](https://agentclientprotocol.com/rfds/session-config-options#option-category-optional) Option category (optional) Each top-level config option MAY include an optional `category` field. This is intended to help Clients distinguish broadly common selectors and provide a consistent UX (for example, attaching keyboard shortcuts to the first option of a given category). In addition to `category`, Clients SHOULD use the ordering of the `configOptions` array as provided by the Agent as the primary way to establish priority and resolve ties. For example, if multiple options share the same `category`, a Client can prefer the first matching option in the list when assigning keyboard shortcuts or deciding which options to surface most prominently. `category` is semantic metadata and MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use. Category names that do not begin with `_` are reserved for the ACP spec. Proposed enum: * `mode` - Session mode selector * `model` - Model selector * `thought_level` - Thought/reasoning level selector * Any string beginning with `_` - Custom category (e.g., `_my_custom_category`) When we introduce this, we could also allow for grouped options, in case there are logical sub-headers and groupings for the options in an individual selector. { "id": "models", "name": "Model", "currentValue": "ask", "type": "select", "options": [\ {\ "group": "Provider A",\ "options": [\ {\ "value": "model-1",\ "name": "Model 1",\ "description": "The fastest model"\ }\ ]\ },\ {\ "group": "Provider B",\ "options": [\ {\ "value": "model-2",\ "name": "Model 2",\ "description": "The most powerful model"\ }\ ]\ }\ ] } We use a list of objects for all of these, to ensure consistent ordering of both the config options and the possible values across languages that may or may not preserve ordering. For grouping options, it needs to be explored whether or not grouped and ungrouped options can be interspersed, or if we need to restrict to one mode or the other (likely the latter). For updating the value from the client and agent, it would follow the same pattern as [session modes](https://agentclientprotocol.com/protocol/session-modes#from-the-client) but have an additional key. { "jsonrpc": "2.0", "id": 2, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123def456", "configId": "mode", "value": "code" } } And the response to this request would return the full list of config options with current values. { "jsonrpc": "2.0", "id": 2, "result": { "configOptions": [\ {\ "id": "mode",\ "name": "Session Mode",\ "type": "select",\ "currentValue": "ask",\ "options": [..]\ },\ {\ "id": "models",\ "name": "Model",\ "type": "select",\ "currentValue": "ask",\ "options": [..]\ }\ ] } } The notification would return the full list of config options with current values as well. { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "config_option_update", "configOptions": [\ {\ "id": "mode",\ "name": "Session Mode",\ "type": "select",\ "currentValue": "ask",\ "options": [..]\ },\ {\ "id": "models",\ "name": "Model",\ "type": "select",\ "currentValue": "ask",\ "options": [..]\ }\ ] } } } We would also likely move session modes to be `@deprecated` in favor of this approach. Until it is removed, we may want Agents to support both fields, and then the Client, if it uses the new config options, should only use the config options supplied and not the `modes` field to avoid duplication. The config options would also take a `type` field to specify different forms of input for the Client to display. If a client receives an option it doesn’t recognize, it should ignore it. Since the Agent is required to have a default value, it can gracefully degrade and ignore the option and the Agent should handle it regardless. The Client should also treat the list of options as prioritized by the Agent. So, if for some reason the Agent provides more options than the Client can reasonably display, the Client should show as many as possible, starting at the beginning of the list. We will start with just supporting `select` for now, and expand to other types as needed. [​](https://agentclientprotocol.com/rfds/session-config-options#frequently-asked-questions) Frequently asked questions ------------------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/session-config-options#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) What alternative approaches did you consider, and why did you settle on this one? As noted, the Zed team already looked into and implemented experimental support for a model selector. However, this has already diverged from how the Codex CLI is modeling their model selector as of last week, so it seems reasonable to, as per a core design principle of the protocol, only limit the Agent implementations where necessary for the Client to render a faithful UX. Maximizing flexibility for the Agent as they iterate on the best way to model new paradigms seems key here, and it is unclear whether the Client benefits from knowing which type of selector this is. We originally discussed internally having a design closer to this proposal, however walked it back thinking it would be helpful for the Client to know what was being selected. However, as we’ve now dealt with multiple Agent implementations, it is unclear if this has actually helped the Client, and allowing for more flexibility seems desirable. ### [​](https://agentclientprotocol.com/rfds/session-config-options#what-about-connection-level-configuration-options) What about connection-level configuration options? This RFD is only concerned with session-level configuration, for which it seems reasonable to require that the Agent can select a default value at all times and not require input from the client before continuing. There seems to be another type of configuration option that is needed when first setting up an Agent (i.e. provider options, plugins, etc.) that are more persistent and may be required by an Agent prior to being able to create a session. These would need to be tackled somewhere closer to the initialization phase, or elsewhere and are out of scope for this RFD. ### [​](https://agentclientprotocol.com/rfds/session-config-options#what-about-multi-value-selectors-or-checkboxes-or-insert-favorite-input-option-here) What about multi-value selectors? or checkboxes? Or _insert favorite input option here_? This is a question we should discuss of how much complexity we want to introduce for the first version, and how we want to express this to via Client capabilities to allow for more option types in the future. [​](https://agentclientprotocol.com/rfds/session-config-options#revision-history) Revision history ----------------------------------------------------------------------------------------------------- * 2025-10-29: Initial draft * 2026-01-09: Add option categories * 2026-01-15: Allow for category extensions Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/introduce-rfd-process) [Session List\ \ Next](https://agentclientprotocol.com/rfds/session-list) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/session-config-options#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/session-config-options#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/session-config-options#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/session-config-options#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/session-config-options#implementation-details-and-plan) * [Option category (optional)](https://agentclientprotocol.com/rfds/session-config-options#option-category-optional) * [Frequently asked questions](https://agentclientprotocol.com/rfds/session-config-options#frequently-asked-questions) * [What alternative approaches did you consider, and why did you settle on this one?](https://agentclientprotocol.com/rfds/session-config-options#what-alternative-approaches-did-you-consider-and-why-did-you-settle-on-this-one) * [What about connection-level configuration options?](https://agentclientprotocol.com/rfds/session-config-options#what-about-connection-level-configuration-options) * [What about multi-value selectors? or checkboxes? Or insert favorite input option here?](https://agentclientprotocol.com/rfds/session-config-options#what-about-multi-value-selectors-or-checkboxes-or-insert-favorite-input-option-here) * [Revision history](https://agentclientprotocol.com/rfds/session-config-options#revision-history) --- # Elicitation: Structured User Input - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/elicitation#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Elicitation: Structured User Input [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) * Author(s): [@yordis](https://github.com/yordis) * Champion: [@benbrandt](https://github.com/benbrandt) [​](https://agentclientprotocol.com/rfds/elicitation#elevator-pitch) Elevator pitch -------------------------------------------------------------------------------------- Add support for agents to request structured information from users through a standardized elicitation mechanism, aligned with [MCP’s elicitation feature](https://modelcontextprotocol.io/specification/draft/client/elicitation) . This allows agents to ask follow-up questions, collect authentication credentials, gather preferences, and request required information without side-channel communication or ad-hoc client UI implementations. [​](https://agentclientprotocol.com/rfds/elicitation#status-quo) Status quo ------------------------------------------------------------------------------ Currently, agents have two limited mechanisms for gathering user input: 1. **Session Config Options** (PR #210): Pre-declared, persistent configuration (model, mode, etc.) with default values required. These are available at session initialization and changes are broadcast to the client. 2. **Unstructured text in turn responses**: Agents can include prompts in their responses, but clients have no standardized way to recognize auth requests, form inputs, or structured selections, leading to inconsistent UX across agents. However, there is no mechanism for agents to: * Request ad-hoc information during a turn (e.g., “Which of these approaches should I proceed with?” from PR #340) * Ask for authentication credentials in a recognized, secure way (pain point from PR #330) * Collect open-ended text input with validation constraints * Handle decision points that weren’t anticipated at session initialization * Request sensitive information via out-of-band mechanisms (browser-based OAuth) The community has already identified the need for this: PR #340 explored a `session/select` mechanism but concluded that leveraging an MCP-like elicitation pattern would be more aligned with how clients will already support MCP servers. PR #330 recognized that authentication requests specifically need special handling separate from regular session data. This gap limits the richness of agent-client interaction and forces both agents and clients to implement ad-hoc solutions for structured user input. [​](https://agentclientprotocol.com/rfds/elicitation#what-we-propose-to-do-about-it) What we propose to do about it ---------------------------------------------------------------------------------------------------------------------- We propose introducing an elicitation mechanism for agents to request structured information from users, aligned with [MCP’s draft elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation) . This addresses discussions from PR #340 about standardizing user selection flows and PR #330 about secure authentication handling. The mechanism would: 1. **Use restricted JSON Schema** (as discussed in PR #210): Like MCP, constrain JSON Schema to a useful subset—flat objects with primitive properties (`string`, `number`, `integer`, `boolean`) plus supported formats and enum values. Clients decide how to render UI based on the schema. 2. **Support two elicitation modes** (following [MCP SEP-1036](https://modelcontextprotocol.io/community/seps/1036-url-mode-elicitation-for-secure-out-of-band-intera) ): * **Form mode** (in-band): Structured data collection via JSON Schema forms * **URL mode** (out-of-band): Browser-based flows for sensitive operations like OAuth (addressing PR #330 authentication pain points) 3. **Request/response pattern**: Agents send elicitation requests via an `elicitation/create` method and receive responses. The agent controls when to send requests and whether to wait for responses before proceeding. Unlike Session Config Options (which are persistent), elicitation requests are transient. 4. **Support client capability negotiation**: Clients declare elicitation support via a structured capability object that distinguishes between `form`\-based and `url`\-based elicitation (following MCP’s capability model). This allows clients to support one or both modalities, enables agents to pass capabilities along to MCP servers, and handles graceful degradation when clients have limited elicitation support. 5. **Provide rich context**: Agents can include title, description, detailed constraints, and examples—helping clients render consistent, helpful UI without custom implementations. 6. **Enable out-of-band flows**: Support URL-mode elicitation (like MCP) for sensitive operations like authentication, where credentials bypass the agent entirely (addressing the core pain point in PR #330). [​](https://agentclientprotocol.com/rfds/elicitation#shiny-future) Shiny future ---------------------------------------------------------------------------------- Once implemented, agents can: * Ask users “Which approach would you prefer: A or B?” and receive a structured response * Request text input: “What’s the name for this function?” * Collect multiple related pieces of information in a single request * Guide users through decision trees with follow-up questions * Provide rich context (descriptions, examples, constraints) for what they’re asking for Clients can: * Present a consistent, standardized UI for elicitation across all agents * Validate user input against constraints before sending to the agent * Cache elicitation history and offer suggestions based on previous responses * Provide keyboard shortcuts and accessibility features for common elicitation types [​](https://agentclientprotocol.com/rfds/elicitation#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------ ### [​](https://agentclientprotocol.com/rfds/elicitation#alignment-with-mcp) Alignment with MCP This proposal follows MCP’s draft elicitation specification. See [MCP Elicitation Specification](https://modelcontextprotocol.io/specification/draft/client/elicitation) for detailed guidance. ACP uses the same JSON Schema constraint approach and capability model, adapted for ACP interactions. Key differences from MCP: * MCP elicitation is tool-call-scoped; ACP elicitation may be tool-call-scoped, session-scoped, or request-scoped * ACP uses `elicitation/create` method (same as MCP) * ACP includes an optional `toolCallId` field to support tool-call-scoped elicitations (e.g., when an agent receives an MCP elicitation during a tool call and needs to redirect it to the user) * ACP must integrate with existing Session Config Options (which also use schema constraints) ### [​](https://agentclientprotocol.com/rfds/elicitation#elicitation-request-structure) Elicitation Request Structure Agents send elicitation requests when they need information from the user. This is a request/response pattern—the agent sends the request and waits for the client’s response. **Example 1: Form Mode - User Selection (from PR #340)** { "mode": "form", "message": "How would you like me to approach this refactoring?", "requestedSchema": { "type": "object", "properties": { "strategy": { "type": "string", "title": "Refactoring Strategy", "description": "Choose how aggressively to refactor", "oneOf": [\ {\ "const": "conservative",\ "title": "Conservative - Minimal changes"\ },\ { "const": "balanced", "title": "Balanced (Recommended)" },\ {\ "const": "aggressive",\ "title": "Aggressive - Maximum optimization"\ }\ ], "default": "balanced" } }, "required": ["strategy"] } } **Example 2: URL Mode - Authentication (from PR #330, out-of-band OAuth)** { "mode": "url", "elicitationId": "github-oauth-123", "url": "https://agent.example.com/connect?elicitationId=github-oauth-123", "message": "Please authorize access to your GitHub repositories to continue." } **Example 3: Form Mode - Text Input with Constraints** { "mode": "form", "message": "What should this function be named?", "requestedSchema": { "type": "object", "properties": { "name": { "type": "string", "title": "Function Name", "description": "Must be a valid identifier", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$", "default": "processData" } }, "required": ["name"] } } **Example 4: Form Mode - Multiple Fields** { "mode": "form", "message": "Please provide configuration details", "requestedSchema": { "type": "object", "properties": { "name": { "type": "string", "title": "Project Name" }, "port": { "type": "integer", "title": "Port Number", "minimum": 1024, "maximum": 65535, "default": 3000 }, "enableLogging": { "type": "boolean", "title": "Enable Logging", "default": true } }, "required": ["name"] } } ### [​](https://agentclientprotocol.com/rfds/elicitation#elicitation-modes) Elicitation Modes Following MCP’s approach (specifically [SEP-1036](https://modelcontextprotocol.io/community/seps/1036-url-mode-elicitation-for-secure-out-of-band-intera) ), elicitation supports two modes: **Form mode** (in-band): Servers request structured data from users using restricted JSON Schema. The client decides how to render the form UI based on the schema. **URL mode** (out-of-band): Servers direct users to external URLs for sensitive interactions that must not pass through the agent or client (OAuth flows, payments, credential collection, etc.). This distinction is reflected in the client capabilities model, allowing clients to declare support for one or both modalities. **Normative requirements:** * Clients declaring the `elicitation` capability MUST support at least one mode (`form` or `url`). * Agents MUST NOT send elicitation requests with modes that are not supported by the client. * For URL mode, the `url` parameter MUST contain a valid URL. * Agents MUST NOT return the `URLElicitationRequiredError` (code `-32042`) except when URL mode elicitation is required. ### [​](https://agentclientprotocol.com/rfds/elicitation#restricted-json-schema) Restricted JSON Schema Aligning with [MCP’s draft elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation) , form mode elicitation uses a restricted subset of JSON Schema. Schemas are limited to flat objects with primitive properties only—the client decides how to render appropriate input UI based on the schema. **Supported primitive types:** 1. **String Schema** { "type": "string", "title": "Display Name", "description": "Description text", "minLength": 3, "maxLength": 50, "pattern": "^[A-Za-z]+$", "format": "email", "default": "user@example.com" } Supported formats: `email`, `uri`, `date`, `date-time` 2. **Number Schema** { "type": "number", "title": "Display Name", "description": "Description text", "minimum": 0, "maximum": 100, "default": 50 } Also supports `"type": "integer"` for whole numbers. 3. **Boolean Schema** { "type": "boolean", "title": "Display Name", "description": "Description text", "default": false } 4. **Enum Schema** (for selections) Single-select enum (without titles): { "type": "string", "title": "Color Selection", "description": "Choose your favorite color", "enum": ["Red", "Green", "Blue"], "default": "Red" } Single-select enum (with titles): { "type": "string", "title": "Color Selection", "description": "Choose your favorite color", "oneOf": [\ { "const": "#FF0000", "title": "Red" },\ { "const": "#00FF00", "title": "Green" },\ { "const": "#0000FF", "title": "Blue" }\ ], "default": "#FF0000" } Multi-select enum (without titles): { "type": "array", "title": "Color Selection", "description": "Choose your favorite colors", "minItems": 1, "maxItems": 2, "items": { "type": "string", "enum": ["Red", "Green", "Blue"] }, "default": ["Red", "Green"] } Multi-select enum (with titles): { "type": "array", "title": "Color Selection", "description": "Choose your favorite colors", "minItems": 1, "maxItems": 2, "items": { "anyOf": [\ { "const": "#FF0000", "title": "Red" },\ { "const": "#00FF00", "title": "Green" },\ { "const": "#0000FF", "title": "Blue" }\ ] }, "default": ["#FF0000", "#00FF00"] } **Request schema structure:** "requestedSchema": { "type": "object", "properties": { "propertyName": { "type": "string", "title": "Display Name", "description": "Description of the property" }, "anotherProperty": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": ["propertyName"] } **Not supported** (to simplify client implementation): * Complex nested objects/arrays (beyond enum arrays) * Conditional validation * Custom formats beyond the supported list Clients use this schema to generate appropriate input forms, validate user input before sending, and provide better guidance to users. All primitive types support optional default values; clients SHOULD pre-populate form fields with these values. **Security note:** Following MCP, servers MUST NOT use form mode elicitation to request sensitive information (passwords, API keys, credentials). Sensitive data collection MUST use URL mode elicitation, which bypasses the agent and client entirely. ### [​](https://agentclientprotocol.com/rfds/elicitation#elicitation-request) Elicitation Request The agent sends an `elicitation/create` request when it needs information from the user: **Form mode example:** { "jsonrpc": "2.0", "id": 43, "method": "elicitation/create", "params": { "sessionId": "...", "toolCallId": "tc_123", "mode": "form", "message": "How would you like me to approach this refactoring?", "requestedSchema": { "type": "object", "properties": { "strategy": { "type": "string", "title": "Refactoring Strategy", "oneOf": [\ { "const": "conservative", "title": "Conservative" },\ { "const": "balanced", "title": "Balanced (Recommended)" },\ { "const": "aggressive", "title": "Aggressive" }\ ], "default": "balanced" } }, "required": ["strategy"] } } } **URL mode example:** { "jsonrpc": "2.0", "id": 44, "method": "elicitation/create", "params": { "requestId": 12, "mode": "url", "elicitationId": "github-oauth-001", "url": "https://agent.example.com/connect?elicitationId=github-oauth-001", "message": "Please authorize access to your GitHub repositories." } } The scope fields are flattened at the top level of the request. Elicitation supports two scoping variants: * **Session scope**: `sessionId` is set — tied to a specific session. Optionally includes `toolCallId` when tied to a specific tool call within that session (e.g., when an agent receives an elicitation from an MCP server during a tool call and needs to redirect it to the user). * **Request scope**: `requestId` is set — tied to a specific JSON-RPC request outside of a session (e.g., auth/configuration phases before any session is started). **Request-scoped example:** { "jsonrpc": "2.0", "id": 45, "method": "elicitation/create", "params": { "requestId": 12, "mode": "form", "message": "Please provide your workspace name to continue setup.", "requestedSchema": { "type": "object", "properties": { "workspaceName": { "type": "string", "title": "Workspace Name", "description": "The name of your workspace" } }, "required": ["workspaceName"] } } } The client presents the elicitation UI to the user. For form mode, the client generates appropriate input UI based on the JSON Schema. For URL mode, the client opens the URL in a secure browser context. ### [​](https://agentclientprotocol.com/rfds/elicitation#user-response) User Response Elicitation responses use a three-action model (following MCP) to clearly distinguish between different user actions: **Accept** - User explicitly approved and submitted with data: { "jsonrpc": "2.0", "id": 43, "result": { "action": "accept", "content": { "strategy": "balanced" } } } **Decline** - User explicitly declined the request: { "jsonrpc": "2.0", "id": 43, "result": { "action": "decline" } } **Cancel** - User dismissed without making an explicit choice (closed dialog, pressed Escape, etc.): { "jsonrpc": "2.0", "id": 43, "result": { "action": "cancel" } } For URL mode elicitation, the response with `action: "accept"` indicates that the user consented to the interaction. It does not mean the interaction is complete—the interaction occurs out-of-band and the client is not aware of the outcome until the agent sends a completion notification. Agents should handle each state appropriately: * **Accept**: Process the submitted data * **Decline**: Handle explicit decline (e.g., use default, offer alternatives) * **Cancel**: Handle dismissal (e.g., use default, prompt again later) ### [​](https://agentclientprotocol.com/rfds/elicitation#message-flow) Message Flow #### [​](https://agentclientprotocol.com/rfds/elicitation#form-mode-flow) Form Mode Flow #### [​](https://agentclientprotocol.com/rfds/elicitation#url-mode-flow) URL Mode Flow #### [​](https://agentclientprotocol.com/rfds/elicitation#url-mode-with-elicitation-required-error-flow) URL Mode With Elicitation Required Error Flow ### [​](https://agentclientprotocol.com/rfds/elicitation#completion-notifications-for-url-mode) Completion Notifications for URL Mode Following MCP, agents MAY send an `elicitation/complete` notification when an out-of-band interaction started by URL mode elicitation is completed: { "jsonrpc": "2.0", "method": "elicitation/complete", "params": { "elicitationId": "github-oauth-001" } } Agents sending notifications: * MUST only send the notification to the client that initiated the elicitation request * MUST include the `elicitationId` established in the original request Clients: * MUST ignore notifications referencing unknown or already-completed IDs * MAY use this notification to automatically retry requests, update UI, or continue an interaction * SHOULD provide manual controls for the user to retry or cancel if the notification never arrives ### [​](https://agentclientprotocol.com/rfds/elicitation#url-elicitation-required-error) URL Elicitation Required Error When a request cannot be processed until a URL mode elicitation is completed, the agent MAY return a `URLElicitationRequiredError` (code `-32042`). This allows clients to understand that a specific elicitation is required before retrying the original request. { "jsonrpc": "2.0", "id": 2, "error": { "code": -32042, "message": "This request requires authorization.", "data": { "elicitations": [\ {\ "mode": "url",\ "elicitationId": "github-oauth-001",\ "url": "https://agent.example.com/connect?elicitationId=github-oauth-001",\ "message": "Authorization is required to access your GitHub repositories."\ }\ ] } } } Any elicitations returned in the error MUST be URL mode elicitations with an `elicitationId`. Clients may automatically retry the failed request after receiving a completion notification. ### [​](https://agentclientprotocol.com/rfds/elicitation#error-handling) Error Handling Agents MUST return standard JSON-RPC errors for common failure cases: * When a request cannot be processed until a URL mode elicitation is completed: `-32042` (`URLElicitationRequiredError`) Clients MUST return standard JSON-RPC errors for common failure cases: * When the agent sends an `elicitation/create` request with a mode not declared in client capabilities: `-32602` (Invalid params) ### [​](https://agentclientprotocol.com/rfds/elicitation#client-capabilities) Client Capabilities Clients declare elicitation support during the `initialize` phase via `ClientCapabilities`, following MCP’s capability model pattern. The capability distinguishes between `form`\-based and `url`\-based elicitation: { "jsonrpc": "2.0", "method": "initialize", "params": { "protocolVersion": "2025-11-25", "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true }, "terminal": true, "elicitation": { "form": {}, "url": {} } }, "clientInfo": { "name": "my-client", "version": "1.0.0" } } } **Capability structure:** * `elicitation.form` - Present if the client can render form UI from restricted JSON Schema (strings, numbers, integers, booleans, enums) * `elicitation.url` - Present if the client can open URLs for out-of-band flows (OAuth, payments, credential collection) **Example: Headless client (no browser access):** "elicitation": { "form": {} } **Example: Simple terminal with URL support only:** "elicitation": { "url": {} } **Example: Full-featured client:** "elicitation": { "form": {}, "url": {} } This structure: 1. Allows clients to declare partial support based on their environment 2. Enables agents to pass capabilities along to MCP servers they connect to 3. Maps cleanly to MCP’s elicitation capability model 4. Provides clear semantics for graceful degradation Agents must gracefully handle clients that don’t include this field (assumed to have no elicitation support) or that only include one of `form` or `url`. ### [​](https://agentclientprotocol.com/rfds/elicitation#backward-compatibility) Backward Compatibility * If a client doesn’t declare `elicitation` capabilities, agents must provide a default value and continue * If a client only declares `elicitation.form`, agents must not send URL-mode elicitation requests (or provide defaults and continue) * If a client only declares `elicitation.url`, agents must not send form-mode elicitation requests (or provide defaults and continue) * Agents should not require elicitation responses to continue operating * Following MCP: an empty capability object (`"elicitation": {}`) is equivalent to declaring support for form mode only ### [​](https://agentclientprotocol.com/rfds/elicitation#statefulness) Statefulness Most practical uses of elicitation require that the agent maintain state about users: * Whether required information has been collected (e.g., the user’s display name via form mode elicitation) * Status of resource access (e.g., API keys or a payment flow via URL mode elicitation) Agents implementing elicitation MUST securely associate this state with individual users. Specifically: * State MUST NOT be associated with session IDs alone * State storage MUST be protected against unauthorized access * For remote agents, user identification MUST be derived from credentials acquired during authorization when possible (e.g., `sub` claim) Agents MUST NOT rely on client-provided user identification without agent-side verification, as this can be forged. [​](https://agentclientprotocol.com/rfds/elicitation#frequently-asked-questions) Frequently asked questions -------------------------------------------------------------------------------------------------------------- ### [​](https://agentclientprotocol.com/rfds/elicitation#can-an-agent-request-multiple-pieces-of-information-at-once) Can an agent request multiple pieces of information at once? Yes—a single form mode elicitation request can include multiple fields in its `requestedSchema`. The schema is an object with multiple properties, and the client renders a form with all requested fields. For sequential information gathering, agents can send multiple elicitation requests and wait for each response before proceeding. This allows agents to adapt follow-up questions based on previous answers. The request/response model gives agents flexibility: they control when to send elicitation requests and whether to wait for responses or continue with other work. ### [​](https://agentclientprotocol.com/rfds/elicitation#how-does-this-differ-from-session-config-options) How does this differ from session config options? Excellent question from PR #210 discussions. Both use restricted JSON Schema, but serve different purposes: | Aspect | Session Config Options | Elicitation | | --- | --- | --- | | **Lifecycle** | Persistent, pre-declared at session init | Transient, request/response | | **Scope** | Session-wide configuration | Single decision point or data collection | | **Defaults** | Required (agents must have defaults) | Optional (schema’s `required` array determines mandatory fields) | | **State management** | Client maintains full state, broadcast on changes | Agent receives response and decides how to proceed | | **Use cases** | Model selection, session mode, persistent settings | Authentication, clarifying questions, one-time data collection | Session Config Options are great for “how should you run this session?” Elicitation is for “what should I do next?” ### [​](https://agentclientprotocol.com/rfds/elicitation#why-align-with-mcp%E2%80%99s-elicitation-instead-of-creating-something-different) Why align with MCP’s elicitation instead of creating something different? As identified in PR #340, clients will already implement MCP elicitation support for MCP servers. Aligning ACP’s elicitation with MCP: * Reduces client implementation burden * Creates consistent UX across MCP and ACP agents * Lets code be shared or reused * Follows the protocol design principle of only constraining when necessary PR #340 specifically concluded: “I think we’d rather have an MCP elicitation story in general, and maybe offer the same interface outside of tool calls.” ### [​](https://agentclientprotocol.com/rfds/elicitation#how-does-authentication-flow-work-with-url-mode-elicitation) How does authentication flow work with URL-mode elicitation? From PR #330: URL-mode elicitation allows agents to request authentication without exposing credentials to the protocol. Following [MCP’s draft elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation) : 1. Agent sends elicitation request with `mode: "url"`, an `elicitationId`, and a URL to the agent’s own connect endpoint (not directly to the OAuth provider) 2. Client displays the URL to the user and requests consent to open it 3. Client responds with `action: "accept"` to indicate the user consented 4. User opens URL in their browser (out-of-band process) 5. Agent’s connect page verifies the user identity matches the elicitation request 6. Agent redirects user to the OAuth provider’s authorization endpoint 7. User authenticates and grants permission 8. OAuth provider redirects back to the agent’s redirect\_uri 9. Agent exchanges the authorization code for tokens and stores them bound to the user’s identity 10. Agent sends an `elicitation/complete` notification to inform the client **Key guarantees**: * Credentials never flow through the agent LLM or client * The agent is responsible for securely storing third-party tokens * The agent MUST verify user identity to prevent phishing attacks **Security requirements** (from MCP draft spec): Agents requesting URL mode elicitation: * MUST NOT include sensitive information about the end-user (credentials, PII, etc.) in the URL * MUST NOT provide a URL which is pre-authenticated to access a protected resource * SHOULD NOT include URLs intended to be clickable in any field of a form mode elicitation request * SHOULD use HTTPS URLs for non-development environments Clients implementing URL mode elicitation: * MUST NOT automatically pre-fetch the URL or any of its metadata * MUST NOT open the URL without explicit consent from the user * MUST show the full URL to the user for examination before consent * MUST open the URL in a secure manner that does not enable the client or LLM to inspect the content or user inputs (e.g., SFSafariViewController on iOS, not WKWebView) * SHOULD highlight the domain of the URL to mitigate subdomain spoofing * SHOULD have warnings for ambiguous/suspicious URIs (e.g., containing Punycode) * SHOULD NOT render URLs as clickable in any field of an elicitation request, except for the `url` field in a URL mode elicitation request (with the restrictions detailed above) **Phishing prevention**: The agent MUST verify that the user who started the elicitation request is the same user who completes the OAuth flow. This is typically done by checking session cookies against the user identity from the MCP authorization. ### [​](https://agentclientprotocol.com/rfds/elicitation#can-agents-use-elicitation-for-information-required-before-responding) Can agents use elicitation for information required before responding? Yes. By modeling elicitation as a request/response pattern (like MCP’s `elicitation/create`), the agent controls its own flow. The agent can: * Send an elicitation request and wait for the response before proceeding * Continue with other work while waiting for user input * Chain multiple elicitations as needed for multi-step workflows This flexibility is why elicitation is modeled as a separate request/response rather than being tightly coupled to turns. ### [​](https://agentclientprotocol.com/rfds/elicitation#what-if-a-user-doesn%E2%80%99t-respond-to-an-elicitation-request) What if a user doesn’t respond to an elicitation request? Elicitation requests require a response. If the user dismisses the elicitation without making an explicit choice (closes the dialog, presses Escape, etc.), the client responds with `action: "cancel"`. The agent then decides how to proceed—it may use a default value, prompt again later, or fail the turn. This ties into the broader request cancellation work: elicitation requests can be cancelled like any other request, and the `cancel` action provides a clear signal that the user chose not to engage rather than explicitly declining. ### [​](https://agentclientprotocol.com/rfds/elicitation#should-elicitation-support-complex-nested-data-structures) Should elicitation support complex nested data structures? We follow MCP’s design here. MCP intentionally restricts elicitation schemas to flat objects with primitive properties to simplify client implementation and user experience. Complex nested structures, arrays of objects (beyond enum arrays), and advanced JSON Schema features are explicitly not supported. If MCP expands this in the future, ACP would follow suit. ### [​](https://agentclientprotocol.com/rfds/elicitation#how-should-agents-handle-clients-that-don%E2%80%99t-support-elicitation) How should agents handle clients that don’t support elicitation? Agents should always design to gracefully degrade: * Check `elicitation.form` and `elicitation.url` capabilities before sending requests * If the required mode is not supported, provide sensible default values * Describe what they’re requesting in turn content (text) as fallback * Proceed with the defaults * For agents connecting to MCP servers: pass the client’s elicitation capabilities to the MCP server so it can also make informed decisions ### [​](https://agentclientprotocol.com/rfds/elicitation#can-we-extend-this-to-replace-the-existing-permission-request-mechanism) Can we extend this to replace the existing Permission-Request mechanism? We recommend keeping them separate. Permission requests are fundamentally security decisions—allowing a tool call to proceed is distinct from the model asking for clarification or collecting user preferences. Keeping these separate allows clients to: * Offer a consistent, recognizable UX for security-sensitive decisions (permissions) * Clearly distinguish “the agent needs approval to do something” from “the agent needs information to continue” * Apply different policies (e.g., “always allow file reads” vs. per-request elicitation responses) This is the same reasoning behind keeping authentication flows (URL mode) distinct from data collection (form mode). While we may reuse some types between these mechanisms, conflating the features would blur important security boundaries. ### [​](https://agentclientprotocol.com/rfds/elicitation#what-about-validating-user-input-on-the-client-side) What about validating user input on the client side? Clients SHOULD validate user input against the provided JSON Schema **before** sending the response to the agent. This prevents invalid data from reaching the agent and provides immediate feedback to the user. Agents SHOULD also validate received data matches the requested schema, as defense-in-depth against malformed or malicious responses. If the agent requires additional validation beyond what’s expressible in JSON Schema: 1. Agent validates the received value in the next turn 2. If validation fails, agent can fail the turn with an error 3. Client can then re-prompt the user (or fall back to the original default) For v1, we recommend starting with JSON Schema validation only. If more complex validation patterns emerge from real-world usage, a future RFD can specify additional validation mechanisms. [​](https://agentclientprotocol.com/rfds/elicitation#revision-history) Revision history ------------------------------------------------------------------------------------------ * 2026-02-06: Spec alignment review. Fixed OAuth URL examples to use agent connect endpoints (not direct OAuth provider URLs) per MCP phishing prevention guidance. Added normative requirements section (MUST support at least one mode, MUST NOT send unsupported modes, url MUST be valid). Added Error Handling section with `-32042` and `-32602` error codes. Added message flow diagrams (form mode, URL mode, URL mode with error). Expanded safe URL handling requirements (pre-fetch prohibition, Punycode warnings, non-clickable URLs in form fields). Added server-side schema validation SHOULD requirement. Added Statefulness subsection with normative requirements for state association and user identification. * 2026-02-05: Major revision to align with MCP draft elicitation specification. Updated enum schema to use `oneOf`/`anyOf` with `const`/`title` instead of `enumNames`. Added multi-select array support. Added `pattern` field for strings. Added URLElicitationRequiredError (-32042) section. Added completion notifications section. Expanded security considerations including phishing prevention. Updated all examples to match MCP draft spec format. * 2026-02-05: Initial MCP alignment. Removed explicit “input types” in favor of restricted JSON Schema (client decides rendering). Added `mode` field (`form`/`url`). Updated capability model to use `form`/`url` sub-objects per MCP SEP-1036. Added three-action response model (`accept`/`decline`/`cancel`). Removed `password` type (MCP prohibits sensitive data in form mode). * 2026-01-12: Initial draft based on community discussions in PR #340 (user selection), PR #210 (session config alignment), and PR #330 (authentication use cases). Aligned with MCP elicitation patterns. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/boolean-config-option) [Next Edit Suggestions\ \ Next](https://agentclientprotocol.com/rfds/next-edit-suggestions) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/elicitation#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/elicitation#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/elicitation#what-we-propose-to-do-about-it) * [Shiny future](https://agentclientprotocol.com/rfds/elicitation#shiny-future) * [Implementation details and plan](https://agentclientprotocol.com/rfds/elicitation#implementation-details-and-plan) * [Alignment with MCP](https://agentclientprotocol.com/rfds/elicitation#alignment-with-mcp) * [Elicitation Request Structure](https://agentclientprotocol.com/rfds/elicitation#elicitation-request-structure) * [Elicitation Modes](https://agentclientprotocol.com/rfds/elicitation#elicitation-modes) * [Restricted JSON Schema](https://agentclientprotocol.com/rfds/elicitation#restricted-json-schema) * [Elicitation Request](https://agentclientprotocol.com/rfds/elicitation#elicitation-request) * [User Response](https://agentclientprotocol.com/rfds/elicitation#user-response) * [Message Flow](https://agentclientprotocol.com/rfds/elicitation#message-flow) * [Form Mode Flow](https://agentclientprotocol.com/rfds/elicitation#form-mode-flow) * [URL Mode Flow](https://agentclientprotocol.com/rfds/elicitation#url-mode-flow) * [URL Mode With Elicitation Required Error Flow](https://agentclientprotocol.com/rfds/elicitation#url-mode-with-elicitation-required-error-flow) * [Completion Notifications for URL Mode](https://agentclientprotocol.com/rfds/elicitation#completion-notifications-for-url-mode) * [URL Elicitation Required Error](https://agentclientprotocol.com/rfds/elicitation#url-elicitation-required-error) * [Error Handling](https://agentclientprotocol.com/rfds/elicitation#error-handling) * [Client Capabilities](https://agentclientprotocol.com/rfds/elicitation#client-capabilities) * [Backward Compatibility](https://agentclientprotocol.com/rfds/elicitation#backward-compatibility) * [Statefulness](https://agentclientprotocol.com/rfds/elicitation#statefulness) * [Frequently asked questions](https://agentclientprotocol.com/rfds/elicitation#frequently-asked-questions) * [Can an agent request multiple pieces of information at once?](https://agentclientprotocol.com/rfds/elicitation#can-an-agent-request-multiple-pieces-of-information-at-once) * [How does this differ from session config options?](https://agentclientprotocol.com/rfds/elicitation#how-does-this-differ-from-session-config-options) * [Why align with MCP’s elicitation instead of creating something different?](https://agentclientprotocol.com/rfds/elicitation#why-align-with-mcp%E2%80%99s-elicitation-instead-of-creating-something-different) * [How does authentication flow work with URL-mode elicitation?](https://agentclientprotocol.com/rfds/elicitation#how-does-authentication-flow-work-with-url-mode-elicitation) * [Can agents use elicitation for information required before responding?](https://agentclientprotocol.com/rfds/elicitation#can-agents-use-elicitation-for-information-required-before-responding) * [What if a user doesn’t respond to an elicitation request?](https://agentclientprotocol.com/rfds/elicitation#what-if-a-user-doesn%E2%80%99t-respond-to-an-elicitation-request) * [Should elicitation support complex nested data structures?](https://agentclientprotocol.com/rfds/elicitation#should-elicitation-support-complex-nested-data-structures) * [How should agents handle clients that don’t support elicitation?](https://agentclientprotocol.com/rfds/elicitation#how-should-agents-handle-clients-that-don%E2%80%99t-support-elicitation) * [Can we extend this to replace the existing Permission-Request mechanism?](https://agentclientprotocol.com/rfds/elicitation#can-we-extend-this-to-replace-the-existing-permission-request-mechanism) * [What about validating user input on the client side?](https://agentclientprotocol.com/rfds/elicitation#what-about-validating-user-input-on-the-client-side) * [Revision history](https://agentclientprotocol.com/rfds/elicitation#revision-history) --- # Next Edit Suggestions - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/next-edit-suggestions#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Next Edit Suggestions [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [@anna239](https://github.com/anna239) [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#elevator-pitch) Elevator pitch ------------------------------------------------------------------------------------------------ > What are you proposing to change? Add a **Next Edit Suggestion (NES)** capability to ACP, allowing agents to provide predictive code edits. The protocol is designed around **capability negotiation**: agents declare what events and context they can consume, and clients provide only what was requested. [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#status-quo) Status quo ---------------------------------------------------------------------------------------- > How do things work today and what problems does this cause? Why would we change things? ACP currently has no mechanism for agents to provide inline edit predictions. Each client–agent pair implements NES through proprietary protocols. [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#what-we-propose-to-do-about-it) What we propose to do about it -------------------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? Introduce a `nes` capability that agents advertise during initialization. The capability declares: * **Events** the agent wants to receive (file lifecycle notifications). * **Context** the agent wants attached to each suggestion request. The client inspects these declarations and provides only what was requested, minimizing overhead for simple agents while allowing rich context for advanced ones. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#capability-advertisement) Capability advertisement During `initialize`, the agent includes a `nes` field in `agentCapabilities`: { "agentCapabilities": { "nes": { "events": { "document": { "didOpen": {}, "didChange": { "syncKind": "incremental" }, "didClose": {}, "didSave": {}, "didFocus": {} } }, "context": { "recentFiles": { "maxCount": 10 }, "relatedSnippets": {}, "editHistory": { "maxCount": 6 }, "userActions": { "maxCount": 16 }, "openFiles": {}, "diagnostics": {} } } } } All fields under `events` and `context` are optional — an agent advertises only what it can use. #### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#client-capabilities) Client capabilities The **client** advertises its own NES-related capabilities in the `initialize` request. The client declares which suggestion kinds it supports beyond the basic `edit` kind. Agents should only suggest kinds that the client has advertised. { "clientCapabilities": { "nes": { "jump": {}, "rename": {}, "searchAndReplace": {} } } } Each entry corresponds to a suggestion kind (see [Suggestion kinds](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-kinds) below). If a kind is absent, the agent must not produce suggestions of that kind. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#session-lifecycle) Session lifecycle If the `nes` capability is present, the client may call `nes/start` to begin an NES session. An NES session is **separate from and independent of** the ACP chat session — it has its own session ID, its own lifecycle, and its own stream of events and requests. A single ACP connection may have any number of active NES sessions alongside any number of chat sessions. The NES session is started via `nes/start` and closed via `nes/close`; it does not inherit state from, or share context with, chat sessions. The agent can also use the existing `configOptions` mechanism to expose NES-related settings (model selection, debounce preferences, enabled/disabled state, etc.). [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#implementation-details-and-plan) Implementation details and plan ---------------------------------------------------------------------------------------------------------------------------------- > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#position-encoding) Position encoding All `Position` objects in NES use zero-based line and zero-based character offsets, following the same conventions as [LSP 3.17](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#position) . The meaning of the `character` offset depends on the negotiated **position encoding**. Three encoding kinds are supported: * `"utf-16"` — character offsets count UTF-16 code units. This is the **default** and must be supported by all clients and agents. * `"utf-32"` — character offsets count Unicode code points. * `"utf-8"` — character offsets count UTF-8 code units (bytes). **Negotiation:** The client may declare the position encodings it supports in the `initialize` request via `clientCapabilities.positionEncodings`, listed in order of preference. The agent selects one from the client’s list and declares it in its `initialize` response as `agentCapabilities.positionEncoding`. If the client omits `positionEncodings`, or the agent omits `positionEncoding` in its response, both sides default to `"utf-16"`. Client `initialize` request (excerpt): { "clientCapabilities": { "positionEncodings": ["utf-32", "utf-16"] } } Agent `initialize` response (excerpt): { "agentCapabilities": { "nes": { ... }, "positionEncoding": "utf-32" } } The negotiated encoding applies to all `Position` and `Range` values exchanged within NES — events, suggestion requests, and suggestion responses. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#events) Events Events are fire-and-forget notifications from client to agent. Every event is scoped to the NES session identified by the `sessionId` returned from `nes/start`. The client sends them only if the corresponding key is present in the agent’s advertised `events` capability (e.g. `nes.events.document` for NES). #### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#document/didopen) `document/didOpen` Sent when a file is opened in the editor. { "jsonrpc": "2.0", "method": "document/didOpen", "params": { "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "languageId": "rust", "version": 1, "text": "fn main() {\n println!(\"hello\");\n}\n" } } #### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#document/didchange) `document/didChange` Sent when a file is edited. Supports two sync modes declared by the agent: * `"full"` — client sends entire file content each time. * `"incremental"` — client sends only the changed ranges. **Incremental:** { "jsonrpc": "2.0", "method": "document/didChange", "params": { "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "contentChanges": [\ {\ "range": {\ "start": { "line": 1, "character": 4 },\ "end": { "line": 1, "character": 4 }\ },\ "text": "let x = 42;\n "\ }\ ] } } **Full:** { "jsonrpc": "2.0", "method": "document/didChange", "params": { "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "contentChanges": [\ {\ "text": "fn main() {\n let x = 42;\n println!(\"hello\");\n}\n"\ }\ ] } } #### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#document/didclose) `document/didClose` Sent when a file is closed. { "jsonrpc": "2.0", "method": "document/didClose", "params": { "sessionId": "session_abc123", "uri": "file:///path/to/file.rs" } } #### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#document/didsave) `document/didSave` Sent when a file is saved. { "jsonrpc": "2.0", "method": "document/didSave", "params": { "sessionId": "session_abc123", "uri": "file:///path/to/file.rs" } } #### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#document/didfocus) `document/didFocus` Sent when a file becomes the active editor tab. Unlike `document/didOpen` (which fires once when a file is first opened), `document/didFocus` fires every time the user switches to a file, including files that are already open. This is the primary trigger for agents that need to refresh context on tab switch (e.g. re-indexing relevant code snippets). { "jsonrpc": "2.0", "method": "document/didFocus", "params": { "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "position": { "line": 5, "character": 12 }, "visibleRange": { "start": { "line": 0, "character": 0 }, "end": { "line": 45, "character": 0 } } } } The `position` is the current cursor position. The `visibleRange` is the portion of the file currently visible in the editor viewport. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-request) Suggestion request The client requests a suggestion by calling `nes/suggest`. Context fields are included only if the agent declared interest in the corresponding `nes.context` key. { "jsonrpc": "2.0", "id": 42, "method": "nes/suggest", "params": { "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "position": { "line": 5, "character": 12 }, "selection": { "start": { "line": 5, "character": 4 }, "end": { "line": 5, "character": 12 } }, "triggerKind": "automatic", "context": { "recentFiles": [\ {\ "uri": "file:///path/to/utils.rs",\ "languageId": "rust",\ "text": "pub fn helper() -> i32 { 42 }\n"\ }\ ], "relatedSnippets": [\ {\ "uri": "file:///path/to/types.rs",\ "excerpts": [\ {\ "startLine": 10,\ "endLine": 25,\ "text": "pub struct Config {\n pub name: String,\n ...\n}"\ }\ ]\ }\ ], "editHistory": [\ {\ "uri": "file:///path/to/file.rs",\ "diff": "--- a/file.rs\n+++ b/file.rs\n@@ -3,0 +3,1 @@\n+ let x = 42;"\ }\ ], "userActions": [\ {\ "action": "insertChar",\ "uri": "file:///path/to/file.rs",\ "position": { "line": 5, "character": 12 },\ "timestampMs": 1719400000000\ },\ {\ "action": "cursorMovement",\ "uri": "file:///path/to/file.rs",\ "position": { "line": 10, "character": 0 },\ "timestampMs": 1719400001200\ }\ ], "openFiles": [\ {\ "uri": "file:///path/to/utils.rs",\ "languageId": "rust",\ "visibleRange": {\ "start": { "line": 0, "character": 0 },\ "end": { "line": 30, "character": 0 }\ },\ "lastFocusedMs": 1719399998000\ },\ {\ "uri": "file:///path/to/types.rs",\ "languageId": "rust",\ "visibleRange": null,\ "lastFocusedMs": 1719399990000\ }\ ], "diagnostics": [\ {\ "uri": "file:///path/to/file.rs",\ "range": {\ "start": { "line": 5, "character": 0 },\ "end": { "line": 5, "character": 10 }\ },\ "severity": "error",\ "message": "cannot find value `foo` in this scope"\ }\ ] } } } `selection` is the current text selection range, if any. When the selection is empty (cursor is a point), this field may be omitted or have `start` equal to `end`. Agents can use selection state to predict replacements or transformations of the selected text. `triggerKind` is one of: * `"automatic"` — triggered by user typing or cursor movement * `"diagnostic"` — triggered by a diagnostic (error/warning) appearing at or near the cursor position. The client includes the relevant diagnostics in the `diagnostics` context field so the agent can target a fix. * `"manual"` — triggered by explicit user action (keyboard shortcut) ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-response) Suggestion response A suggestion is one of several kinds, each identified by the `kind` field. The `edit` kind is always supported; other kinds (`jump`, `rename`, `searchAndReplace`) require the client to advertise support in its capabilities. **Edit suggestion:** { "jsonrpc": "2.0", "id": 42, "result": { "suggestions": [\ {\ "id": "sugg_001",\ "kind": "edit",\ "uri": "file:///path/to/other_file.rs",\ "edits": [\ {\ "range": {\ "start": { "line": 5, "character": 0 },\ "end": { "line": 5, "character": 10 }\ },\ "newText": "let result = helper();"\ }\ ],\ "cursorPosition": { "line": 5, "character": 22 }\ }\ ] } } **Jump suggestion:** { "jsonrpc": "2.0", "id": 42, "result": { "suggestions": [\ {\ "id": "sugg_002",\ "kind": "jump",\ "uri": "file:///path/to/other_file.rs",\ "position": { "line": 15, "character": 4 }\ }\ ] } } **Rename suggestion:** { "jsonrpc": "2.0", "id": 42, "result": { "suggestions": [\ {\ "id": "sugg_003",\ "kind": "rename",\ "uri": "file:///path/to/file.rs",\ "position": { "line": 5, "character": 10 },\ "newName": "calculateTotal"\ }\ ] } } **Search-and-replace suggestion:** { "jsonrpc": "2.0", "id": 42, "result": { "suggestions": [\ {\ "id": "sugg_004",\ "kind": "searchAndReplace",\ "uri": "file:///path/to/file.rs",\ "search": "oldFunction",\ "replace": "newFunction",\ "isRegex": false\ }\ ] } } A response may contain a mix of suggestion kinds. The client decides how to present them (e.g. inline ghost text for edits, a navigation hint for jumps). Agents must only include suggestion kinds that the client has advertised in its capabilities (except `edit`, which is always supported). Each suggestion contains: * `id` — unique identifier for accept/reject tracking. * `kind` — the suggestion kind (see [Suggestion kinds](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-kinds) below). Edit suggestions additionally contain: * `uri` — the file to edit. * `edits` — one or more text edits to apply. * `cursorPosition` — optional suggested cursor position after applying edits. Jump suggestions additionally contain: * `uri` — the file to navigate to. * `position` — the target position within that file. Rename suggestions additionally contain: * `uri` — the file URI containing the symbol. * `position` — the position of the symbol to rename. * `newName` — the new name for the symbol. Search-and-replace suggestions additionally contain: * `uri` — the file URI to search within. Can be a folder, then operation is performed in all the files in this folder. * `search` — the text or pattern to find. * `replace` — the replacement text. * `isRegex` (`boolean`, optional) — whether `search` is a regular expression. Defaults to `false`. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#accept-/-reject) Accept / Reject { "jsonrpc": "2.0", "method": "nes/accept", "params": { "sessionId": "session_abc123", "id": "sugg_001" } } { "jsonrpc": "2.0", "method": "nes/reject", "params": { "sessionId": "session_abc123", "id": "sugg_001", "reason": "rejected" } } `reason` is one of: * `"rejected"` — the user explicitly dismissed the suggestion (e.g. pressed Escape or typed something incompatible). * `"ignored"` — the suggestion was shown but the user continued editing without interacting with it, and the context changed enough to invalidate it. * `"replaced"` — the suggestion was superseded by a newer suggestion before the user could act on it. * `"cancelled"` — the request was cancelled before the agent returned a response (e.g. the user typed quickly and the previous request became stale). The `reason` field is optional. Providing granular reasons allows agents to improve their models — for example, a `"replaced"` suggestion carries different training signal than an explicit `"rejected"`. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#nes-session-start) NES session start The client provides workspace metadata when starting a session. This information is static for the lifetime of the session. { "jsonrpc": "2.0", "id": 1, "method": "nes/start", "params": { "workspaceUri": "file:///Users/alice/projects/my-app", "workspaceFolders": [\ {\ "uri": "file:///Users/alice/projects/my-app",\ "name": "my-app"\ }\ ], "repository": { "name": "my-app", "owner": "alice", "remoteUrl": "https://github.com/alice/my-app.git" } } } All fields in `params` are optional. The `repository` field is omitted if the workspace is not a git repository or the info is unavailable. Response: { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "session_abc123" } } The returned `sessionId` scopes all subsequent NES events, requests, and notifications for that session. #### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#error-handling) Error handling The agent may reject `nes/start` with an error. In particular, agents that require authentication may return an `auth_required` error: { "jsonrpc": "2.0", "id": 1, "error": { "code": -32000, "message": "Authentication required", "data": { "reason": "auth_required" } } } Clients **must** be prepared to handle `auth_required` errors on `nes/start`. The recommended behavior is to prompt the user to authenticate (e.g. sign in or provide credentials) and retry the `nes/start` call after authentication succeeds. Clients should not silently ignore this error or assume NES is unavailable — the agent may be fully functional once the user authenticates. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#nes-session-close) NES session close The client closes an NES session by calling `nes/close`. The agent **must** cancel any ongoing work related to the NES session and free up any resources associated with it. { "jsonrpc": "2.0", "id": 2, "method": "nes/close", "params": { "sessionId": "session_abc123" } } Response: { "jsonrpc": "2.0", "id": 2, "result": {} } ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-kinds) Suggestion kinds The `kind` field in each suggestion identifies its type. The following kinds are defined: * **`edit`** — A text edit suggestion. Always supported; does not require a client capability. * **`jump`** — Navigate to a different file/position. Requires `jump` in client capabilities. * **`rename`** — Rename a symbol across the workspace. Requires `rename` in client capabilities. * **`searchAndReplace`** — Search and replace text within a file/folder. Requires `searchAndReplace` in client capabilities. Additional suggestion kinds may be added to the protocol in the future. Agents must only produce suggestions whose `kind` the client has advertised (except `edit`, which is always supported). ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#config-options) Config options The agent can use the existing `configOptions` mechanism from ACP to expose NES-related settings. For example, an agent might return config options like: { "configOptions": [\ {\ "id": "nes_model",\ "name": "Prediction Model",\ "category": "model",\ "type": "enum",\ "currentValue": "fast",\ "options": [\ { "value": "fast", "label": "Fast" },\ { "value": "accurate", "label": "Accurate" }\ ]\ }\ ] } [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#frequently-asked-questions) Frequently asked questions ------------------------------------------------------------------------------------------------------------------------ > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#why-separate-events-from-context) Why separate events from context? Events and context serve different purposes and have different delivery models: * **Events** are pushed as they happen — they allow the agent to maintain internal state (like an LSP server tracking open documents). This is the model Copilot uses. * **Context** is attached to each request — it allows stateless agents to receive everything they need in one call. This is the model Zed Predict and Supermaven use. A note about Cursor: Cursor has a separate context-collection phase (`RefreshTabContext`) that involves vector DB lookup and is triggered on file open, tab switch, and significant edits. The event-based approach supports this flow: an NES agent can listen for `document/didOpen`, `document/didFocus`, and accumulated `document/didChange` events to self-trigger its own context refresh. The `document/didFocus` event (with cursor position and visible range) and workspace metadata from `nes/start` provide all the inputs Cursor’s `RefreshTabContext` needs. An agent may want both (events for incremental file tracking + context for edit history), or just one. The capability split lets each agent pick the model that fits its architecture. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#why-not-reuse-lsp%E2%80%99s-textdocument/didopen-etc-directly) Why not reuse LSP’s `textDocument/didOpen` etc. directly? LSP’s document sync notifications carry the same information, but: 1. ACP is not LSP — reusing method names could cause confusion in implementations that bridge both. 2. We may want to evolve the event payloads independently (e.g. adding metadata fields). 3. Using `document/` as a generic namespace keeps these methods reusable across different ACP capabilities (NES, and potentially others in the future) without tying them to a single feature. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#how-does-this-relate-to-pr-#325) How does this relate to PR #325? This RFD covers the session lifecycle and also suggests a protocol that would cover a variety of different nes providers ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#why-provide-workspace-info-in-nes/start) Why provide workspace info in `nes/start`? Agents that perform server-side indexing (embedding-based retrieval, semantic search) need to know which repository they’re working with. This metadata — workspace root, repo name/owner, remote URL — is static for the session lifetime, so it belongs in the session start rather than being repeated on every request or requiring a separate query. ### [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#what-alternative-approaches-did-you-consider) What alternative approaches did you consider? 1. **Context-only** — Pass all file content, edit history, and metadata as context fields on each `nes/suggest` request, with no event notifications. This is simpler for stateless agents but forces the client to assemble and transmit potentially large payloads on every request, even when nothing changed. It also prevents agents from maintaining their own incremental state (e.g. an internal file mirror or semantic index). 2. **Events-only** — Rely entirely on event notifications (`didOpen`, `didChange`, etc.) and have the agent maintain all state internally, with `nes/suggest` sending only the cursor position. This is efficient on the wire but requires every agent to implement stateful document tracking, which is a high barrier for simple agents that just want the code around the cursor. 3. **Events + context (chosen)** — Allow agents to declare both. An agent that wants to track files incrementally can request events; an agent that prefers stateless request-response can request context fields; a sophisticated agent can use both (events for file sync, context for edit history and definition excerpts). This gives each agent the flexibility to pick the model that fits its architecture without imposing unnecessary complexity. [​](https://agentclientprotocol.com/rfds/next-edit-suggestions#revision-history) Revision history ---------------------------------------------------------------------------------------------------- * 2026-02-22: Initial draft Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/elicitation) [Additional Workspace Roots for Session Lifecycle Requests\ \ Next](https://agentclientprotocol.com/rfds/additional-directories) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/next-edit-suggestions#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/next-edit-suggestions#status-quo) * [What we propose to do about it](https://agentclientprotocol.com/rfds/next-edit-suggestions#what-we-propose-to-do-about-it) * [Capability advertisement](https://agentclientprotocol.com/rfds/next-edit-suggestions#capability-advertisement) * [Client capabilities](https://agentclientprotocol.com/rfds/next-edit-suggestions#client-capabilities) * [Session lifecycle](https://agentclientprotocol.com/rfds/next-edit-suggestions#session-lifecycle) * [Implementation details and plan](https://agentclientprotocol.com/rfds/next-edit-suggestions#implementation-details-and-plan) * [Position encoding](https://agentclientprotocol.com/rfds/next-edit-suggestions#position-encoding) * [Events](https://agentclientprotocol.com/rfds/next-edit-suggestions#events) * [document/didOpen](https://agentclientprotocol.com/rfds/next-edit-suggestions#document%2Fdidopen) * [document/didChange](https://agentclientprotocol.com/rfds/next-edit-suggestions#document%2Fdidchange) * [document/didClose](https://agentclientprotocol.com/rfds/next-edit-suggestions#document%2Fdidclose) * [document/didSave](https://agentclientprotocol.com/rfds/next-edit-suggestions#document%2Fdidsave) * [document/didFocus](https://agentclientprotocol.com/rfds/next-edit-suggestions#document%2Fdidfocus) * [Suggestion request](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-request) * [Suggestion response](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-response) * [Accept / Reject](https://agentclientprotocol.com/rfds/next-edit-suggestions#accept-%2F-reject) * [NES session start](https://agentclientprotocol.com/rfds/next-edit-suggestions#nes-session-start) * [Error handling](https://agentclientprotocol.com/rfds/next-edit-suggestions#error-handling) * [NES session close](https://agentclientprotocol.com/rfds/next-edit-suggestions#nes-session-close) * [Suggestion kinds](https://agentclientprotocol.com/rfds/next-edit-suggestions#suggestion-kinds) * [Config options](https://agentclientprotocol.com/rfds/next-edit-suggestions#config-options) * [Frequently asked questions](https://agentclientprotocol.com/rfds/next-edit-suggestions#frequently-asked-questions) * [Why separate events from context?](https://agentclientprotocol.com/rfds/next-edit-suggestions#why-separate-events-from-context) * [Why not reuse LSP’s textDocument/didOpen etc. directly?](https://agentclientprotocol.com/rfds/next-edit-suggestions#why-not-reuse-lsp%E2%80%99s-textdocument%2Fdidopen-etc-directly) * [How does this relate to PR #325?](https://agentclientprotocol.com/rfds/next-edit-suggestions#how-does-this-relate-to-pr-%23325) * [Why provide workspace info in nes/start?](https://agentclientprotocol.com/rfds/next-edit-suggestions#why-provide-workspace-info-in-nes%2Fstart) * [What alternative approaches did you consider?](https://agentclientprotocol.com/rfds/next-edit-suggestions#what-alternative-approaches-did-you-consider) * [Revision history](https://agentclientprotocol.com/rfds/next-edit-suggestions#revision-history) --- # Rust SDK based on SACP - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/rfds/rust-sdk-v1#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Draft Rust SDK based on SACP [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) Author(s): [nikomatsakis](https://github.com/nikomatsakis) [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#elevator-pitch) Elevator pitch -------------------------------------------------------------------------------------- > What are you proposing to change? Replace the current ACP Rust SDK with a new implementation based on SACP (Symposium ACP). The new SDK provides a component-based architecture with builder patterns, explicit message ordering guarantees, and first-class support for [Proxy Chains](https://agentclientprotocol.com/rfds/proxy-chains) and [MCP-over-ACP](https://agentclientprotocol.com/rfds/mcp-over-acp) . [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#status-quo) Status quo ------------------------------------------------------------------------------ > How do things work today and what problems does this cause? Why would we change things? The current `agent-client-protocol` crate has a straightforward design with trait-based callbacks for common ACP methods and well-typed requests and responses. It’s convenient for simple purposes but quickly becomes awkward when attempting more complex designs. Two examples that we found pushed the limits of the design are the _conductor_ (from the [proxy chains](https://agentclientprotocol.com/rfds/proxy-chains) RFD) and the [patchwork-rs](https://patchwork-lang.github.io/patchwork-rs/) project: The Conductor is an orchestrator that routes messages between proxies, agents, and MCP servers. It must adapt messages as they flow through the system and maintain the correct ordering. Patchwork is a programmatic interface for working with agents. It allows Rust programs to run prompts that provide custom tools (implemented using [MCP-over-ACP](https://agentclientprotocol.com/rfds/mcp-over-acp) ) and messages: let mut results = Vec::new(); let _: () = patchwork.think() .text("Process each item and record it using the `record` tool") .tool( "record", "Record a processed item", async |input: RecordInput, _cx| { results.push(input.item); Ok(RecordOutput { success: true }) }, acp::tool_fn_mut!(), ) .await?; // After the think block, `results` contains all recorded items println!("Recorded: {:?}", results); ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-handlers-can%E2%80%99t-send-messages) Limitation: Handlers can’t send messages The current SDK uses traits like `Agent` where handler methods receive only the request and return only the response: #[async_trait] pub trait Agent { async fn prompt(&self, args: PromptRequest) -> Result; // ... } There’s no (easy) way to send messages back to the client from within a handler. If you want to send a `SessionNotification` while processing a prompt, you need to obtain an `AgentSideConnection` through some other means and coordinate access yourself. This is awkward for agents (which want to stream progress during prompt processing) and prohibitive for proxies (which need to forward messages to their successor while handling a request from their predecessor). **Goal:** Handlers should receive a context parameter that provides methods to send requests and notifications back through the connection. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-fixed-set-of-handlers) Limitation: Fixed set of handlers ACP is an extensible protocol where users can add their own method names beginning with `_`. The current SDK uses a trait which means that it cannot offer “first-class” support for user-defined requests/notifications. Instead, these are handled using extension methods (`ext_method`, `ext_notification`). These methods have no static typing and require the user to work with raw JSON. **Goal:** Allow SDK users to define their own request/notification types that are handled in the same fashion as built-in types. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-message-handlers-must-be-the-same-across-all-session) Limitation: Message handlers must be the same across all session The current API always executes the same handler code for a particular method (e.g., a session/update). If different handling is required for a particular session, that handler must maintain some kind of map from session-id to identify what handling is required, which is non-trivial bookkeeping that can become awkward. As an example of how complex this can get, consider the [elaborate message forwarding scheme](https://nikomatsakis.github.io/threadbare/agent.html#full-trace-nested-think) used by older versions of patchwork. **Goal:** Allow SDK users to add/remove “dynamic” handlers that are specific to a particular session or other part of the protocol. These handlers should be closures so they can capture state. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-no-ordering-guarantees) Limitation: No ordering guarantees In the current SDK, every incoming request or notification results is handled in a freshly spawned task. This means that it is not possible to guarantee that requests or notifications are handled in the order they arrive. It is also not possible to be sure that a notification is fully handled before the response to another request; this makes it difficult to, for example, be sure that a `session/update` notification is handled before the turn is ended (which is sent as the response to the `prompt` request). This is essential for an application like patchwork, which wishes to fully capture the updates before returning. **Goal:** Handlers should block message processing to allow them to ensure that they fully process a message before other messages are processed. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-confusing-naming-and-11-assumption) Limitation: Confusing naming and 1:1 assumption `AgentSideConnection` is ambiguous - does this represent the agent, or the connection _to_ an agent? What’s more, the SDK currently assumes that each connection has a single peer, but [proxies](https://agentclientprotocol.com/rfds/proxy-chains) may wish to send/receive messages from multiple peers (client or agent). This was a constant source of confusion in early versions of the conductor and frequently required the author to get out a pencil and paper and work things out very carefully. **Goal:** Use directional naming like `ClientToAgent` that makes relationships explicit: “I am the client, the remote peer is an agent.” Enable multiple peers. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-awkward-to-connect-components) Limitation: Awkward to connect components When building tests and other applications, it’s convenient to be able to create a client and connect it directly to an agent, leaving the plumbing to the framework. The current SDK only accepts channels and byte-streams which creates unnecessary boilerplate. **Goal:** Provide a `Component` trait that abstracts over anything that can connect to an ACP transport, enabling uniform handling in orchestration scenarios. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#challenge-executor-independence-and-starvation-freedom) Challenge: Executor independence and starvation freedom This isn’t a limitation of the current SDK per se, but a common pitfall in async Rust designs that we want to address. We want the SDK to be independent from specific executors (not tied to tokio) while still supporting richer patterns like spawning background tasks. One specific common issue with Rust async APIs is _starvation_, which can occur with stream-like APIs where it is important to keep awaiting the stream so that items make progress. For example, in a setup like this one, the “connection” is not being “awaited” while each message is handled: // PROBLEMATIC: message handling starves while processing while let Some(message) = connection.next().await { process(message).await; // connection is quiescent during this await! } With careful design, it is possible to avoid these hazards. The most common way is either to spawn tasks (which then ties one to a specific executor) or to use “interior iteration” style APIs like `for_each` or `run_until`: // CORRECT: message handling continues concurrently connection.run_until(async |cx| { // The connection processes messages while this code runs let response = cx.send_request(request).block_task().await?; process(response).await }).await **Goal:** Provide APIs that are starvation-free by design, making it difficult to accidentally block message processing. [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-we-propose-to-do-about-it) What we propose to do about it ---------------------------------------------------------------------------------------------------------------------- > What are you proposing to improve the situation? We propose to adopt the design and implementation from [`sacp`](https://github.com/symposium-dev/symposium-acp/) (developed as part of the [Symposium project](https://symposium.dev/) ) as the foundation for `agent-client-protocol` v1.0. The `sacp` crates will be imported into this repository and renamed: | Current | New name | | --- | --- | | `sacp` | `agent-client-protocol` (v1.0) | | `sacp-derive` | `agent-client-protocol-derive` | | `sacp-tokio` | `agent-client-protocol-tokio` | | `sacp-rmcp` | `agent-client-protocol-rmcp` | | `sacp-conductor` | `agent-client-protocol-conductor` | | `sacp-test` | `agent-client-protocol-test` | | `sacp-tee` | `agent-client-protocol-tee` | | `sacp-trace-viewer` | `agent-client-protocol-trace-viewer` | The `sacp` crates will then be deprecated in favor of the `agent-client-protocol` family. The new SDK addresses the limitations above through a builder-based API with explicit connection semantics. The following table summarizes the key API concepts and which goals they address: | API Concept | Goals Addressed | | --- | --- | | [Link types](https://agentclientprotocol.com/rfds/rust-sdk-v1#link-types-and-directional-naming)
(`ClientToAgent`, `AgentToClient`) | Confusing naming, 1:1 assumption | | [`Component` trait + `connect_to`](https://agentclientprotocol.com/rfds/rust-sdk-v1#the-component-trait-and-connect_to) | Awkward to connect components | | [Connection context (`cx`)](https://agentclientprotocol.com/rfds/rust-sdk-v1#sending-messages) | Handlers can’t send messages | | [`on_receive_*` handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#handling-messages)
with closure types | Fixed set of handlers | | [`serve` / `run_until`](https://agentclientprotocol.com/rfds/rust-sdk-v1#running-connections-serve-and-run_until) | Executor independence, starvation freedom | | [Session builders + dynamic handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#session-builders-and-mcp-servers) | Handlers must be same across sessions | | [Ordering guarantees + `spawn`](https://agentclientprotocol.com/rfds/rust-sdk-v1#controlling-ordering) | No ordering guarantees | We have validated the design by implementing a number of use cases: * **sacp-conductor** (to be renamed **agent-client-protocol-conductor**) - implementation of the conductor from the [proxy chains](https://agentclientprotocol.com/rfds/proxy-chains) RFD * [Patchwork](https://patchwork-lang.github.io/patchwork-rs/) - programmatic agent orchestration * **elizacp** - agent implementing the classic ELIZA program * **agent-client-protocol-tee** - proxy that logs messages before forwarding * **yopo** (“You Only Prompt Once”) - CLI tool for single prompts The [Deep dive](https://agentclientprotocol.com/rfds/rust-sdk-v1#deep-dive) section below walks through each concept in detail. [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#deep-dive) Deep dive ---------------------------------------------------------------------------- This section walks through the SDK concepts in detail, organized by what you’re trying to do. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#getting-up-and-going) Getting up and going #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#link-types-and-directional-naming) Link types and directional naming The SDK is organized around _link types_ that describe who you are and who you’re talking to. The two most common examples are: * `ClientToAgent` - “I am a client, connecting to an agent” * `AgentToClient` - “I am an agent, serving a client” To build a connection, start with the link type and invoke the `builder` method. Builders use the typical “fluent” style: // As a client connecting to an agent ClientToAgent::builder() .name("my-client") // optional, useful for tracing // As an agent serving clients AgentToClient::builder() .name("my-agent") // optional, useful for tracing Most types in the SDK are parameterized by the link type. This helps document the intent of the connection and also determines default method handling when no event handler is registered. (Both `ClientToAgent` and `AgentToClient` generally error on unhandled messages, but proxies default to forwarding.) #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#the-component-trait-and-connect_to) The `Component` trait and `connect_to` The `connect_to` method connects your builder to the other side. The argument can be anything that implements the `Component` trait, which abstracts over anything that can communicate via JSON-RPC: // Connect to an agent over stdio ClientToAgent::builder() .connect_to(acp::stdio()) The `AcpAgent` type allows connecting to an external ACP agent or agent extension: // Connect to a specific agent by command ClientToAgent::builder() .connect_to(AcpAgent::from_str("some-command --acp")) // Connect to Zed's Claude Code integration ClientToAgent::builder() .connect_to(AcpAgent::zed_claude_code()) For testing, you can connect builders directly to each other - no transport setup required: ClientToAgent::builder() .connect_to(AgentToClient::builder()) Or connect to a struct that implements `Component`: impl Component for MyAgent { async fn serve(self, client: impl Component) -> Result<(), acp::Error> { AgentToClient::builder() .on_receive_request(/* ... */) .serve(client) .await } } // Connect client directly to agent - useful for testing ClientToAgent::builder() .connect_to(MyAgent::new()) #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#running-connections-serve-and-run_until) Running connections: `serve` and `run_until` The `connect_to` method returns a `JrConnection`, but that connection is inert until executed. There are two ways to run it. **`serve()`** runs until the connection is closed. This is for “reactive” components that respond to incoming messages: AgentToClient::builder() .name("my-agent") .on_receive_request(/* ... */) .connect_to(transport)? .serve() .await **`run_until()`** takes an async closure and runs your code concurrently with message handling. The closure receives a _connection context_ (conventionally called `cx`) - this is how you interact with the connection, sending messages, spawning tasks, and adding dynamic handlers. When the closure returns, the connection closes: ClientToAgent::builder() .name("my-client") .connect_to(transport)? .run_until(async |cx| { // Your code runs here while messages are handled in the background. // Use `cx` to send requests and notifications. let response = cx.send_request(InitializeRequest::new(ProtocolVersion::LATEST)) .block_task().await?; Ok(response) }) .await The `run_until` pattern directly addresses starvation. Instead of exposing an async stream that users might accidentally block, `run_until` runs your code _concurrently_ with message handling. The `cx` type (`JrConnectionCx`) follows the “handle” pattern: cloned values refer to the same connection. It’s `'static` so it can be sent across threads or stored in structs. Handlers registered with `on_receive_*` also receive a `cx` parameter. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#sending-messages) Sending messages #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#sending-notifications) Sending notifications Use `cx.send_notification()` to send a notification. It returns a `Result` that is `Err` if the connection is broken: cx.send_notification(StatusNotification::new("processing"))?; #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#sending-requests) Sending requests Use `cx.send_request()` to send a request. This returns a handle for managing the response: let response_handle = cx.send_request(PromptRequest::new(session_id, messages)); The handle is not the response itself - that may not have arrived yet. You have two options for getting it: **`on_response` / `on_ok_response`** registers a handler that runs when the response arrives: cx.send_request(PromptRequest::new(session_id, messages)) .on_ok_response( async move |response: PromptResponse, cx| { println!("Agent finished: {:?}", response.stop_reason); Ok(()) }, acp::on_response!() )?; **`block_task`** returns a future you can await: let response: PromptResponse = cx.send_request(PromptRequest::new(session_id, messages)) .block_task() .await?; The `block_task` approach is convenient but dangerous in handlers (methods that begin with `on_`). See [Controlling ordering](https://agentclientprotocol.com/rfds/rust-sdk-v1#controlling-ordering) for details. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#controlling-ordering) Controlling ordering #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#atomic-handlers) Atomic handlers Handler methods (methods whose names begin with `on_`) execute in the order messages arrive. Each handler must complete before the next message is processed: .on_receive_request(async |req: PromptRequest, request_cx, cx| { // No other messages will be processed while this runs cx.send_notification(StatusNotification::new("processing"))?; // The notification is guaranteed to be sent before the response request_cx.respond(PromptResponse::new(StopReason::EndTurn)) }, acp::on_receive_request!()) #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#block_task-and-deadlock) `block_task` and deadlock Using `block_task` inside a handler creates a deadlock: the handler waits for a response, but responses can’t be processed until the handler completes. // WRONG - will deadlock .on_receive_request(async |req: PromptRequest, request_cx, cx| { let response = cx.send_request(SomeOtherRequest::new()) .block_task() // Deadlock! Handler blocks waiting for response .await?; // but responses can't be processed until handler returns request_cx.respond(/* ... */) }, acp::on_receive_request!()) Use `on_response` instead, or spawn a task. #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#spawning-tasks) Spawning tasks Use `cx.spawn` to run work concurrently with message handling: .on_receive_request(async |request: PromptRequest, request_cx, cx| { cx.spawn(async move { // Safe to use block_task here - we're in a spawned task let response = cx.send_request(InitializeRequest::new(ProtocolVersion::LATEST)) .block_task() .await?; /* ... */ Ok(()) })?; // Handler returns immediately, spawned work continues request_cx.respond(/* ... */) }, acp::on_receive_request!()) Spawned tasks are tracked in the `JrConnectionCx` and don’t require runtime-specific spawning. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#client-sessions) Client sessions When a client sends a `NewSessionRequest`, agents typically need to set up session-specific state: handlers that only apply to this session, MCP servers with tools tailored to the workspace, or initialization logic that runs once the session is confirmed. #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#session-builders) Session builders The session builder API provides a fluent interface for configuring sessions. Start with `cx.build_session()` or `cx.build_session_from()` and chain configuration methods: cx.build_session("/path/to/workspace") .with_mcp_server(my_mcp_server)? // Attach MCP servers (see below) // ... additional configuration MCP servers provide tools that the agent can invoke. We’ll show how to define them in the examples below. #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#running-sessions-with-run_until) Running sessions with `run_until` The primary way to run a session is with `block_task().run_until()`. This pattern allows your closure to capture borrowed state from the surrounding scope - no `'static` requirement: // Inside a run_until closure (not a handler) let workspace_path = Path::new("/my/workspace"); cx.build_session(workspace_path) .with_mcp_server( McpServer::builder("tools") .tool_fn("get_path", "Returns the path", async move |_: (), _| { // Can capture `workspace_path` by reference! Ok(workspace_path.display().to_string()) }, acp::tool_fn!()) .build() )? .block_task() .run_until(async |mut session| { session.send_prompt("What is the workspace path?")?; let response = session.read_to_string().await?; println!("{response}"); Ok(()) }) .await?; The `run_until` closure receives an `ActiveSession` with methods for interacting with the agent: * **`send_prompt(text)`** - Send a prompt to the agent * **`read_to_string()`** - Read all updates until the turn ends, returning text content * **`read_update()`** - Read individual updates for fine-grained control For more complex MCP servers, you can use the standard rmcp API via the `agent-client-protocol-rmcp` crate: use agent_client_protocol_rmcp::RmcpServer; cx.build_session(workspace_path) .with_mcp_server(RmcpServer::new(my_rmcp_service))? // ... #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#non-blocking-sessions-with-on_session_start) Non-blocking sessions with `on_session_start` When you need to start a session from inside an `on_receive_*` handler but can’t block, use `on_session_start`. This spawns the session work and returns immediately: .on_receive_request(async |req: NewSessionRequest, request_cx, cx| { cx.build_session_from(req) .with_mcp_server(my_mcp_server)? .on_session_start(async |mut session| { session.send_prompt("Hello")?; let response = session.read_to_string().await?; Ok(()) })?; // Handler returns immediately, session runs in background Ok(()) }, acp::on_receive_request!()) Note that `on_session_start` requires `'static` - closures and MCP servers cannot borrow from the surrounding scope. Use owned data or `Arc` for shared state. #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#start_session-and-proxy-sessions) `start_session` and proxy sessions For cases where you want to avoid the rightward drift of `run_until` but still need blocking behavior, `start_session` returns an `ActiveSession` handle directly: let mut session = cx.build_session(workspace_path) .with_mcp_server(my_mcp_server)? .block_task() .start_session() .await?; session.send_prompt("Hello")?; let response = session.read_to_string().await?; Like `on_session_start`, this requires `'static` for closures and MCP servers. For proxies that want to inject MCP servers but otherwise forward all messages, use `start_session_proxy`: .on_receive_request(async |req: NewSessionRequest, request_cx, cx| { let session_id = cx.build_session_from(req) .with_mcp_server(injected_tools)? .block_task() .start_session_proxy(request_cx) .await?; // Session messages are automatically proxied between client and agent Ok(()) }, acp::on_receive_request!()) ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#handling-messages) Handling messages #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#notification-handlers) Notification handlers Register handlers using `on_receive_notification`. The closure’s first argument type determines which notification type it handles: AgentToClient::builder() .on_receive_notification( async |notif: SessionNotification, cx| { // ------------------- // Expected notification type println!("Session update: {:?}", notif.update); Ok(()) }, acp::on_receive_notification!(), // <-- Hacky macro argument required ) Note the ‘hacky macro argument’. This is required due to current limitations in async closures. It can be removed once [Return Type Notation](https://github.com/rust-lang/rfcs/pull/3654) is stabilized and [issue #149407](https://github.com/rust-lang/rust/issues/149407) is fixed. #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#request-handlers) Request handlers Request handlers receive an additional `request_cx` parameter for sending the response: .on_receive_request( async |req: PromptRequest, request_cx, cx| { // Process the request... cx.send_notification(StatusNotification::new("processing"))?; // Send the response request_cx.respond(PromptResponse::new(StopReason::EndTurn)) }, acp::on_receive_request!(), ) The `request_cx` is `#[must_use]` - the compiler warns if you forget to send a response. It provides three methods: * **`respond(response)`** - Send a successful response * **`respond_with_error(error)`** - Send an error response * **`respond_with_result(result)`** - Send either, based on a `Result` The `request_cx` is `Send`, so you can move it to another task or thread if you need to respond asynchronously: .on_receive_request( async |req: LongRunningRequest, request_cx, cx| { cx.spawn(async move { let result = do_expensive_work(&req).await; request_cx.respond_with_result(result) }); Ok(()) }, acp::on_receive_request!(), ) ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#custom-message-types) Custom message types Define custom notifications and requests using derive macros: #[derive(Debug, Serialize, Deserialize, JsonSchema, JrNotification)] #[notification(method = "_myapp/progress")] struct ProgressNotification { percent: u32, message: String, } #[derive(Debug, Serialize, Deserialize, JsonSchema, JrRequest)] #[request(method = "_myapp/compute", response = ComputeResponse)] struct ComputeRequest { input: String, } #[derive(Debug, Serialize, Deserialize, JsonSchema)] struct ComputeResponse { result: String, } Custom types work exactly like built-in types - no special `ext_notification` path required: ClientToAgent::builder() .on_receive_notification( async |notif: ProgressNotification, cx| { println!("Progress: {}% - {}", notif.percent, notif.message); Ok(()) }, acp::on_receive_notification!() ) #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#generic-message-handlers) Generic message handlers Use `on_receive_message` with `MessageCx` to intercept any incoming message (request or notification) before typed handlers: .on_receive_message( async |message: MessageCx, cx| { // Forward all messages to another thread for processing message_sender.send(message)?; Ok(()) }, acp::on_receive_message!(), ) `MessageCx` is useful for forwarding, logging, or other scenarios where you need to intercept messages before typed dispatch. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#message-handling-in-depth) Message handling in depth #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#handler-chains) Handler chains A _message handler_ takes ownership of a message and either handles it or returns a (possibly modified) copy to be tried by the next handler. Handlers are chained together - each gets a chance to claim the message before it passes to the next. **Static handlers** are registered at build time via `.on_receive_request()`, etc. They’re tried in registration order. **Dynamic handlers** are added at runtime via `cx.add_dynamic_handler()`. They’re useful for sub-protocols where groups of related messages are identified by some kind of ID. For example, session messages all share a `session_id` - a dynamic handler can be registered for each session to handle its messages. **Link default handler** provides fallback behavior based on the link type (e.g., proxies forward unhandled messages). #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#message-handlers) Message handlers The `JrMessageHandler` trait defines how handlers work: pub trait JrMessageHandler: Send { type Link: JrLink; async fn handle_message( &mut self, message: MessageCx, cx: JrConnectionCx, ) -> Result, Error>; } The handler takes ownership of the message. If it handles the message, it returns `Handled::Yes`. If not, it returns ownership via `Handled::No { message, retry }` so the next handler can try: pub enum Handled { Yes, No { message: T, retry: bool }, } **The `retry` flag**: If any of the static or dynamic handlers returns `retry: true`, and no handler ultimately claims the message, it gets queued and offered to each new dynamic handler as it’s added. This solves a race condition with sessions: messages for a session may arrive before the session’s dynamic handler is registered. The default handlers for `ClientToAgent` and `AgentToClient` already set `retry: true` for session messages with unrecognized session IDs, so you typically don’t need to handle this yourself. For convenience, handlers can return `Ok(())` which is equivalent to `Handled::Yes`. Handlers can also modify the message before passing it along: .on_receive_request(async |mut req: EchoRequest, request_cx, cx| { req.text.push("modified".to_string()); Ok(Handled::No { message: (req, request_cx), retry: false, }) }, acp::on_receive_request!()) #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#registering-dynamic-handlers) Registering dynamic handlers Register dynamic handlers at runtime for session-specific or protocol-specific message handling: let registration = cx.add_dynamic_handler(MySessionHandler::new(session_id))?; When `registration` is dropped, the dynamic handler is removed. To keep it alive indefinitely, call `run_indefinitely()`: registration.run_indefinitely(); #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#default-handling-from-link-type) Default handling from link type Each link type defines default handling for unhandled messages. For example: * **`ClientToAgent`** - Errors on unhandled requests, ignores unhandled notifications * **`ProxyToConductor`** - Forwards unhandled messages to the next component You only need to register handlers for messages you want to intercept. #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#matchmessage-for-implementing-handlers) MatchMessage for implementing handlers When implementing `JrMessageHandler` directly, `MatchMessage` provides ergonomic dispatch: impl JrMessageHandler for MyHandler { type Link = AgentToClient; async fn handle_message( &mut self, message: MessageCx, cx: JrConnectionCx, ) -> Result, Error> { MatchMessage::new(message) .if_request(async |req: InitializeRequest, request_cx| { request_cx.respond(InitializeResponse::new(req.protocol_version)) }) .if_request(async |req: PromptRequest, request_cx| { request_cx.respond(PromptResponse::new(StopReason::EndTurn)) }) .if_notification(async |notif: SessionNotification| { log::info!("Session update: {:?}", notif); Ok(()) }) .await .done() } } For proxies with multiple peers, `MatchMessageFrom` dispatches based on message source: MatchMessageFrom::new(message, &cx) .if_request_from(Client, async |req: PromptRequest, request_cx| { // Handle requests from the client }) .if_notification_from(Agent, async |notif: SessionNotification| { // Handle notifications from the agent }) .await .done() ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#error-handling) Error handling Errors in handlers tear down the connection. If a handler returns an `Err`, the connection closes and all pending operations fail. For request handlers, you can propagate error responses instead of tearing down the connection: .on_receive_request(async |req: ComputeRequest, request_cx, cx| { match process(&req) { Ok(result) => request_cx.respond(ComputeResponse { result }), Err(e) => request_cx.respond_err(JsonRpcError::new( ErrorCode::InvalidParams, format!("Failed to process: {}", e), )), } }, acp::on_receive_request!()) ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#writing-proxies) Writing proxies #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#multiple-peers) Multiple peers Simple link types like `ClientToAgent` have one remote peer. Proxy link types like `ProxyToConductor` have two: `Client` (predecessor) and `Agent` (successor). With multiple peers, you must explicitly name which peer you’re communicating with: ProxyToConductor::builder() .on_receive_notification_from( acp::Agent, // <-- Receive from the agent async |notif: SessionNotification, cx| { cx.send_notification_to(acp::Client, notif)?; // ----------- // Send to the client Ok(()) }, acp::on_receive_notification!(), ) #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#default-forwarding) Default forwarding For proxies, the default handling is typically `Forward` - unhandled messages pass through to the next component. You only need to register handlers for messages you want to intercept or modify. #### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#session-builders-for-proxies) Session builders for proxies Proxies can add session-scoped handlers: cx.build_session_from(req) .on_receive_notification(async |notif: SessionNotification, cx| { // This handler only runs for this session log_notification(¬if); Ok(()) }, acp::on_receive_notification!()) .on_proxy_session_start(request_cx, async |_| Ok(())) ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#advanced-defining-custom-link-types) Advanced: Defining custom link types Link types define the relationship between peers. The SDK provides built-in types, but you can define your own: use acp::link::{JrLink, LinkDirection}; pub struct MyCustomLink; impl JrLink for MyCustomLink { type ConnectsTo = OtherSideLink; fn direction() -> LinkDirection { LinkDirection::Outbound // We initiate the connection } fn default_request_handling() -> DefaultHandling { DefaultHandling::Error // Unknown requests return an error } fn default_notification_handling() -> DefaultHandling { DefaultHandling::Ignore // Unknown notifications are silently dropped } } [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#shiny-future) Shiny future ---------------------------------------------------------------------------------- > How will things play out once this feature exists? ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#unified-rust-acp-experience) Unified Rust ACP experience The Rust ecosystem will have a single SDK for ACP development. Whether you’re building a simple client, a proxy chain, or a programmatic orchestration framework like patchwork-rs, the same SDK handles all cases. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#smooth-transition-from-the-current-sdk) Smooth transition from the current SDK The new SDK is more ergonomic than the current trait-based approach, so migration should be straightforward for most users. The builder pattern with context parameters (`cx`) replaces the `AgentSideConnection` pattern, and the directional naming (`ClientToAgent` vs `AgentSideConnection`) makes code clearer. We can provide migration guidance and potentially a thin compatibility layer for common patterns, but most users will find the new code simpler than the old. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#potential-crate-reorganization) Potential crate reorganization Currently, `agent-client-protocol` contains both generic JSON-RPC machinery (builder patterns, message handling, connection management) and ACP-specific types (link types, schema integration). In the future, it might be valuable to split the generic JSON-RPC layer into its own crate. However, this is complicated by the trait implementations: the generic traits need to be implemented for ACP types currently defined in the schema crate. We’d need to carefully consider where type definitions live to avoid orphan rule issues. This reorganization isn’t blocking for the initial adoption. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#cross-language-sdk-alignment) Cross-language SDK alignment The design principles here - builder patterns, context parameters, directional naming, component abstractions - aren’t Rust-specific. They represent good SDK design that could inform TypeScript and other language SDKs. This doesn’t mean other SDKs should be ports of the Rust SDK. Each language has its own idioms. But the core ideas (explicit message ordering, composable components, context in callbacks) translate across languages. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#foundation-for-protocol-evolution) Foundation for protocol evolution The builder pattern and component model make it easier to evolve the ACP protocol. New methods can be added without breaking existing code. New component types (beyond client/agent/proxy) can be introduced by implementing the Component trait. [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#implementation-details-and-plan) Implementation details and plan ------------------------------------------------------------------------------------------------------------------------ > Tell me more about your implementation. What is your detailed implementation plan? ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#crate-structure) Crate structure The new SDK is organized into several crates with clear responsibilities: * **`agent-client-protocol`** - Core SDK with builder patterns, link types, and component abstractions * **`agent-client-protocol-tokio`** - Tokio runtime integration (spawn, timers, I/O) * **`agent-client-protocol-rmcp`** - Bridge to the rmcp crate for MCP integration * **`agent-client-protocol-conductor`** - Reference conductor implementation * **`agent-client-protocol-derive`** - Derive macros for JSON-RPC traits * **`agent-client-protocol-test`** - Test utilities and mock implementations * **`agent-client-protocol-tee`** - Debugging proxy that logs all traffic * **`agent-client-protocol-trace-viewer`** - Interactive sequence diagram viewer for trace files ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#current-status) Current status A working implementation exists in the [symposium-dev/symposium-acp](https://github.com/symposium-dev/symposium-acp) repository and is published on crates.io. It powers: * The conductor (proxy chain orchestration) * patchwork-rs (programmatic agent orchestration) * Symposium (Rust development environment) ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#migration-path) Migration path The transition involves importing the `sacp` implementation into this repository: 1. **Import `sacp` crates** into this repository with the new `agent-client-protocol-*` naming 2. **Release `agent-client-protocol` v1.0** with the new builder-based API 3. **Deprecate `sacp` crates** on crates.io, pointing users to the `agent-client-protocol` family 4. **Provide migration guidance** for users of the current v0.x SDK Most users will find the migration straightforward - the builder pattern is more ergonomic than the trait-based approach, so the new code is often simpler than the old. [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#frequently-asked-questions) Frequently asked questions -------------------------------------------------------------------------------------------------------------- > What questions have arisen over the course of authoring this document or during subsequent discussions? ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-alternative-approaches-did-you-consider) What alternative approaches did you consider? We first attempted to build on the existing SDK but due to the limitations decided to try an alternative approach. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-about-other-language-sdks) What about other language SDKs? We would like to try and adapt these ideas to other languages. It would be good if the SDKs for all languages took the same general approach. Most of the concerns in this document are not Rust-specific, though as often happens, the limitations become more annoying in Rust because of the limits imposed by the ownership system. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#how-does-this-relate-to-the-proxy-chains-and-mcp-over-acp-rfds) How does this relate to the Proxy Chains and MCP-over-ACP RFDs? This expanded SDK design is motivated by working through the use cases enabled by [proxy chains](https://agentclientprotocol.com/rfds/proxy-chains) and [MCP-over-ACP](https://agentclientprotocol.com/rfds/mcp-over-acp) . ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#how-well-tested-is-this-design) How well-tested is this design? The design has been used for a wide range of projects but the majority were written by the SDK author, though Amazon’s kiro-cli team and the Goose client adopted sacp for their use case with minimal difficulty. Before we finalize the design, it would be good to have more adopters to help ensure that it meets all common needs. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#can-i-derive-jrrequest/jrnotification-on-enums) Can I derive `JrRequest`/`JrNotification` on enums? Not currently. The derive macros only support structs with a single method name. For enums that group related messages (e.g., all session-related requests), you would need to implement the traits manually. This is a potential future enhancement - enum derives could dispatch to different methods per variant, which would be useful for `MessageCx` typed handlers. For now, use the untyped `MessageCx` with `MatchMessage` for this pattern. ### [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-changes-are-needed-before-stabilizing) What changes are needed before stabilizing? We are in the process of changing how response messages work to simplify the implementation of the conductor. Before stabilizing we should do a thorough review of the methods and look for candidates that can be removed or simplified. The conductor is feature complete but the support for MCP-over-ACP needs a few minor improvements (in particular, it should detect when the agent only supports stdio bridging and not attempt to use HTTP, which it currently does not). [​](https://agentclientprotocol.com/rfds/rust-sdk-v1#revision-history) Revision history ------------------------------------------------------------------------------------------ * Initial draft based on working implementation in symposium-acp repository. Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/rfds/auth-methods) [Logout Method\ \ Next](https://agentclientprotocol.com/rfds/logout-method) ⌘I On this page * [Elevator pitch](https://agentclientprotocol.com/rfds/rust-sdk-v1#elevator-pitch) * [Status quo](https://agentclientprotocol.com/rfds/rust-sdk-v1#status-quo) * [Limitation: Handlers can’t send messages](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-handlers-can%E2%80%99t-send-messages) * [Limitation: Fixed set of handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-fixed-set-of-handlers) * [Limitation: Message handlers must be the same across all session](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-message-handlers-must-be-the-same-across-all-session) * [Limitation: No ordering guarantees](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-no-ordering-guarantees) * [Limitation: Confusing naming and 1:1 assumption](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-confusing-naming-and-11-assumption) * [Limitation: Awkward to connect components](https://agentclientprotocol.com/rfds/rust-sdk-v1#limitation-awkward-to-connect-components) * [Challenge: Executor independence and starvation freedom](https://agentclientprotocol.com/rfds/rust-sdk-v1#challenge-executor-independence-and-starvation-freedom) * [What we propose to do about it](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-we-propose-to-do-about-it) * [Deep dive](https://agentclientprotocol.com/rfds/rust-sdk-v1#deep-dive) * [Getting up and going](https://agentclientprotocol.com/rfds/rust-sdk-v1#getting-up-and-going) * [Link types and directional naming](https://agentclientprotocol.com/rfds/rust-sdk-v1#link-types-and-directional-naming) * [The Component trait and connect\_to](https://agentclientprotocol.com/rfds/rust-sdk-v1#the-component-trait-and-connect_to) * [Running connections: serve and run\_until](https://agentclientprotocol.com/rfds/rust-sdk-v1#running-connections-serve-and-run_until) * [Sending messages](https://agentclientprotocol.com/rfds/rust-sdk-v1#sending-messages) * [Sending notifications](https://agentclientprotocol.com/rfds/rust-sdk-v1#sending-notifications) * [Sending requests](https://agentclientprotocol.com/rfds/rust-sdk-v1#sending-requests) * [Controlling ordering](https://agentclientprotocol.com/rfds/rust-sdk-v1#controlling-ordering) * [Atomic handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#atomic-handlers) * [block\_task and deadlock](https://agentclientprotocol.com/rfds/rust-sdk-v1#block_task-and-deadlock) * [Spawning tasks](https://agentclientprotocol.com/rfds/rust-sdk-v1#spawning-tasks) * [Client sessions](https://agentclientprotocol.com/rfds/rust-sdk-v1#client-sessions) * [Session builders](https://agentclientprotocol.com/rfds/rust-sdk-v1#session-builders) * [Running sessions with run\_until](https://agentclientprotocol.com/rfds/rust-sdk-v1#running-sessions-with-run_until) * [Non-blocking sessions with on\_session\_start](https://agentclientprotocol.com/rfds/rust-sdk-v1#non-blocking-sessions-with-on_session_start) * [start\_session and proxy sessions](https://agentclientprotocol.com/rfds/rust-sdk-v1#start_session-and-proxy-sessions) * [Handling messages](https://agentclientprotocol.com/rfds/rust-sdk-v1#handling-messages) * [Notification handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#notification-handlers) * [Request handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#request-handlers) * [Custom message types](https://agentclientprotocol.com/rfds/rust-sdk-v1#custom-message-types) * [Generic message handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#generic-message-handlers) * [Message handling in depth](https://agentclientprotocol.com/rfds/rust-sdk-v1#message-handling-in-depth) * [Handler chains](https://agentclientprotocol.com/rfds/rust-sdk-v1#handler-chains) * [Message handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#message-handlers) * [Registering dynamic handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#registering-dynamic-handlers) * [Default handling from link type](https://agentclientprotocol.com/rfds/rust-sdk-v1#default-handling-from-link-type) * [MatchMessage for implementing handlers](https://agentclientprotocol.com/rfds/rust-sdk-v1#matchmessage-for-implementing-handlers) * [Error handling](https://agentclientprotocol.com/rfds/rust-sdk-v1#error-handling) * [Writing proxies](https://agentclientprotocol.com/rfds/rust-sdk-v1#writing-proxies) * [Multiple peers](https://agentclientprotocol.com/rfds/rust-sdk-v1#multiple-peers) * [Default forwarding](https://agentclientprotocol.com/rfds/rust-sdk-v1#default-forwarding) * [Session builders for proxies](https://agentclientprotocol.com/rfds/rust-sdk-v1#session-builders-for-proxies) * [Advanced: Defining custom link types](https://agentclientprotocol.com/rfds/rust-sdk-v1#advanced-defining-custom-link-types) * [Shiny future](https://agentclientprotocol.com/rfds/rust-sdk-v1#shiny-future) * [Unified Rust ACP experience](https://agentclientprotocol.com/rfds/rust-sdk-v1#unified-rust-acp-experience) * [Smooth transition from the current SDK](https://agentclientprotocol.com/rfds/rust-sdk-v1#smooth-transition-from-the-current-sdk) * [Potential crate reorganization](https://agentclientprotocol.com/rfds/rust-sdk-v1#potential-crate-reorganization) * [Cross-language SDK alignment](https://agentclientprotocol.com/rfds/rust-sdk-v1#cross-language-sdk-alignment) * [Foundation for protocol evolution](https://agentclientprotocol.com/rfds/rust-sdk-v1#foundation-for-protocol-evolution) * [Implementation details and plan](https://agentclientprotocol.com/rfds/rust-sdk-v1#implementation-details-and-plan) * [Crate structure](https://agentclientprotocol.com/rfds/rust-sdk-v1#crate-structure) * [Current status](https://agentclientprotocol.com/rfds/rust-sdk-v1#current-status) * [Migration path](https://agentclientprotocol.com/rfds/rust-sdk-v1#migration-path) * [Frequently asked questions](https://agentclientprotocol.com/rfds/rust-sdk-v1#frequently-asked-questions) * [What alternative approaches did you consider?](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-alternative-approaches-did-you-consider) * [What about other language SDKs?](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-about-other-language-sdks) * [How does this relate to the Proxy Chains and MCP-over-ACP RFDs?](https://agentclientprotocol.com/rfds/rust-sdk-v1#how-does-this-relate-to-the-proxy-chains-and-mcp-over-acp-rfds) * [How well-tested is this design?](https://agentclientprotocol.com/rfds/rust-sdk-v1#how-well-tested-is-this-design) * [Can I derive JrRequest/JrNotification on enums?](https://agentclientprotocol.com/rfds/rust-sdk-v1#can-i-derive-jrrequest%2Fjrnotification-on-enums) * [What changes are needed before stabilizing?](https://agentclientprotocol.com/rfds/rust-sdk-v1#what-changes-are-needed-before-stabilizing) * [Revision history](https://agentclientprotocol.com/rfds/rust-sdk-v1#revision-history) --- # Schema - Agent Client Protocol [Skip to main content](https://agentclientprotocol.com/protocol/schema#content-area) [Agent Client Protocol home page![light logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/light.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=0c3a91b5b58329f66ffe53c9d5b300a2)![dark logo](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/logo/dark.svg?fit=max&auto=format&n=ZwvtxaoaZwBJrK5s&q=85&s=99cc8d69910f89294f950a22e9dfc988)](https://agentclientprotocol.com/) Search... ⌘K Search... Navigation Protocol Schema [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [Protocol](https://agentclientprotocol.com/get-started/introduction) [RFDs](https://agentclientprotocol.com/rfds/about) [Community](https://agentclientprotocol.com/community/communication) [Publications](https://agentclientprotocol.com/publications) [Updates](https://agentclientprotocol.com/updates) [Brand](https://agentclientprotocol.com/brand) [​](https://agentclientprotocol.com/protocol/schema#agent) Agent ------------------------------------------------------------------- Defines the interface that all ACP-compliant agents must implement. Agents are programs that use generative AI to autonomously modify code. They handle requests from clients and execute tasks using language models and tools. ### [​](https://agentclientprotocol.com/protocol/schema#authenticate) authenticate Authenticates the client using the specified authentication method. Called when the agent requires authentication before allowing session creation. The client provides the authentication method ID that was advertised during initialization. After successful authentication, the client can proceed to create sessions with `new_session` without receiving an `auth_required` error. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization) #### [​](https://agentclientprotocol.com/protocol/schema#authenticaterequest) AuthenticateRequest Request parameters for the authenticate method. Specifies which authentication method to use. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-method-id) methodId string required The ID of the authentication method to use. Must be one of the methods advertised in the initialize response. #### [​](https://agentclientprotocol.com/protocol/schema#authenticateresponse) AuthenticateResponse Response to the `authenticate` method. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-1) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) ### [​](https://agentclientprotocol.com/protocol/schema#initialize) initialize Establishes the connection with a client and negotiates protocol capabilities. This method is called once at the beginning of the connection to: * Negotiate the protocol version to use * Exchange capability information between client and agent * Determine available authentication methods The agent should respond with its supported protocol version and capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization) #### [​](https://agentclientprotocol.com/protocol/schema#initializerequest) InitializeRequest Request parameters for the initialize method. Sent by the client to establish connection and negotiate capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-2) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-client-capabilities) clientCapabilities Capabilities supported by the client. * Default: `{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}` [​](https://agentclientprotocol.com/protocol/schema#param-client-info) clientInfo Information about the Client name and version sent to the Agent.Note: in future versions of the protocol, this will be required. [​](https://agentclientprotocol.com/protocol/schema#param-protocol-version) protocolVersion required The latest protocol version supported by the client. #### [​](https://agentclientprotocol.com/protocol/schema#initializeresponse) InitializeResponse Response to the `initialize` method. Contains the negotiated protocol version and agent capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-3) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-agent-capabilities) agentCapabilities Capabilities supported by the agent. * Default: `{"loadSession":false,"mcpCapabilities":{"http":false,"sse":false},"promptCapabilities":{"audio":false,"embeddedContext":false,"image":false},"sessionCapabilities":{}}` [​](https://agentclientprotocol.com/protocol/schema#param-agent-info) agentInfo Information about the Agent name and version sent to the Client.Note: in future versions of the protocol, this will be required. [​](https://agentclientprotocol.com/protocol/schema#param-auth-methods) authMethods Authentication methods supported by the agent. * Default: `[]` [​](https://agentclientprotocol.com/protocol/schema#param-protocol-version-1) protocolVersion required The protocol version the client specified if supported by the agent, or the latest protocol version supported by the agent.The client should disconnect, if it doesn’t support this version. ### [​](https://agentclientprotocol.com/protocol/schema#session/cancel) session/cancel Cancels ongoing operations for a session. This is a notification sent by the client to cancel an ongoing prompt turn. Upon receiving this notification, the Agent SHOULD: * Stop all language model requests as soon as possible * Abort all tool call invocations in progress * Send any pending `session/update` notifications * Respond to the original `session/prompt` request with `StopReason::Cancelled` See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) #### [​](https://agentclientprotocol.com/protocol/schema#cancelnotification) CancelNotification Notification to cancel ongoing operations for a session. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-4) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-session-id) sessionId required The ID of the session to cancel operations for. ### [​](https://agentclientprotocol.com/protocol/schema#session/list) session/list Lists existing sessions known to the agent. This method is only available if the agent advertises the `sessionCapabilities.list` capability. The agent should return metadata about sessions with optional filtering and pagination support. #### [​](https://agentclientprotocol.com/protocol/schema#listsessionsrequest) ListSessionsRequest Request parameters for listing existing sessions. Only available if the Agent supports the `sessionCapabilities.list` capability. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-5) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-cursor) cursor string | null Opaque cursor token from a previous response’s nextCursor field for cursor-based pagination [​](https://agentclientprotocol.com/protocol/schema#param-cwd) cwd string | null Filter sessions by working directory. Must be an absolute path. #### [​](https://agentclientprotocol.com/protocol/schema#listsessionsresponse) ListSessionsResponse Response from listing sessions. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-6) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-next-cursor) nextCursor string | null Opaque cursor token. If present, pass this in the next request’s cursor parameter to fetch the next page. If absent, there are no more results. [​](https://agentclientprotocol.com/protocol/schema#param-sessions) sessions required Array of session information objects ### [​](https://agentclientprotocol.com/protocol/schema#session/load) session/load Loads an existing session to resume a previous conversation. This method is only available if the agent advertises the `loadSession` capability. The agent should: * Restore the session context and conversation history * Connect to the specified MCP servers * Stream the entire conversation history back to the client via notifications See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) #### [​](https://agentclientprotocol.com/protocol/schema#loadsessionrequest) LoadSessionRequest Request parameters for loading an existing session. Only available if the Agent supports the `loadSession` capability. See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-7) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-cwd-1) cwd string required The working directory for this session. [​](https://agentclientprotocol.com/protocol/schema#param-mcp-servers) mcpServers required List of MCP servers to connect to for this session. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-1) sessionId required The ID of the session to load. #### [​](https://agentclientprotocol.com/protocol/schema#loadsessionresponse) LoadSessionResponse Response from loading an existing session. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-8) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-config-options) configOptions Initial session configuration options if supported by the Agent. [​](https://agentclientprotocol.com/protocol/schema#param-modes) modes Initial mode state if supported by the AgentSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) ### [​](https://agentclientprotocol.com/protocol/schema#session/new) session/new Creates a new conversation session with the agent. Sessions represent independent conversation contexts with their own history and state. The agent should: * Create a new session context * Connect to any specified MCP servers * Return a unique session ID for future requests May return an `auth_required` error if the agent requires authentication. See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup) #### [​](https://agentclientprotocol.com/protocol/schema#newsessionrequest) NewSessionRequest Request parameters for creating a new session. See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-9) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-cwd-2) cwd string required The working directory for this session. Must be an absolute path. [​](https://agentclientprotocol.com/protocol/schema#param-mcp-servers-1) mcpServers required List of MCP (Model Context Protocol) servers the agent should connect to. #### [​](https://agentclientprotocol.com/protocol/schema#newsessionresponse) NewSessionResponse Response from creating a new session. See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-10) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-config-options-1) configOptions Initial session configuration options if supported by the Agent. [​](https://agentclientprotocol.com/protocol/schema#param-modes-1) modes Initial mode state if supported by the AgentSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) [​](https://agentclientprotocol.com/protocol/schema#param-session-id-2) sessionId required Unique identifier for the created session.Used in all subsequent requests for this conversation. ### [​](https://agentclientprotocol.com/protocol/schema#session/prompt) session/prompt Processes a user prompt within a session. This method handles the whole lifecycle of a prompt: * Receives user messages with optional context (files, images, etc.) * Processes the prompt using language models * Reports language model content and tool calls to the Clients * Requests permission to run tools * Executes any requested tool calls * Returns when the turn is complete with a stop reason See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn) #### [​](https://agentclientprotocol.com/protocol/schema#promptrequest) PromptRequest Request parameters for sending a user prompt to the agent. Contains the user’s message and any additional context. See protocol docs: [User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-11) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-prompt) prompt required The blocks of content that compose the user’s message.As a baseline, the Agent MUST support `ContentBlock::Text` and `ContentBlock::ResourceLink`, while other variants are optionally enabled via `PromptCapabilities`.The Client MUST adapt its interface according to `PromptCapabilities`.The client MAY include referenced pieces of context as either `ContentBlock::Resource` or `ContentBlock::ResourceLink`.When available, `ContentBlock::Resource` is preferred as it avoids extra round-trips and allows the message to include pieces of context from sources the agent may not have access to. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-3) sessionId required The ID of the session to send this user message to #### [​](https://agentclientprotocol.com/protocol/schema#promptresponse) PromptResponse Response from processing a user prompt. See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-12) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-stop-reason) stopReason required Indicates why the agent stopped processing the turn. ### [​](https://agentclientprotocol.com/protocol/schema#session/set_config_option) session/set\_config\_option Sets the current value for a session configuration option. #### [​](https://agentclientprotocol.com/protocol/schema#setsessionconfigoptionrequest) SetSessionConfigOptionRequest Request parameters for setting a session configuration option. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-13) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-config-id) configId required The ID of the configuration option to set. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-4) sessionId required The ID of the session to set the configuration option for. [​](https://agentclientprotocol.com/protocol/schema#param-value) value required The ID of the configuration option value to set. #### [​](https://agentclientprotocol.com/protocol/schema#setsessionconfigoptionresponse) SetSessionConfigOptionResponse Response to `session/set_config_option` method. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-14) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-config-options-2) configOptions required The full set of configuration options and their current values. ### [​](https://agentclientprotocol.com/protocol/schema#session/set_mode) session/set\_mode Sets the current mode for a session. Allows switching between different agent modes (e.g., “ask”, “architect”, “code”) that affect system prompts, tool availability, and permission behaviors. The mode must be one of the modes advertised in `availableModes` during session creation or loading. Agents may also change modes autonomously and notify the client via `current_mode_update` notifications. This method can be called at any time during a session, whether the Agent is idle or actively generating a response. See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) #### [​](https://agentclientprotocol.com/protocol/schema#setsessionmoderequest) SetSessionModeRequest Request parameters for setting a session mode. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-15) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-mode-id) modeId required The ID of the mode to set. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-5) sessionId required The ID of the session to set the mode for. #### [​](https://agentclientprotocol.com/protocol/schema#setsessionmoderesponse) SetSessionModeResponse Response to `session/set_mode` method. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-16) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#client) Client --------------------------------------------------------------------- Defines the interface that ACP-compliant clients must implement. Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources. ### [​](https://agentclientprotocol.com/protocol/schema#fs/read_text_file) fs/read\_text\_file Reads content from a text file in the client’s file system. Only available if the client advertises the `fs.readTextFile` capability. Allows the agent to access file contents within the client’s environment. See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client) #### [​](https://agentclientprotocol.com/protocol/schema#readtextfilerequest) ReadTextFileRequest Request to read content from a text file. Only available if the client supports the `fs.readTextFile` capability. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-17) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-limit) limit integer | null Maximum number of lines to read. * Minimum: `0` [​](https://agentclientprotocol.com/protocol/schema#param-line) line integer | null Line number to start reading from (1-based). * Minimum: `0` [​](https://agentclientprotocol.com/protocol/schema#param-path) path string required Absolute path to the file to read. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-6) sessionId required The session ID for this request. #### [​](https://agentclientprotocol.com/protocol/schema#readtextfileresponse) ReadTextFileResponse Response containing the contents of a text file. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-18) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content) content string required ### [​](https://agentclientprotocol.com/protocol/schema#fs/write_text_file) fs/write\_text\_file Writes content to a text file in the client’s file system. Only available if the client advertises the `fs.writeTextFile` capability. Allows the agent to create or modify files within the client’s environment. See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client) #### [​](https://agentclientprotocol.com/protocol/schema#writetextfilerequest) WriteTextFileRequest Request to write content to a text file. Only available if the client supports the `fs.writeTextFile` capability. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-19) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-1) content string required The text content to write to the file. [​](https://agentclientprotocol.com/protocol/schema#param-path-1) path string required Absolute path to the file to write. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-7) sessionId required The session ID for this request. #### [​](https://agentclientprotocol.com/protocol/schema#writetextfileresponse) WriteTextFileResponse Response to `fs/write_text_file` **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-20) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) ### [​](https://agentclientprotocol.com/protocol/schema#session/request_permission) session/request\_permission Requests permission from the user for a tool call operation. Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision. If the client cancels the prompt turn via `session/cancel`, it MUST respond to this request with `RequestPermissionOutcome::Cancelled`. See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) #### [​](https://agentclientprotocol.com/protocol/schema#requestpermissionrequest) RequestPermissionRequest Request for user permission to execute a tool call. Sent when the agent needs authorization before performing a sensitive operation. See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-21) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-options) options required Available permission options for the user to choose from. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-8) sessionId required The session ID for this request. [​](https://agentclientprotocol.com/protocol/schema#param-tool-call) toolCall required Details about the tool call requiring permission. #### [​](https://agentclientprotocol.com/protocol/schema#requestpermissionresponse) RequestPermissionResponse Response to a permission request. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-22) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-outcome) outcome required The user’s decision on the permission request. ### [​](https://agentclientprotocol.com/protocol/schema#session/update) session/update Handles session update notifications from the agent. This is a notification endpoint (no response expected) that receives real-time updates about session progress, including message chunks, tool calls, and execution plans. Note: Clients SHOULD continue accepting tool call updates even after sending a `session/cancel` notification, as the agent may send final updates before responding with the cancelled stop reason. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) #### [​](https://agentclientprotocol.com/protocol/schema#sessionnotification) SessionNotification Notification containing a session update from the agent. Used to stream real-time progress and results during prompt processing. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-23) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-session-id-9) sessionId required The ID of the session this update pertains to. [​](https://agentclientprotocol.com/protocol/schema#param-update) update required The actual update content. ### [​](https://agentclientprotocol.com/protocol/schema#terminal/create) terminal/create Executes a command in a new terminal Only available if the `terminal` Client capability is set to `true`. Returns a `TerminalId` that can be used with other terminal methods to get the current output, wait for exit, and kill the command. The `TerminalId` can also be used to embed the terminal in a tool call by using the `ToolCallContent::Terminal` variant. The Agent is responsible for releasing the terminal by using the `terminal/release` method. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) #### [​](https://agentclientprotocol.com/protocol/schema#createterminalrequest) CreateTerminalRequest Request to create a new terminal and execute a command. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-24) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-args) args Array of command arguments. [​](https://agentclientprotocol.com/protocol/schema#param-command) command string required The command to execute. [​](https://agentclientprotocol.com/protocol/schema#param-cwd-3) cwd string | null Working directory for the command (absolute path). [​](https://agentclientprotocol.com/protocol/schema#param-env) env Environment variables for the command. [​](https://agentclientprotocol.com/protocol/schema#param-output-byte-limit) outputByteLimit integer | null Maximum number of output bytes to retain.When the limit is exceeded, the Client truncates from the beginning of the output to stay within the limit.The Client MUST ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit. * Minimum: `0` [​](https://agentclientprotocol.com/protocol/schema#param-session-id-10) sessionId required The session ID for this request. #### [​](https://agentclientprotocol.com/protocol/schema#createterminalresponse) CreateTerminalResponse Response containing the ID of the created terminal. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-25) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-terminal-id) terminalId string required The unique identifier for the created terminal. ### [​](https://agentclientprotocol.com/protocol/schema#terminal/kill) terminal/kill Kills the terminal command without releasing the terminal While `terminal/release` will also kill the command, this method will keep the `TerminalId` valid so it can be used with other methods. This method can be helpful when implementing command timeouts which terminate the command as soon as elapsed, and then get the final output so it can be sent to the model. Note: Call `terminal/release` when `TerminalId` is no longer needed. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) #### [​](https://agentclientprotocol.com/protocol/schema#killterminalrequest) KillTerminalRequest Request to kill a terminal without releasing it. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-26) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-session-id-11) sessionId required The session ID for this request. [​](https://agentclientprotocol.com/protocol/schema#param-terminal-id-1) terminalId string required The ID of the terminal to kill. #### [​](https://agentclientprotocol.com/protocol/schema#killterminalresponse) KillTerminalResponse Response to `terminal/kill` method **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-27) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) ### [​](https://agentclientprotocol.com/protocol/schema#terminal/output) terminal/output Gets the terminal output and exit status Returns the current content in the terminal without waiting for the command to exit. If the command has already exited, the exit status is included. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) #### [​](https://agentclientprotocol.com/protocol/schema#terminaloutputrequest) TerminalOutputRequest Request to get the current output and status of a terminal. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-28) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-session-id-12) sessionId required The session ID for this request. [​](https://agentclientprotocol.com/protocol/schema#param-terminal-id-2) terminalId string required The ID of the terminal to get output from. #### [​](https://agentclientprotocol.com/protocol/schema#terminaloutputresponse) TerminalOutputResponse Response containing the terminal output and exit status. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-29) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-exit-status) exitStatus Exit status if the command has completed. [​](https://agentclientprotocol.com/protocol/schema#param-output) output string required The terminal output captured so far. [​](https://agentclientprotocol.com/protocol/schema#param-truncated) truncated boolean required Whether the output was truncated due to byte limits. ### [​](https://agentclientprotocol.com/protocol/schema#terminal/release) terminal/release Releases a terminal The command is killed if it hasn’t exited yet. Use `terminal/wait_for_exit` to wait for the command to exit before releasing the terminal. After release, the `TerminalId` can no longer be used with other `terminal/*` methods, but tool calls that already contain it, continue to display its output. The `terminal/kill` method can be used to terminate the command without releasing the terminal, allowing the Agent to call `terminal/output` and other methods. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) #### [​](https://agentclientprotocol.com/protocol/schema#releaseterminalrequest) ReleaseTerminalRequest Request to release a terminal and free its resources. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-30) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-session-id-13) sessionId required The session ID for this request. [​](https://agentclientprotocol.com/protocol/schema#param-terminal-id-3) terminalId string required The ID of the terminal to release. #### [​](https://agentclientprotocol.com/protocol/schema#releaseterminalresponse) ReleaseTerminalResponse Response to terminal/release method **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-31) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) ### [​](https://agentclientprotocol.com/protocol/schema#terminal/wait_for_exit) terminal/wait\_for\_exit Waits for the terminal command to exit and return its exit status See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) #### [​](https://agentclientprotocol.com/protocol/schema#waitforterminalexitrequest) WaitForTerminalExitRequest Request to wait for a terminal command to exit. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-32) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-session-id-14) sessionId required The session ID for this request. [​](https://agentclientprotocol.com/protocol/schema#param-terminal-id-4) terminalId string required The ID of the terminal to wait for. #### [​](https://agentclientprotocol.com/protocol/schema#waitforterminalexitresponse) WaitForTerminalExitResponse Response containing the exit status of a terminal command. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-33) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-exit-code) exitCode integer | null The process exit code (may be null if terminated by signal). * Minimum: `0` [​](https://agentclientprotocol.com/protocol/schema#param-signal) signal string | null The signal that terminated the process (may be null if exited normally). [​](https://agentclientprotocol.com/protocol/schema#agentcapabilities) AgentCapabilities ------------------------------------------------------------------------------------------- Capabilities supported by the agent. Advertised during initialization to inform the client about available features and content types. See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-34) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-load-session) loadSession boolean Whether the agent supports `session/load`. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#param-mcp-capabilities) mcpCapabilities MCP capabilities supported by the agent. * Default: `{"http":false,"sse":false}` [​](https://agentclientprotocol.com/protocol/schema#param-prompt-capabilities) promptCapabilities Prompt capabilities supported by the agent. * Default: `{"audio":false,"embeddedContext":false,"image":false}` [​](https://agentclientprotocol.com/protocol/schema#param-session-capabilities) sessionCapabilities * Default: `{}` [​](https://agentclientprotocol.com/protocol/schema#annotations) Annotations ------------------------------------------------------------------------------- Optional annotations for the client. The client can use annotations to inform how objects are used or displayed **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-35) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-audience) audience [​](https://agentclientprotocol.com/protocol/schema#param-last-modified) lastModified string | null [​](https://agentclientprotocol.com/protocol/schema#param-priority) priority number | null [​](https://agentclientprotocol.com/protocol/schema#audiocontent) AudioContent --------------------------------------------------------------------------------- Audio provided to or from an LLM. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-36) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations) annotations [​](https://agentclientprotocol.com/protocol/schema#param-data) data string required [​](https://agentclientprotocol.com/protocol/schema#param-mime-type) mimeType string required [​](https://agentclientprotocol.com/protocol/schema#authmethod) AuthMethod ----------------------------------------------------------------------------- Describes an available authentication method. The `type` field acts as the discriminator in the serialized JSON form. When no `type` is present, the method is treated as `agent`. Agent handles authentication itself. This is the default when no `type` is specified. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-37) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-description) description string | null Optional description providing more details about this authentication method. [​](https://agentclientprotocol.com/protocol/schema#param-id) id string required Unique identifier for this authentication method. [​](https://agentclientprotocol.com/protocol/schema#param-name) name string required Human-readable name of the authentication method. [​](https://agentclientprotocol.com/protocol/schema#authmethodagent) AuthMethodAgent --------------------------------------------------------------------------------------- Agent handles authentication itself. This is the default authentication method type. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-38) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-description-1) description string | null Optional description providing more details about this authentication method. [​](https://agentclientprotocol.com/protocol/schema#param-id-1) id string required Unique identifier for this authentication method. [​](https://agentclientprotocol.com/protocol/schema#param-name-1) name string required Human-readable name of the authentication method. [​](https://agentclientprotocol.com/protocol/schema#availablecommand) AvailableCommand ----------------------------------------------------------------------------------------- Information about a command. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-39) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-description-2) description string required Human-readable description of what the command does. [​](https://agentclientprotocol.com/protocol/schema#param-input) input Input for the command if required [​](https://agentclientprotocol.com/protocol/schema#param-name-2) name string required Command name (e.g., `create_plan`, `research_codebase`). [​](https://agentclientprotocol.com/protocol/schema#availablecommandinput) AvailableCommandInput --------------------------------------------------------------------------------------------------- The input specification for a command. All text that was typed after the command name is provided as input. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-40) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-hint) hint string required A hint to display when the input hasn’t been provided yet [​](https://agentclientprotocol.com/protocol/schema#availablecommandsupdate) AvailableCommandsUpdate ------------------------------------------------------------------------------------------------------- Available commands are ready or have changed **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-41) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-available-commands) availableCommands required Commands the agent can execute [​](https://agentclientprotocol.com/protocol/schema#blobresourcecontents) BlobResourceContents ------------------------------------------------------------------------------------------------- Binary resource contents. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-42) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-blob) blob string required [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-1) mimeType string | null [​](https://agentclientprotocol.com/protocol/schema#param-uri) uri string required [​](https://agentclientprotocol.com/protocol/schema#clientcapabilities) ClientCapabilities --------------------------------------------------------------------------------------------- Capabilities supported by the client. Advertised during initialization to inform the agent about available features and methods. See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-43) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-fs) fs File system capabilities supported by the client. Determines which file operations the agent can request. * Default: `{"readTextFile":false,"writeTextFile":false}` [​](https://agentclientprotocol.com/protocol/schema#param-terminal) terminal boolean Whether the Client support all `terminal/*` methods. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#configoptionupdate) ConfigOptionUpdate --------------------------------------------------------------------------------------------- Session configuration options have been updated. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-44) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-config-options-3) configOptions required The full set of configuration options and their current values. [​](https://agentclientprotocol.com/protocol/schema#content) Content ----------------------------------------------------------------------- Standard content block (text, images, resources). **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-45) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-2) content required The actual content block. [​](https://agentclientprotocol.com/protocol/schema#contentblock) ContentBlock --------------------------------------------------------------------------------- Content blocks represent displayable information in the Agent Client Protocol. They provide a structured way to handle various types of user-facing content—whether it’s text from language models, images for analysis, or embedded resources for context. Content blocks appear in: * User prompts sent via `session/prompt` * Language model output streamed through `session/update` notifications * Progress updates and results from tool calls This structure is compatible with the Model Context Protocol (MCP), enabling agents to seamlessly forward content from MCP tool outputs without transformation. See protocol docs: [Content](https://agentclientprotocol.com/protocol/content) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-text) text object Text content. May be plain text or formatted with Markdown.All agents MUST support text content blocks in prompts. Clients SHOULD render this text as Markdown. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-46) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-1) annotations [​](https://agentclientprotocol.com/protocol/schema#param-text-1) text string required [​](https://agentclientprotocol.com/protocol/schema#param-type) type string required The discriminator value. Must be `"text"`. [​](https://agentclientprotocol.com/protocol/schema#param-image) image object Images for visual context or analysis.Requires the `image` prompt capability when included in prompts. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-47) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-2) annotations [​](https://agentclientprotocol.com/protocol/schema#param-data-1) data string required [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-2) mimeType string required [​](https://agentclientprotocol.com/protocol/schema#param-type-1) type string required The discriminator value. Must be `"image"`. [​](https://agentclientprotocol.com/protocol/schema#param-uri-1) uri string | null [​](https://agentclientprotocol.com/protocol/schema#param-audio) audio object Audio data for transcription or analysis.Requires the `audio` prompt capability when included in prompts. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-48) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-3) annotations [​](https://agentclientprotocol.com/protocol/schema#param-data-2) data string required [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-3) mimeType string required [​](https://agentclientprotocol.com/protocol/schema#param-type-2) type string required The discriminator value. Must be `"audio"`. [​](https://agentclientprotocol.com/protocol/schema#param-resource-link) resource\_link object References to resources that the agent can access.All agents MUST support resource links in prompts. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-49) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-4) annotations [​](https://agentclientprotocol.com/protocol/schema#param-description-3) description string | null [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-4) mimeType string | null [​](https://agentclientprotocol.com/protocol/schema#param-name-3) name string required [​](https://agentclientprotocol.com/protocol/schema#param-size) size integer | null [​](https://agentclientprotocol.com/protocol/schema#param-title) title string | null [​](https://agentclientprotocol.com/protocol/schema#param-type-3) type string required The discriminator value. Must be `"resource_link"`. [​](https://agentclientprotocol.com/protocol/schema#param-uri-2) uri string required [​](https://agentclientprotocol.com/protocol/schema#param-resource) resource object Complete resource contents embedded directly in the message.Preferred for including context as it avoids extra round-trips.Requires the `embeddedContext` prompt capability when included in prompts. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-50) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-5) annotations [​](https://agentclientprotocol.com/protocol/schema#param-resource-1) resource required [​](https://agentclientprotocol.com/protocol/schema#param-type-4) type string required The discriminator value. Must be `"resource"`. [​](https://agentclientprotocol.com/protocol/schema#contentchunk) ContentChunk --------------------------------------------------------------------------------- A streamed item of content **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-51) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-3) content required A single item of content [​](https://agentclientprotocol.com/protocol/schema#currentmodeupdate) CurrentModeUpdate ------------------------------------------------------------------------------------------- The current mode of the session has changed See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-52) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-current-mode-id) currentModeId required The ID of the current mode [​](https://agentclientprotocol.com/protocol/schema#diff) Diff ----------------------------------------------------------------- A diff representing file modifications. Shows changes to files in a format suitable for display in the client UI. See protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-53) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-new-text) newText string required The new content after modification. [​](https://agentclientprotocol.com/protocol/schema#param-old-text) oldText string | null The original content (None for new files). [​](https://agentclientprotocol.com/protocol/schema#param-path-2) path string required The file path being modified. [​](https://agentclientprotocol.com/protocol/schema#embeddedresource) EmbeddedResource ----------------------------------------------------------------------------------------- The contents of a resource, embedded into a prompt or tool call result. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-54) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-6) annotations [​](https://agentclientprotocol.com/protocol/schema#param-resource-2) resource required [​](https://agentclientprotocol.com/protocol/schema#embeddedresourceresource) EmbeddedResourceResource --------------------------------------------------------------------------------------------------------- Resource content that can be embedded in a message. **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-text-resource-contents) TextResourceContents Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-55) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-5) mimeType string | null [​](https://agentclientprotocol.com/protocol/schema#param-text-2) text string required [​](https://agentclientprotocol.com/protocol/schema#param-uri-3) uri string required [​](https://agentclientprotocol.com/protocol/schema#param-blob-resource-contents) BlobResourceContents Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-56) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-blob-1) blob string required [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-6) mimeType string | null [​](https://agentclientprotocol.com/protocol/schema#param-uri-4) uri string required [​](https://agentclientprotocol.com/protocol/schema#envvariable) EnvVariable ------------------------------------------------------------------------------- An environment variable to set when launching an MCP server. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-57) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-name-4) name string required The name of the environment variable. [​](https://agentclientprotocol.com/protocol/schema#param-value-1) value string required The value to set for the environment variable. [​](https://agentclientprotocol.com/protocol/schema#error) Error ------------------------------------------------------------------- JSON-RPC error object. Represents an error that occurred during method execution, following the JSON-RPC 2.0 error object specification with optional additional data. See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-code) code required A number indicating the error type that occurred. This must be an integer as defined in the JSON-RPC specification. [​](https://agentclientprotocol.com/protocol/schema#param-data-3) data object Optional primitive or structured value that contains additional information about the error. This may include debugging information or context-specific details. [​](https://agentclientprotocol.com/protocol/schema#param-message) message string required A string providing a short description of the error. The message should be limited to a concise single sentence. [​](https://agentclientprotocol.com/protocol/schema#errorcode) ErrorCode --------------------------------------------------------------------------- Predefined error codes for common JSON-RPC and ACP-specific errors. These codes follow the JSON-RPC 2.0 specification for standard errors and use the reserved range (-32000 to -32099) for protocol-specific errors. **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-32700) \-32700 int32 **Parse error**: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. [​](https://agentclientprotocol.com/protocol/schema#param-32600) \-32600 int32 **Invalid request**: The JSON sent is not a valid Request object. [​](https://agentclientprotocol.com/protocol/schema#param-32601) \-32601 int32 **Method not found**: The method does not exist or is not available. [​](https://agentclientprotocol.com/protocol/schema#param-32602) \-32602 int32 **Invalid params**: Invalid method parameter(s). [​](https://agentclientprotocol.com/protocol/schema#param-32603) \-32603 int32 **Internal error**: Internal JSON-RPC error. Reserved for implementation-defined server errors. [​](https://agentclientprotocol.com/protocol/schema#param-32000) \-32000 int32 **Authentication required**: Authentication is required before this operation can be performed. [​](https://agentclientprotocol.com/protocol/schema#param-32002) \-32002 int32 **Resource not found**: A given resource, such as a file, was not found. [​](https://agentclientprotocol.com/protocol/schema#param-other) Other int32 Other undefined error code. [​](https://agentclientprotocol.com/protocol/schema#extnotification) ExtNotification --------------------------------------------------------------------------------------- Allows the Agent to send an arbitrary notification that is not part of the ACP spec. Extension notifications provide a way to send one-way messages for custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#extrequest) ExtRequest ----------------------------------------------------------------------------- Allows for sending an arbitrary request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#extresponse) ExtResponse ------------------------------------------------------------------------------- Allows for sending an arbitrary response to an `ExtRequest` that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#filesystemcapabilities) FileSystemCapabilities ----------------------------------------------------------------------------------------------------- File system capabilities that a client may support. See protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-58) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-read-text-file) readTextFile boolean Whether the Client supports `fs/read_text_file` requests. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#param-write-text-file) writeTextFile boolean Whether the Client supports `fs/write_text_file` requests. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#httpheader) HttpHeader ----------------------------------------------------------------------------- An HTTP header to set when making requests to the MCP server. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-59) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-name-5) name string required The name of the HTTP header. [​](https://agentclientprotocol.com/protocol/schema#param-value-2) value string required The value to set for the HTTP header. [​](https://agentclientprotocol.com/protocol/schema#imagecontent) ImageContent --------------------------------------------------------------------------------- An image provided to or from an LLM. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-60) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-7) annotations [​](https://agentclientprotocol.com/protocol/schema#param-data-4) data string required [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-7) mimeType string required [​](https://agentclientprotocol.com/protocol/schema#param-uri-5) uri string | null [​](https://agentclientprotocol.com/protocol/schema#implementation) Implementation ------------------------------------------------------------------------------------- Metadata about the implementation of the client or agent. Describes the name and version of an MCP implementation, with an optional title for UI representation. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-61) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-name-6) name string required Intended for programmatic or logical use, but can be used as a display name fallback if title isn’t present. [​](https://agentclientprotocol.com/protocol/schema#param-title-1) title string | null Intended for UI and end-user contexts — optimized to be human-readable and easily understood.If not provided, the name should be used for display. [​](https://agentclientprotocol.com/protocol/schema#param-version) version string required Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. (e.g. “1.0.0”). [​](https://agentclientprotocol.com/protocol/schema#mcpcapabilities) McpCapabilities --------------------------------------------------------------------------------------- MCP capabilities supported by the agent **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-62) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-http) http boolean Agent supports `McpServer::Http`. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#param-sse) sse boolean Agent supports `McpServer::Sse`. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#mcpserver) McpServer --------------------------------------------------------------------------- Configuration for connecting to an MCP (Model Context Protocol) server. MCP servers provide tools and context that the agent can use when processing prompts. See protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-http-1) http object HTTP transport configurationOnly available when the Agent capabilities indicate `mcp_capabilities.http` is `true`. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-63) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-headers) headers required HTTP headers to set when making requests to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-name-7) name string required Human-readable name identifying this MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-type-5) type string required The discriminator value. Must be `"http"`. [​](https://agentclientprotocol.com/protocol/schema#param-url) url string required URL to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-sse-1) sse object SSE transport configurationOnly available when the Agent capabilities indicate `mcp_capabilities.sse` is `true`. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-64) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-headers-1) headers required HTTP headers to set when making requests to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-name-8) name string required Human-readable name identifying this MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-type-6) type string required The discriminator value. Must be `"sse"`. [​](https://agentclientprotocol.com/protocol/schema#param-url-1) url string required URL to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-stdio) stdio Stdio transport configurationAll Agents MUST support this transport. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-65) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-args-1) args required Command-line arguments to pass to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-command-1) command string required Path to the MCP server executable. [​](https://agentclientprotocol.com/protocol/schema#param-env-1) env required Environment variables to set when launching the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-name-9) name string required Human-readable name identifying this MCP server. [​](https://agentclientprotocol.com/protocol/schema#mcpserverhttp) McpServerHttp ----------------------------------------------------------------------------------- HTTP transport configuration for MCP. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-66) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-headers-2) headers required HTTP headers to set when making requests to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-name-10) name string required Human-readable name identifying this MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-url-2) url string required URL to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#mcpserversse) McpServerSse --------------------------------------------------------------------------------- SSE transport configuration for MCP. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-67) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-headers-3) headers required HTTP headers to set when making requests to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-name-11) name string required Human-readable name identifying this MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-url-3) url string required URL to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#mcpserverstdio) McpServerStdio ------------------------------------------------------------------------------------- Stdio transport configuration for MCP. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-68) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-args-2) args required Command-line arguments to pass to the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-command-2) command string required Path to the MCP server executable. [​](https://agentclientprotocol.com/protocol/schema#param-env-2) env required Environment variables to set when launching the MCP server. [​](https://agentclientprotocol.com/protocol/schema#param-name-12) name string required Human-readable name identifying this MCP server. [​](https://agentclientprotocol.com/protocol/schema#permissionoption) PermissionOption ----------------------------------------------------------------------------------------- An option presented to the user when requesting permission. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-69) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-kind) kind required Hint about the nature of this permission option. [​](https://agentclientprotocol.com/protocol/schema#param-name-13) name string required Human-readable label to display to the user. [​](https://agentclientprotocol.com/protocol/schema#param-option-id) optionId required Unique identifier for this permission option. [​](https://agentclientprotocol.com/protocol/schema#permissionoptionid) PermissionOptionId --------------------------------------------------------------------------------------------- Unique identifier for a permission option. **Type:** `string` [​](https://agentclientprotocol.com/protocol/schema#permissionoptionkind) PermissionOptionKind ------------------------------------------------------------------------------------------------- The type of permission option being presented to the user. Helps clients choose appropriate icons and UI treatment. **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-allow-once) allow\_once string Allow this operation only this time. [​](https://agentclientprotocol.com/protocol/schema#param-allow-always) allow\_always string Allow this operation and remember the choice. [​](https://agentclientprotocol.com/protocol/schema#param-reject-once) reject\_once string Reject this operation only this time. [​](https://agentclientprotocol.com/protocol/schema#param-reject-always) reject\_always string Reject this operation and remember the choice. [​](https://agentclientprotocol.com/protocol/schema#plan) Plan ----------------------------------------------------------------- An execution plan for accomplishing complex tasks. Plans consist of multiple entries representing individual tasks or goals. Agents report plans to clients to provide visibility into their execution strategy. Plans can evolve during execution as the agent discovers new requirements or completes tasks. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-70) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-entries) entries required The list of tasks to be accomplished.When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update. [​](https://agentclientprotocol.com/protocol/schema#planentry) PlanEntry --------------------------------------------------------------------------- A single entry in the execution plan. Represents a task or goal that the assistant intends to accomplish as part of fulfilling the user’s request. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-71) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-4) content string required Human-readable description of what this task aims to accomplish. [​](https://agentclientprotocol.com/protocol/schema#param-priority-1) priority required The relative importance of this task. Used to indicate which tasks are most critical to the overall goal. [​](https://agentclientprotocol.com/protocol/schema#param-status) status required Current execution status of this task. [​](https://agentclientprotocol.com/protocol/schema#planentrypriority) PlanEntryPriority ------------------------------------------------------------------------------------------- Priority levels for plan entries. Used to indicate the relative importance or urgency of different tasks in the execution plan. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-high) high string High priority task - critical to the overall goal. [​](https://agentclientprotocol.com/protocol/schema#param-medium) medium string Medium priority task - important but not critical. [​](https://agentclientprotocol.com/protocol/schema#param-low) low string Low priority task - nice to have but not essential. [​](https://agentclientprotocol.com/protocol/schema#planentrystatus) PlanEntryStatus --------------------------------------------------------------------------------------- Status of a plan entry in the execution flow. Tracks the lifecycle of each task from planning through completion. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-pending) pending string The task has not started yet. [​](https://agentclientprotocol.com/protocol/schema#param-in-progress) in\_progress string The task is currently being worked on. [​](https://agentclientprotocol.com/protocol/schema#param-completed) completed string The task has been successfully completed. [​](https://agentclientprotocol.com/protocol/schema#promptcapabilities) PromptCapabilities --------------------------------------------------------------------------------------------- Prompt capabilities supported by the agent in `session/prompt` requests. Baseline agent functionality requires support for `ContentBlock::Text` and `ContentBlock::ResourceLink` in prompt requests. Other variants must be explicitly opted in to. Capabilities for different types of content in prompt requests. Indicates which content types beyond the baseline (text and resource links) the agent can process. See protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-72) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-audio-1) audio boolean Agent supports `ContentBlock::Audio`. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#param-embedded-context) embeddedContext boolean Agent supports embedded context in `session/prompt` requests.When enabled, the Client is allowed to include `ContentBlock::Resource` in prompt requests for pieces of context that are referenced in the message. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#param-image-1) image boolean Agent supports `ContentBlock::Image`. * Default: `false` [​](https://agentclientprotocol.com/protocol/schema#protocolversion) ProtocolVersion --------------------------------------------------------------------------------------- Protocol version identifier. This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities. **Type:** `integer (uint16)` | Constraint | Value | | --- | --- | | Minimum | `0` | | Maximum | `65535` | [​](https://agentclientprotocol.com/protocol/schema#requestid) RequestId --------------------------------------------------------------------------- JSON RPC Request Id An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null \[1\] and Numbers SHOULD NOT contain fractional parts \[2\] The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects. \[1\] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling. \[2\] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions. **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#requestpermissionoutcome) RequestPermissionOutcome --------------------------------------------------------------------------------------------------------- The outcome of a permission request. **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-cancelled) cancelled object The prompt turn was cancelled before the user responded.When a client sends a `session/cancel` notification to cancel an ongoing prompt turn, it MUST respond to all pending `session/request_permission` requests with this `Cancelled` outcome.See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-outcome-1) outcome string required The discriminator value. Must be `"cancelled"`. [​](https://agentclientprotocol.com/protocol/schema#param-selected) selected object The user selected one of the provided options. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-73) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-option-id-1) optionId required The ID of the option the user selected. [​](https://agentclientprotocol.com/protocol/schema#param-outcome-2) outcome string required The discriminator value. Must be `"selected"`. [​](https://agentclientprotocol.com/protocol/schema#resourcelink) ResourceLink --------------------------------------------------------------------------------- A resource that the server is capable of reading, included in a prompt or tool call result. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-74) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-8) annotations [​](https://agentclientprotocol.com/protocol/schema#param-description-4) description string | null [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-8) mimeType string | null [​](https://agentclientprotocol.com/protocol/schema#param-name-14) name string required [​](https://agentclientprotocol.com/protocol/schema#param-size-1) size integer | null [​](https://agentclientprotocol.com/protocol/schema#param-title-2) title string | null [​](https://agentclientprotocol.com/protocol/schema#param-uri-6) uri string required [​](https://agentclientprotocol.com/protocol/schema#role) Role ----------------------------------------------------------------- The sender or recipient of messages and data in a conversation. **Type:** Enumeration | Value | | --- | | `"assistant"` | | `"user"` | [​](https://agentclientprotocol.com/protocol/schema#selectedpermissionoutcome) SelectedPermissionOutcome ----------------------------------------------------------------------------------------------------------- The user selected one of the provided options. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-75) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-option-id-2) optionId required The ID of the option the user selected. [​](https://agentclientprotocol.com/protocol/schema#sessioncapabilities) SessionCapabilities ----------------------------------------------------------------------------------------------- Session capabilities supported by the agent. As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`. Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities. Note: `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol. See protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-76) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-list) list Whether the agent supports `session/list`. [​](https://agentclientprotocol.com/protocol/schema#sessionconfiggroupid) SessionConfigGroupId ------------------------------------------------------------------------------------------------- Unique identifier for a session configuration option value group. **Type:** `string` [​](https://agentclientprotocol.com/protocol/schema#sessionconfigid) SessionConfigId --------------------------------------------------------------------------------------- Unique identifier for a session configuration option. **Type:** `string` [​](https://agentclientprotocol.com/protocol/schema#sessionconfigoption) SessionConfigOption ----------------------------------------------------------------------------------------------- A session configuration option selector and its current state. Single-value selector (dropdown). **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-current-value) currentValue required The currently selected value. [​](https://agentclientprotocol.com/protocol/schema#param-options-1) options required The set of selectable options. [​](https://agentclientprotocol.com/protocol/schema#param-type-7) type string required The discriminator value. Must be `"select"`. [​](https://agentclientprotocol.com/protocol/schema#sessionconfigoptioncategory) SessionConfigOptionCategory --------------------------------------------------------------------------------------------------------------- Semantic category for a session configuration option. This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons, placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use, like other ACP extension methods. Category names that do not begin with `_` are reserved for the ACP spec. **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-mode) mode string Session mode selector. [​](https://agentclientprotocol.com/protocol/schema#param-model) model string Model selector. [​](https://agentclientprotocol.com/protocol/schema#param-thought-level) thought\_level string Thought/reasoning level selector. [​](https://agentclientprotocol.com/protocol/schema#param-other) other string Unknown / uncategorized selector. [​](https://agentclientprotocol.com/protocol/schema#sessionconfigselect) SessionConfigSelect ----------------------------------------------------------------------------------------------- A single-value selector (dropdown) session configuration option payload. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-current-value-1) currentValue required The currently selected value. [​](https://agentclientprotocol.com/protocol/schema#param-options-2) options required The set of selectable options. [​](https://agentclientprotocol.com/protocol/schema#sessionconfigselectgroup) SessionConfigSelectGroup --------------------------------------------------------------------------------------------------------- A group of possible values for a session configuration option. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-77) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-group) group required Unique identifier for this group. [​](https://agentclientprotocol.com/protocol/schema#param-name-15) name string required Human-readable label for this group. [​](https://agentclientprotocol.com/protocol/schema#param-options-3) options required The set of option values in this group. [​](https://agentclientprotocol.com/protocol/schema#sessionconfigselectoption) SessionConfigSelectOption ----------------------------------------------------------------------------------------------------------- A possible value for a session configuration option. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-78) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-description-5) description string | null Optional description for this option value. [​](https://agentclientprotocol.com/protocol/schema#param-name-16) name string required Human-readable label for this option value. [​](https://agentclientprotocol.com/protocol/schema#param-value-3) value required Unique identifier for this option value. [​](https://agentclientprotocol.com/protocol/schema#sessionconfigselectoptions) SessionConfigSelectOptions ------------------------------------------------------------------------------------------------------------- Possible values for a session configuration option. **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-ungrouped) Ungrouped array A flat list of options with no grouping. [​](https://agentclientprotocol.com/protocol/schema#param-grouped) Grouped array A list of options grouped under headers. [​](https://agentclientprotocol.com/protocol/schema#sessionconfigvalueid) SessionConfigValueId ------------------------------------------------------------------------------------------------- Unique identifier for a session configuration option value. **Type:** `string` [​](https://agentclientprotocol.com/protocol/schema#sessionid) SessionId --------------------------------------------------------------------------- A unique identifier for a conversation session between a client and agent. Sessions maintain their own context, conversation history, and state, allowing multiple independent interactions with the same agent. See protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) **Type:** `string` [​](https://agentclientprotocol.com/protocol/schema#sessioninfo) SessionInfo ------------------------------------------------------------------------------- Information about a session returned by session/list **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-79) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-cwd-4) cwd string required The working directory for this session. Must be an absolute path. [​](https://agentclientprotocol.com/protocol/schema#param-session-id-15) sessionId required Unique identifier for the session [​](https://agentclientprotocol.com/protocol/schema#param-title-3) title string | null Human-readable title for the session [​](https://agentclientprotocol.com/protocol/schema#param-updated-at) updatedAt string | null ISO 8601 timestamp of last activity [​](https://agentclientprotocol.com/protocol/schema#sessioninfoupdate) SessionInfoUpdate ------------------------------------------------------------------------------------------- Update to session metadata. All fields are optional to support partial updates. Agents send this notification to update session information like title or custom metadata. This allows clients to display dynamic session names and track session state changes. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-80) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-title-4) title string | null Human-readable title for the session. Set to null to clear. [​](https://agentclientprotocol.com/protocol/schema#param-updated-at-1) updatedAt string | null ISO 8601 timestamp of last activity. Set to null to clear. [​](https://agentclientprotocol.com/protocol/schema#sessionlistcapabilities) SessionListCapabilities ------------------------------------------------------------------------------------------------------- Capabilities for the `session/list` method. By supplying `\{\}` it means that the agent supports listing of sessions. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-81) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#sessionmode) SessionMode ------------------------------------------------------------------------------- A mode the agent can operate in. See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-82) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-description-6) description string | null [​](https://agentclientprotocol.com/protocol/schema#param-id-2) id required [​](https://agentclientprotocol.com/protocol/schema#param-name-17) name string required [​](https://agentclientprotocol.com/protocol/schema#sessionmodeid) SessionModeId ----------------------------------------------------------------------------------- Unique identifier for a Session Mode. **Type:** `string` [​](https://agentclientprotocol.com/protocol/schema#sessionmodestate) SessionModeState ----------------------------------------------------------------------------------------- The set of modes and the one currently active. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-83) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-available-modes) availableModes required The set of modes that the Agent can operate in [​](https://agentclientprotocol.com/protocol/schema#param-current-mode-id-1) currentModeId required The current mode the Agent is in. [​](https://agentclientprotocol.com/protocol/schema#sessionupdate) SessionUpdate ----------------------------------------------------------------------------------- Different types of updates that can be sent during session processing. These updates provide real-time feedback about the agent’s progress. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-user-message-chunk) user\_message\_chunk object A chunk of the user’s message being streamed. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-84) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-5) content required A single item of content [​](https://agentclientprotocol.com/protocol/schema#param-session-update) sessionUpdate string required The discriminator value. Must be `"user_message_chunk"`. [​](https://agentclientprotocol.com/protocol/schema#param-agent-message-chunk) agent\_message\_chunk object A chunk of the agent’s response being streamed. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-85) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-6) content required A single item of content [​](https://agentclientprotocol.com/protocol/schema#param-session-update-1) sessionUpdate string required The discriminator value. Must be `"agent_message_chunk"`. [​](https://agentclientprotocol.com/protocol/schema#param-agent-thought-chunk) agent\_thought\_chunk object A chunk of the agent’s internal reasoning being streamed. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-86) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-7) content required A single item of content [​](https://agentclientprotocol.com/protocol/schema#param-session-update-2) sessionUpdate string required The discriminator value. Must be `"agent_thought_chunk"`. [​](https://agentclientprotocol.com/protocol/schema#param-tool-call) tool\_call object Notification that a new tool call has been initiated. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-87) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-8) content Content produced by the tool call. [​](https://agentclientprotocol.com/protocol/schema#param-kind-1) kind The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. [​](https://agentclientprotocol.com/protocol/schema#param-locations) locations File locations affected by this tool call. Enables “follow-along” features in clients. [​](https://agentclientprotocol.com/protocol/schema#param-raw-input) rawInput object Raw input parameters sent to the tool. [​](https://agentclientprotocol.com/protocol/schema#param-raw-output) rawOutput object Raw output returned by the tool. [​](https://agentclientprotocol.com/protocol/schema#param-session-update-3) sessionUpdate string required The discriminator value. Must be `"tool_call"`. [​](https://agentclientprotocol.com/protocol/schema#param-status-1) status Current execution status of the tool call. [​](https://agentclientprotocol.com/protocol/schema#param-title-5) title string required Human-readable title describing what the tool is doing. [​](https://agentclientprotocol.com/protocol/schema#param-tool-call-id) toolCallId required Unique identifier for this tool call within the session. [​](https://agentclientprotocol.com/protocol/schema#param-tool-call-update) tool\_call\_update object Update on the status or results of a tool call. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-88) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-9) content Replace the content collection. [​](https://agentclientprotocol.com/protocol/schema#param-kind-2) kind Update the tool kind. [​](https://agentclientprotocol.com/protocol/schema#param-locations-1) locations Replace the locations collection. [​](https://agentclientprotocol.com/protocol/schema#param-raw-input-1) rawInput object Update the raw input. [​](https://agentclientprotocol.com/protocol/schema#param-raw-output-1) rawOutput object Update the raw output. [​](https://agentclientprotocol.com/protocol/schema#param-session-update-4) sessionUpdate string required The discriminator value. Must be `"tool_call_update"`. [​](https://agentclientprotocol.com/protocol/schema#param-status-2) status Update the execution status. [​](https://agentclientprotocol.com/protocol/schema#param-title-6) title string | null Update the human-readable title. [​](https://agentclientprotocol.com/protocol/schema#param-tool-call-id-1) toolCallId required The ID of the tool call being updated. [​](https://agentclientprotocol.com/protocol/schema#param-plan) plan object The agent’s execution plan for complex tasks. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan) Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-89) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-entries-1) entries required The list of tasks to be accomplished.When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update. [​](https://agentclientprotocol.com/protocol/schema#param-session-update-5) sessionUpdate string required The discriminator value. Must be `"plan"`. [​](https://agentclientprotocol.com/protocol/schema#param-available-commands-update) available\_commands\_update object Available commands are ready or have changed Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-90) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-available-commands-1) availableCommands required Commands the agent can execute [​](https://agentclientprotocol.com/protocol/schema#param-session-update-6) sessionUpdate string required The discriminator value. Must be `"available_commands_update"`. [​](https://agentclientprotocol.com/protocol/schema#param-current-mode-update) current\_mode\_update object The current mode of the session has changedSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-91) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-current-mode-id-2) currentModeId required The ID of the current mode [​](https://agentclientprotocol.com/protocol/schema#param-session-update-7) sessionUpdate string required The discriminator value. Must be `"current_mode_update"`. [​](https://agentclientprotocol.com/protocol/schema#param-config-option-update) config\_option\_update object Session configuration options have been updated. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-92) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-config-options-4) configOptions required The full set of configuration options and their current values. [​](https://agentclientprotocol.com/protocol/schema#param-session-update-8) sessionUpdate string required The discriminator value. Must be `"config_option_update"`. [​](https://agentclientprotocol.com/protocol/schema#param-session-info-update) session\_info\_update object Session metadata has been updated (title, timestamps, custom metadata) Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-93) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-session-update-9) sessionUpdate string required The discriminator value. Must be `"session_info_update"`. [​](https://agentclientprotocol.com/protocol/schema#param-title-7) title string | null Human-readable title for the session. Set to null to clear. [​](https://agentclientprotocol.com/protocol/schema#param-updated-at-2) updatedAt string | null ISO 8601 timestamp of last activity. Set to null to clear. [​](https://agentclientprotocol.com/protocol/schema#stopreason) StopReason ----------------------------------------------------------------------------- Reasons why an agent stops processing a prompt turn. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-end-turn) end\_turn string The turn ended successfully. [​](https://agentclientprotocol.com/protocol/schema#param-max-tokens) max\_tokens string The turn ended because the agent reached the maximum number of tokens. [​](https://agentclientprotocol.com/protocol/schema#param-max-turn-requests) max\_turn\_requests string The turn ended because the agent reached the maximum number of allowed agent requests between user turns. [​](https://agentclientprotocol.com/protocol/schema#param-refusal) refusal string The turn ended because the agent refused to continue. The user prompt and everything that comes after it won’t be included in the next prompt, so this should be reflected in the UI. [​](https://agentclientprotocol.com/protocol/schema#param-cancelled-1) cancelled string The turn was cancelled by the client via `session/cancel`.This stop reason MUST be returned when the client sends a `session/cancel` notification, even if the cancellation causes exceptions in underlying operations. Agents should catch these exceptions and return this semantically meaningful response to confirm successful cancellation. [​](https://agentclientprotocol.com/protocol/schema#terminal) Terminal ------------------------------------------------------------------------- Embed a terminal created with `terminal/create` by its id. The terminal must be added before calling `terminal/release`. See protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-94) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-terminal-id-5) terminalId string required [​](https://agentclientprotocol.com/protocol/schema#terminalexitstatus) TerminalExitStatus --------------------------------------------------------------------------------------------- Exit status of a terminal command. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-95) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-exit-code-1) exitCode integer | null The process exit code (may be null if terminated by signal). * Minimum: `0` [​](https://agentclientprotocol.com/protocol/schema#param-signal-1) signal string | null The signal that terminated the process (may be null if exited normally). [​](https://agentclientprotocol.com/protocol/schema#textcontent) TextContent ------------------------------------------------------------------------------- Text provided to or from an LLM. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-96) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-annotations-9) annotations [​](https://agentclientprotocol.com/protocol/schema#param-text-3) text string required [​](https://agentclientprotocol.com/protocol/schema#textresourcecontents) TextResourceContents ------------------------------------------------------------------------------------------------- Text-based resource contents. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-97) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-mime-type-9) mimeType string | null [​](https://agentclientprotocol.com/protocol/schema#param-text-4) text string required [​](https://agentclientprotocol.com/protocol/schema#param-uri-7) uri string required [​](https://agentclientprotocol.com/protocol/schema#toolcall) ToolCall ------------------------------------------------------------------------- Represents a tool call that the language model has requested. Tool calls are actions that the agent executes on behalf of the language model, such as reading files, executing code, or fetching data from external sources. See protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/tool-calls) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-98) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-10) content Content produced by the tool call. [​](https://agentclientprotocol.com/protocol/schema#param-kind-3) kind The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. [​](https://agentclientprotocol.com/protocol/schema#param-locations-2) locations File locations affected by this tool call. Enables “follow-along” features in clients. [​](https://agentclientprotocol.com/protocol/schema#param-raw-input-2) rawInput object Raw input parameters sent to the tool. [​](https://agentclientprotocol.com/protocol/schema#param-raw-output-2) rawOutput object Raw output returned by the tool. [​](https://agentclientprotocol.com/protocol/schema#param-status-3) status Current execution status of the tool call. [​](https://agentclientprotocol.com/protocol/schema#param-title-8) title string required Human-readable title describing what the tool is doing. [​](https://agentclientprotocol.com/protocol/schema#param-tool-call-id-2) toolCallId required Unique identifier for this tool call within the session. [​](https://agentclientprotocol.com/protocol/schema#toolcallcontent) ToolCallContent --------------------------------------------------------------------------------------- Content produced by a tool call. Tool calls can produce different types of content including standard content blocks (text, images) or file diffs. See protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-content-11) content object Standard content block (text, images, resources). Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-99) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-12) content required The actual content block. [​](https://agentclientprotocol.com/protocol/schema#param-type-8) type string required The discriminator value. Must be `"content"`. [​](https://agentclientprotocol.com/protocol/schema#param-diff) diff object File modification shown as a diff. Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-100) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-new-text-1) newText string required The new content after modification. [​](https://agentclientprotocol.com/protocol/schema#param-old-text-1) oldText string | null The original content (None for new files). [​](https://agentclientprotocol.com/protocol/schema#param-path-3) path string required The file path being modified. [​](https://agentclientprotocol.com/protocol/schema#param-type-9) type string required The discriminator value. Must be `"diff"`. [​](https://agentclientprotocol.com/protocol/schema#param-terminal-1) terminal object Embed a terminal created with `terminal/create` by its id.The terminal must be added before calling `terminal/release`.See protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals) Show Properties [​](https://agentclientprotocol.com/protocol/schema#param-meta-101) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-terminal-id-6) terminalId string required [​](https://agentclientprotocol.com/protocol/schema#param-type-10) type string required The discriminator value. Must be `"terminal"`. [​](https://agentclientprotocol.com/protocol/schema#toolcallid) ToolCallId ----------------------------------------------------------------------------- Unique identifier for a tool call within a session. **Type:** `string` [​](https://agentclientprotocol.com/protocol/schema#toolcalllocation) ToolCallLocation ----------------------------------------------------------------------------------------- A file location being accessed or modified by a tool. Enables clients to implement “follow-along” features that track which files the agent is working with in real-time. See protocol docs: [Following the Agent](https://agentclientprotocol.com/protocol/tool-calls#following-the-agent) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-102) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-line-1) line integer | null Optional line number within the file. * Minimum: `0` [​](https://agentclientprotocol.com/protocol/schema#param-path-4) path string required The file path being accessed or modified. [​](https://agentclientprotocol.com/protocol/schema#toolcallstatus) ToolCallStatus ------------------------------------------------------------------------------------- Execution status of a tool call. Tool calls progress through different statuses during their lifecycle. See protocol docs: [Status](https://agentclientprotocol.com/protocol/tool-calls#status) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-pending-1) pending string The tool call hasn’t started running yet because the input is either streaming or we’re awaiting approval. [​](https://agentclientprotocol.com/protocol/schema#param-in-progress-1) in\_progress string The tool call is currently running. [​](https://agentclientprotocol.com/protocol/schema#param-completed-1) completed string The tool call completed successfully. [​](https://agentclientprotocol.com/protocol/schema#param-failed) failed string The tool call failed with an error. [​](https://agentclientprotocol.com/protocol/schema#toolcallupdate) ToolCallUpdate ------------------------------------------------------------------------------------- An update to an existing tool call. Used to report progress and results as tools execute. All fields except the tool call ID are optional - only changed fields need to be included. See protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating) **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-103) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-content-13) content Replace the content collection. [​](https://agentclientprotocol.com/protocol/schema#param-kind-4) kind Update the tool kind. [​](https://agentclientprotocol.com/protocol/schema#param-locations-3) locations Replace the locations collection. [​](https://agentclientprotocol.com/protocol/schema#param-raw-input-3) rawInput object Update the raw input. [​](https://agentclientprotocol.com/protocol/schema#param-raw-output-3) rawOutput object Update the raw output. [​](https://agentclientprotocol.com/protocol/schema#param-status-4) status Update the execution status. [​](https://agentclientprotocol.com/protocol/schema#param-title-9) title string | null Update the human-readable title. [​](https://agentclientprotocol.com/protocol/schema#param-tool-call-id-3) toolCallId required The ID of the tool call being updated. [​](https://agentclientprotocol.com/protocol/schema#toolkind) ToolKind ------------------------------------------------------------------------- Categories of tools that can be invoked. Tool kinds help clients choose appropriate icons and optimize how they display tool execution progress. See protocol docs: [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating) **Type:** Union [​](https://agentclientprotocol.com/protocol/schema#param-read) read string Reading files or data. [​](https://agentclientprotocol.com/protocol/schema#param-edit) edit string Modifying files or content. [​](https://agentclientprotocol.com/protocol/schema#param-delete) delete string Removing files or data. [​](https://agentclientprotocol.com/protocol/schema#param-move) move string Moving or renaming files. [​](https://agentclientprotocol.com/protocol/schema#param-search) search string Searching for information. [​](https://agentclientprotocol.com/protocol/schema#param-execute) execute string Running commands or code. [​](https://agentclientprotocol.com/protocol/schema#param-think) think string Internal reasoning or planning. [​](https://agentclientprotocol.com/protocol/schema#param-fetch) fetch string Retrieving external data. [​](https://agentclientprotocol.com/protocol/schema#param-switch-mode) switch\_mode string Switching the current session mode. [​](https://agentclientprotocol.com/protocol/schema#param-other-1) other string Other tool types (default). [​](https://agentclientprotocol.com/protocol/schema#unstructuredcommandinput) UnstructuredCommandInput --------------------------------------------------------------------------------------------------------- All text that was typed after the command name is provided as input. **Type:** Object **Properties:** [​](https://agentclientprotocol.com/protocol/schema#param-meta-104) \_meta object | null The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) [​](https://agentclientprotocol.com/protocol/schema#param-hint-1) hint string required A hint to display when the input hasn’t been provided yet Was this page helpful? YesNo [Previous](https://agentclientprotocol.com/protocol/transports) [KotlinKotlin library for the Agent Client Protocol\ \ Next](https://agentclientprotocol.com/libraries/kotlin) ⌘I On this page * [Agent](https://agentclientprotocol.com/protocol/schema#agent) * [authenticate](https://agentclientprotocol.com/protocol/schema#authenticate) * [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) * [AuthenticateResponse](https://agentclientprotocol.com/protocol/schema#authenticateresponse) * [initialize](https://agentclientprotocol.com/protocol/schema#initialize) * [InitializeRequest](https://agentclientprotocol.com/protocol/schema#initializerequest) * [InitializeResponse](https://agentclientprotocol.com/protocol/schema#initializeresponse) * [session/cancel](https://agentclientprotocol.com/protocol/schema#session%2Fcancel) * [CancelNotification](https://agentclientprotocol.com/protocol/schema#cancelnotification) * [session/list](https://agentclientprotocol.com/protocol/schema#session%2Flist) * [ListSessionsRequest](https://agentclientprotocol.com/protocol/schema#listsessionsrequest) * [ListSessionsResponse](https://agentclientprotocol.com/protocol/schema#listsessionsresponse) * [session/load](https://agentclientprotocol.com/protocol/schema#session%2Fload) * [LoadSessionRequest](https://agentclientprotocol.com/protocol/schema#loadsessionrequest) * [LoadSessionResponse](https://agentclientprotocol.com/protocol/schema#loadsessionresponse) * [session/new](https://agentclientprotocol.com/protocol/schema#session%2Fnew) * [NewSessionRequest](https://agentclientprotocol.com/protocol/schema#newsessionrequest) * [NewSessionResponse](https://agentclientprotocol.com/protocol/schema#newsessionresponse) * [session/prompt](https://agentclientprotocol.com/protocol/schema#session%2Fprompt) * [PromptRequest](https://agentclientprotocol.com/protocol/schema#promptrequest) * [PromptResponse](https://agentclientprotocol.com/protocol/schema#promptresponse) * [session/set\_config\_option](https://agentclientprotocol.com/protocol/schema#session%2Fset_config_option) * [SetSessionConfigOptionRequest](https://agentclientprotocol.com/protocol/schema#setsessionconfigoptionrequest) * [SetSessionConfigOptionResponse](https://agentclientprotocol.com/protocol/schema#setsessionconfigoptionresponse) * [session/set\_mode](https://agentclientprotocol.com/protocol/schema#session%2Fset_mode) * [SetSessionModeRequest](https://agentclientprotocol.com/protocol/schema#setsessionmoderequest) * [SetSessionModeResponse](https://agentclientprotocol.com/protocol/schema#setsessionmoderesponse) * [Client](https://agentclientprotocol.com/protocol/schema#client) * [fs/read\_text\_file](https://agentclientprotocol.com/protocol/schema#fs%2Fread_text_file) * [ReadTextFileRequest](https://agentclientprotocol.com/protocol/schema#readtextfilerequest) * [ReadTextFileResponse](https://agentclientprotocol.com/protocol/schema#readtextfileresponse) * [fs/write\_text\_file](https://agentclientprotocol.com/protocol/schema#fs%2Fwrite_text_file) * [WriteTextFileRequest](https://agentclientprotocol.com/protocol/schema#writetextfilerequest) * [WriteTextFileResponse](https://agentclientprotocol.com/protocol/schema#writetextfileresponse) * [session/request\_permission](https://agentclientprotocol.com/protocol/schema#session%2Frequest_permission) * [RequestPermissionRequest](https://agentclientprotocol.com/protocol/schema#requestpermissionrequest) * [RequestPermissionResponse](https://agentclientprotocol.com/protocol/schema#requestpermissionresponse) * [session/update](https://agentclientprotocol.com/protocol/schema#session%2Fupdate) * [SessionNotification](https://agentclientprotocol.com/protocol/schema#sessionnotification) * [terminal/create](https://agentclientprotocol.com/protocol/schema#terminal%2Fcreate) * [CreateTerminalRequest](https://agentclientprotocol.com/protocol/schema#createterminalrequest) * [CreateTerminalResponse](https://agentclientprotocol.com/protocol/schema#createterminalresponse) * [terminal/kill](https://agentclientprotocol.com/protocol/schema#terminal%2Fkill) * [KillTerminalRequest](https://agentclientprotocol.com/protocol/schema#killterminalrequest) * [KillTerminalResponse](https://agentclientprotocol.com/protocol/schema#killterminalresponse) * [terminal/output](https://agentclientprotocol.com/protocol/schema#terminal%2Foutput) * [TerminalOutputRequest](https://agentclientprotocol.com/protocol/schema#terminaloutputrequest) * [TerminalOutputResponse](https://agentclientprotocol.com/protocol/schema#terminaloutputresponse) * [terminal/release](https://agentclientprotocol.com/protocol/schema#terminal%2Frelease) * [ReleaseTerminalRequest](https://agentclientprotocol.com/protocol/schema#releaseterminalrequest) * [ReleaseTerminalResponse](https://agentclientprotocol.com/protocol/schema#releaseterminalresponse) * [terminal/wait\_for\_exit](https://agentclientprotocol.com/protocol/schema#terminal%2Fwait_for_exit) * [WaitForTerminalExitRequest](https://agentclientprotocol.com/protocol/schema#waitforterminalexitrequest) * [WaitForTerminalExitResponse](https://agentclientprotocol.com/protocol/schema#waitforterminalexitresponse) * [AgentCapabilities](https://agentclientprotocol.com/protocol/schema#agentcapabilities) * [Annotations](https://agentclientprotocol.com/protocol/schema#annotations) * [AudioContent](https://agentclientprotocol.com/protocol/schema#audiocontent) * [AuthMethod](https://agentclientprotocol.com/protocol/schema#authmethod) * [AuthMethodAgent](https://agentclientprotocol.com/protocol/schema#authmethodagent) * [AvailableCommand](https://agentclientprotocol.com/protocol/schema#availablecommand) * [AvailableCommandInput](https://agentclientprotocol.com/protocol/schema#availablecommandinput) * [AvailableCommandsUpdate](https://agentclientprotocol.com/protocol/schema#availablecommandsupdate) * [BlobResourceContents](https://agentclientprotocol.com/protocol/schema#blobresourcecontents) * [ClientCapabilities](https://agentclientprotocol.com/protocol/schema#clientcapabilities) * [ConfigOptionUpdate](https://agentclientprotocol.com/protocol/schema#configoptionupdate) * [Content](https://agentclientprotocol.com/protocol/schema#content) * [ContentBlock](https://agentclientprotocol.com/protocol/schema#contentblock) * [ContentChunk](https://agentclientprotocol.com/protocol/schema#contentchunk) * [CurrentModeUpdate](https://agentclientprotocol.com/protocol/schema#currentmodeupdate) * [Diff](https://agentclientprotocol.com/protocol/schema#diff) * [EmbeddedResource](https://agentclientprotocol.com/protocol/schema#embeddedresource) * [EmbeddedResourceResource](https://agentclientprotocol.com/protocol/schema#embeddedresourceresource) * [EnvVariable](https://agentclientprotocol.com/protocol/schema#envvariable) * [Error](https://agentclientprotocol.com/protocol/schema#error) * [ErrorCode](https://agentclientprotocol.com/protocol/schema#errorcode) * [ExtNotification](https://agentclientprotocol.com/protocol/schema#extnotification) * [ExtRequest](https://agentclientprotocol.com/protocol/schema#extrequest) * [ExtResponse](https://agentclientprotocol.com/protocol/schema#extresponse) * [FileSystemCapabilities](https://agentclientprotocol.com/protocol/schema#filesystemcapabilities) * [HttpHeader](https://agentclientprotocol.com/protocol/schema#httpheader) * [ImageContent](https://agentclientprotocol.com/protocol/schema#imagecontent) * [Implementation](https://agentclientprotocol.com/protocol/schema#implementation) * [McpCapabilities](https://agentclientprotocol.com/protocol/schema#mcpcapabilities) * [McpServer](https://agentclientprotocol.com/protocol/schema#mcpserver) * [McpServerHttp](https://agentclientprotocol.com/protocol/schema#mcpserverhttp) * [McpServerSse](https://agentclientprotocol.com/protocol/schema#mcpserversse) * [McpServerStdio](https://agentclientprotocol.com/protocol/schema#mcpserverstdio) * [PermissionOption](https://agentclientprotocol.com/protocol/schema#permissionoption) * [PermissionOptionId](https://agentclientprotocol.com/protocol/schema#permissionoptionid) * [PermissionOptionKind](https://agentclientprotocol.com/protocol/schema#permissionoptionkind) * [Plan](https://agentclientprotocol.com/protocol/schema#plan) * [PlanEntry](https://agentclientprotocol.com/protocol/schema#planentry) * [PlanEntryPriority](https://agentclientprotocol.com/protocol/schema#planentrypriority) * [PlanEntryStatus](https://agentclientprotocol.com/protocol/schema#planentrystatus) * [PromptCapabilities](https://agentclientprotocol.com/protocol/schema#promptcapabilities) * [ProtocolVersion](https://agentclientprotocol.com/protocol/schema#protocolversion) * [RequestId](https://agentclientprotocol.com/protocol/schema#requestid) * [RequestPermissionOutcome](https://agentclientprotocol.com/protocol/schema#requestpermissionoutcome) * [ResourceLink](https://agentclientprotocol.com/protocol/schema#resourcelink) * [Role](https://agentclientprotocol.com/protocol/schema#role) * [SelectedPermissionOutcome](https://agentclientprotocol.com/protocol/schema#selectedpermissionoutcome) * [SessionCapabilities](https://agentclientprotocol.com/protocol/schema#sessioncapabilities) * [SessionConfigGroupId](https://agentclientprotocol.com/protocol/schema#sessionconfiggroupid) * [SessionConfigId](https://agentclientprotocol.com/protocol/schema#sessionconfigid) * [SessionConfigOption](https://agentclientprotocol.com/protocol/schema#sessionconfigoption) * [SessionConfigOptionCategory](https://agentclientprotocol.com/protocol/schema#sessionconfigoptioncategory) * [SessionConfigSelect](https://agentclientprotocol.com/protocol/schema#sessionconfigselect) * [SessionConfigSelectGroup](https://agentclientprotocol.com/protocol/schema#sessionconfigselectgroup) * [SessionConfigSelectOption](https://agentclientprotocol.com/protocol/schema#sessionconfigselectoption) * [SessionConfigSelectOptions](https://agentclientprotocol.com/protocol/schema#sessionconfigselectoptions) * [SessionConfigValueId](https://agentclientprotocol.com/protocol/schema#sessionconfigvalueid) * [SessionId](https://agentclientprotocol.com/protocol/schema#sessionid) * [SessionInfo](https://agentclientprotocol.com/protocol/schema#sessioninfo) * [SessionInfoUpdate](https://agentclientprotocol.com/protocol/schema#sessioninfoupdate) * [SessionListCapabilities](https://agentclientprotocol.com/protocol/schema#sessionlistcapabilities) * [SessionMode](https://agentclientprotocol.com/protocol/schema#sessionmode) * [SessionModeId](https://agentclientprotocol.com/protocol/schema#sessionmodeid) * [SessionModeState](https://agentclientprotocol.com/protocol/schema#sessionmodestate) * [SessionUpdate](https://agentclientprotocol.com/protocol/schema#sessionupdate) * [StopReason](https://agentclientprotocol.com/protocol/schema#stopreason) * [Terminal](https://agentclientprotocol.com/protocol/schema#terminal) * [TerminalExitStatus](https://agentclientprotocol.com/protocol/schema#terminalexitstatus) * [TextContent](https://agentclientprotocol.com/protocol/schema#textcontent) * [TextResourceContents](https://agentclientprotocol.com/protocol/schema#textresourcecontents) * [ToolCall](https://agentclientprotocol.com/protocol/schema#toolcall) * [ToolCallContent](https://agentclientprotocol.com/protocol/schema#toolcallcontent) * [ToolCallId](https://agentclientprotocol.com/protocol/schema#toolcallid) * [ToolCallLocation](https://agentclientprotocol.com/protocol/schema#toolcalllocation) * [ToolCallStatus](https://agentclientprotocol.com/protocol/schema#toolcallstatus) * [ToolCallUpdate](https://agentclientprotocol.com/protocol/schema#toolcallupdate) * [ToolKind](https://agentclientprotocol.com/protocol/schema#toolkind) * [UnstructuredCommandInput](https://agentclientprotocol.com/protocol/schema#unstructuredcommandinput) ---