├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── 05_bug_report.yml │ ├── 10_accepted_protocol_changes.yml │ └── config.yml ├── dependabot.yml └── workflows │ ├── ci.yml │ ├── publish-schema.yml │ └── release-plz.yml ├── .gitignore ├── .prettierrc ├── .release-plz.toml ├── AGENTS.md ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── Cargo.lock ├── Cargo.toml ├── GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── README.md ├── docs ├── README.md ├── assets │ ├── acp-docs-logo-mark.webp │ └── acp-docs-logo.webp ├── brand.mdx ├── community │ ├── code-of-conduct.mdx │ ├── communication.mdx │ ├── contributing.mdx │ ├── governance.mdx │ └── working-interest-groups.mdx ├── docs.json ├── images │ ├── architecture-diagram.png │ ├── mcp-proxy.d2 │ ├── mcp-proxy.svg │ ├── mcp.d2 │ ├── mcp.svg │ ├── server-client.d2 │ └── server-client.svg ├── libraries │ ├── community.mdx │ ├── kotlin.mdx │ ├── python.mdx │ ├── rust.mdx │ └── typescript.mdx ├── logo │ ├── dark.svg │ ├── fav-dark.png │ ├── fav-light.png │ └── light.svg ├── overview │ ├── agents.mdx │ ├── architecture.mdx │ ├── clients.mdx │ └── introduction.mdx ├── protocol │ ├── agent-plan.mdx │ ├── content.mdx │ ├── error.mdx │ ├── extensibility.mdx │ ├── file-system.mdx │ ├── initialization.mdx │ ├── overview.mdx │ ├── prompt-turn.mdx │ ├── schema.mdx │ ├── schema.unstable.mdx │ ├── session-modes.mdx │ ├── session-setup.mdx │ ├── slash-commands.mdx │ ├── terminals.mdx │ ├── tool-calls.mdx │ └── transports.mdx ├── rfds │ ├── TEMPLATE │ ├── about.mdx │ ├── introduce-rfd-process.mdx │ ├── request-cancellation.mdx │ ├── session-config-options.mdx │ ├── session-fork.mdx │ ├── session-list.mdx │ └── session-resume.mdx ├── updates.mdx └── v2-changes.md ├── package-lock.json ├── package.json ├── rust ├── acp.rs ├── agent.rs ├── bin │ └── generate.rs ├── client.rs ├── content.rs ├── error.rs ├── ext.rs ├── plan.rs ├── rpc.rs ├── tool_call.rs └── version.rs ├── schema ├── meta.json ├── meta.unstable.json ├── schema.json └── schema.unstable.json ├── scripts └── spellcheck.sh └── typos.toml /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @agentclientprotocol/core-maintainers 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/05_bug_report.yml: -------------------------------------------------------------------------------- 1 | name: Bug Report 2 | description: | 3 | Something is not working as expected in ACP 4 | type: "Bug" 5 | body: 6 | - type: textarea 7 | attributes: 8 | label: Summary 9 | description: Provide a one sentence summary and detailed reproduction steps 10 | value: | 11 | 12 | SUMMARY_SENTENCE_HERE 13 | 14 | ### Description 15 | 18 | 19 | DESCRIPTION_HERE 20 | 21 | **Expected Behavior**: 22 | **Actual Behavior**: 23 | 24 | validations: 25 | required: true 26 | 27 | - type: textarea 28 | id: environment 29 | attributes: 30 | label: ACP Version 31 | validations: 32 | required: true 33 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/10_accepted_protocol_changes.yml: -------------------------------------------------------------------------------- 1 | name: Accepted Protocol Changes [Staff Only] 2 | description: Zed Staff Only 3 | type: "Feature" 4 | body: 5 | - type: textarea 6 | attributes: 7 | label: Summary 8 | value: | 9 | 10 | DISCUSSION_LINK_HERE 11 | 12 | ### Description 13 | 14 | IF YOU DO NOT WORK FOR ZED INDUSTRIES DO NOT CREATE ISSUES WITH THIS TEMPLATE. 15 | THEY WILL BE AUTO-CLOSED AND MAY RESULT IN YOU BEING BANNED FROM THE ZED ISSUE TRACKER. 16 | 17 | PROPOSALS TO ADD ADDITIONAL CAPABILITIES / CHANGE EXISTING ONES SHOULD BE PROPOSED IN DISCUSSIONS FIRST: 18 | https://github.com/agentclientprotocol/agent-client-protocol/discussions/categories/protocol-suggestions 19 | validations: 20 | required: true 21 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | # yaml-language-server: $schema=https://json.schemastore.org/github-issue-config.json 2 | blank_issues_enabled: false 3 | contact_links: 4 | - name: Propose Protocol Changes 5 | url: https://github.com/agentclientprotocol/agent-client-protocol/discussions/categories/protocol-suggestions 6 | about: Propose additions or changes to the protocol 7 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | # Check for updates to GitHub Actions every week 7 | interval: "weekly" 8 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: [main] 6 | pull_request: 7 | branches: [main] 8 | workflow_dispatch: 9 | 10 | permissions: 11 | contents: read 12 | pages: write 13 | id-token: write 14 | 15 | concurrency: 16 | group: "ci-${{ github.ref }}" 17 | cancel-in-progress: ${{ github.event_name == 'pull_request' }} 18 | 19 | jobs: 20 | build: 21 | name: Build 22 | runs-on: ubuntu-latest 23 | timeout-minutes: 5 24 | 25 | steps: 26 | - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 27 | 28 | - name: Use Node.js 29 | uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 30 | with: 31 | node-version: latest 32 | cache: "npm" 33 | 34 | - name: Setup Rust 35 | uses: actions-rust-lang/setup-rust-toolchain@1780873c7b576612439a134613cc4cc74ce5538c 36 | with: 37 | toolchain: nightly,stable 38 | components: rustfmt,clippy 39 | 40 | - name: Install dependencies 41 | run: npm ci 42 | 43 | - name: Check formatting 44 | run: npm run format:check 45 | 46 | - name: Check for typos 47 | uses: crate-ci/typos@2d0ce569feab1f8752f1dde43cc2f2aa53236e06 48 | with: 49 | config: ./typos.toml 50 | 51 | - name: Lint 52 | run: cargo clippy 53 | 54 | - name: Build 55 | run: cargo build --all-targets --all-features 56 | 57 | - name: Run tests 58 | run: cargo test --all-features 59 | -------------------------------------------------------------------------------- /.github/workflows/publish-schema.yml: -------------------------------------------------------------------------------- 1 | name: Upload Schema 2 | on: 3 | release: 4 | types: [published] 5 | 6 | permissions: {} 7 | 8 | concurrency: 9 | group: ${{ github.workflow }}-${{ github.ref }} 10 | cancel-in-progress: false 11 | 12 | jobs: 13 | upload-schema: 14 | permissions: 15 | contents: write # to upload release assets 16 | if: github.repository_owner == 'agentclientprotocol' && startsWith(github.event.release.name, 'v') 17 | runs-on: ubuntu-latest 18 | steps: 19 | - name: Checkout repository 20 | uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 21 | with: 22 | persist-credentials: false 23 | - name: Upload schema files to release 24 | env: 25 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 26 | run: | 27 | gh release upload "${{ github.event.release.name }}" schema/schema.json schema/meta.json schema/schema.unstable.json schema/meta.unstable.json 28 | -------------------------------------------------------------------------------- /.github/workflows/release-plz.yml: -------------------------------------------------------------------------------- 1 | name: Release-plz 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | release-plz-release: 10 | name: Release-plz release 11 | environment: release # Optional: for enhanced security 12 | runs-on: ubuntu-latest 13 | if: ${{ github.repository_owner == 'agentclientprotocol' }} 14 | permissions: 15 | contents: write 16 | id-token: write 17 | steps: 18 | - &checkout 19 | name: Checkout repository 20 | uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 21 | with: 22 | fetch-depth: 0 23 | persist-credentials: false 24 | - &install-rust 25 | name: Install Rust toolchain 26 | uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e 27 | with: 28 | toolchain: stable 29 | - &generate-token 30 | # Generating a GitHub token, so that PRs and tags created by 31 | # the release-plz-action can trigger actions workflows. 32 | name: Generate GitHub token 33 | uses: actions/create-github-app-token@7e473efe3cb98aa54f8d4bac15400b15fad77d94 34 | id: generate-token 35 | with: 36 | # GitHub App ID secret name 37 | app-id: ${{ secrets.RELEASE_PLZ_APP_ID }} 38 | # GitHub App private key secret name 39 | private-key: ${{ secrets.RELEASE_PLZ_APP_PRIVATE_KEY }} 40 | - name: Run release-plz 41 | uses: release-plz/action@1efcf74dfcd6e500990dad806e286899ae384064 42 | with: 43 | command: release 44 | env: 45 | GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }} 46 | 47 | release-plz-pr: 48 | name: Release-plz PR 49 | runs-on: ubuntu-latest 50 | if: ${{ github.repository_owner == 'agentclientprotocol' }} 51 | permissions: 52 | pull-requests: write 53 | contents: write 54 | concurrency: 55 | group: release-plz-${{ github.ref }} 56 | cancel-in-progress: false 57 | steps: 58 | - *checkout 59 | - *install-rust 60 | - *generate-token 61 | - name: Run release-plz 62 | uses: release-plz/action@1efcf74dfcd6e500990dad806e286899ae384064 63 | with: 64 | command: release-pr 65 | env: 66 | GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }} 67 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | target 2 | node_modules 3 | dist 4 | *.tsbuildinfo 5 | .DS_Store 6 | 7 | # TypeScript generated files 8 | typescript/*.js 9 | typescript/*.d.ts 10 | typescript/*.js.map 11 | # Exclude generator scripts 12 | !typescript/generate.js 13 | 14 | # TypeDoc generated documentation 15 | typescript/docs/ 16 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | {} 2 | -------------------------------------------------------------------------------- /.release-plz.toml: -------------------------------------------------------------------------------- 1 | [workspace] 2 | git_release_type = "auto" 3 | -------------------------------------------------------------------------------- /AGENTS.md: -------------------------------------------------------------------------------- 1 | All paths in the protocol should be absolute 2 | 3 | ## Adding new methods 4 | 5 | - Create empty params and output structs in rust/client.rs or rust/agent.rs under the corresponding section. I'll add the fields myself. 6 | - If the protocol method name is `noun/verb`, use `verb_noun` for the user facing methods and structs. 7 | 8 | Example 1 (`noun/noun`): 9 | Protocol method: `terminal/output` 10 | Trait method name: `terminal_output` 11 | Request/Response structs: `TerminalOutputRequest` / `TerminalOutputResponse` 12 | Method names struct: `terminal_output: &'static str` 13 | 14 | Example 2 (`noun/verb`): 15 | Protocol method: `terminal/new` 16 | Trait method name: `new_terminal` 17 | Request/Response structs: `NewTerminalRequest` / `NewTerminalResponse` 18 | Method names struct: `terminal_new: &'static str` 19 | 20 | - Do not write any tests or docs at all! 21 | - Add constants for the method names 22 | - Add variants to {Agent|Client}{Request|Response} enums 23 | - Add the methods to the Client/Agent impl of {Agent|Client}SideConnection in rust/acp.rs 24 | - Handle the new method in the `Side::decode_request`/`Side::decode_notification` implementation 25 | - Handle the new request in the blanket impl of MessageHandler<{Agent|Client}Side> 26 | - Add the method to markdown_generator.rs SideDocs functions 27 | - Run `npm run generate` and fix any issues that appear 28 | - Run `npm run check` 29 | - Update the example agents and clients in tests and examples in both libraries 30 | 31 | ## Updating existing methods, their params, or output 32 | 33 | - Update the mintlify docs and guides in the `docs` directory 34 | - Run `npm run check` to make sure the json and zod schemas gets generated properly 35 | 36 | Never write readme files related to the conversation unless explicitly asked to. 37 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## [0.8.0](https://github.com/agentclientprotocol/agent-client-protocol/compare/v0.7.0...v0.8.0) - 2025-11-28 4 | 5 | Some follow-up changes from 0.7.0. Most of the changes were in the Rust schema to make things a bit easier to work with. 6 | 7 | However, there were some further cleanups to the JSON schema to remove some $ref indirection where possible to have the schema be a bit flatter. 8 | 9 | There are also some fixes that were causing issues with code generators related to Extension methods, these now have concrete types in the schema as well. 10 | 11 | **Rust**: There are some breaking changes to the `OutgoingMessage` types and other low-level RPC types to make them generate clearer JSON schema representations. Likely these are only used by SDKs, but they moved to tuple enum variants. 12 | 13 | Also, rather than having free-floating `V0` and `V1` constants, these are now associated constants on the `ProtocolVersion` type itself. 14 | 15 | ### Fixed 16 | 17 | - Broken doctest and test in CI ([#267](https://github.com/agentclientprotocol/agent-client-protocol/pull/267)) 18 | 19 | ### Other 20 | 21 | - Remove some nesting of the JSON schema ([#278](https://github.com/agentclientprotocol/agent-client-protocol/pull/278)) 22 | - Easier ids in constructors ([#275](https://github.com/agentclientprotocol/agent-client-protocol/pull/275)) 23 | - Exhaustive RPC types ([#272](https://github.com/agentclientprotocol/agent-client-protocol/pull/272)) 24 | - Easier `new` methods for ExtRequest + ExtNotification ([#271](https://github.com/agentclientprotocol/agent-client-protocol/pull/271)) 25 | - Protocol Version constants ([#270](https://github.com/agentclientprotocol/agent-client-protocol/pull/270)) 26 | - Cleanup Rust example from schema docs ([#269](https://github.com/agentclientprotocol/agent-client-protocol/pull/269)) 27 | - Introduce helper methods to get the corresponding method name of a ([#268](https://github.com/agentclientprotocol/agent-client-protocol/pull/268)) 28 | 29 | ## 0.7.0 (2025-11-25) 30 | 31 | This is a big release as we move towards a v1.0 release of the JSON Schema. 32 | 33 | This should be the final form, we just want to go through the motions of upgrading all of the SDKs to verify no further changes are needed. 34 | 35 | **NOTE: The Protocol version is already, and remains, `1`. This is just for the JSON Schema itself.** There are no breaking changes to the protocol, we just reworked the schema representation to be more compliant with code generation tooling for the various SDKs. 36 | 37 | We also now have two variants of the schema attached to the release: 38 | 39 | **Stable** 40 | 41 | - schema.json 42 | - meta.json 43 | 44 | **Unstable** 45 | 46 | - schema.unstable.json 47 | - meta.unstable.json 48 | 49 | As we have more [RFD](https://agentclientprotocol.com/rfds/about) implementations in progress, this will allow us to iterate on the schema without requiring SDKs to churn through the changes. 50 | 51 | For SDK authors, it is important if you use the unstable version, to make sure the unstable features are behind a flag of some kind with clear direction to your users about the state of these features. But this will also allow teams to start testing the unstable features and provide feedback to the RFD authors. 52 | 53 | ### Rust 54 | 55 | The Rust crate, `agent-client-protocol-schema` has major breaking changes. All exported type are now marked as `#[non_exhaustive]`. Since the schema itself is JSON, and we can introduce new fields and variants in a non-breaking way, we wanted to allow for the same behavior in the Rust library. 56 | 57 | All enum variants are also tuple variants now, with their own structs. This made it nicer to represent in the JSON Schema, and also made sure we have `_meta` fields on all variants. 58 | 59 | This upgrade will likely come with a lot of compilation errors, but ideally upgrading will be more painless in the future. 60 | 61 | ## 0.6.3 (2025-10-30) 62 | 63 | ### Protocol 64 | 65 | - Add `discriminator` fields to the schema.json for tagged enums to aid with code generation in language tooling. 66 | 67 | ## 0.6.2 (2025-10-24) 68 | 69 | ### Protocol 70 | 71 | Fix incorrectly named `_meta` field on `SetSessionModeResponse` 72 | 73 | ## 0.6.1 (2025-10-24) 74 | 75 | ### Protocol 76 | 77 | - No changes 78 | 79 | ### Rust 80 | 81 | - Make `Implementation` fields public 82 | 83 | ## 0.6.0 (2025-10-24) 84 | 85 | ### Protocol 86 | 87 | - Add ability for agents and clients to provide information about their implementation https://github.com/agentclientprotocol/agent-client-protocol/pull/192 88 | 89 | ## 0.5.0 (2025-10-23) 90 | 91 | ### Protocol 92 | 93 | - JSON Schema: More consistent inlining for enum representations to fix issues with code generation in language tooling. 94 | - Provide more schema-level information about JSON-RPC format. 95 | - Provide missing `_meta` fields on certain enum variants. 96 | 97 | ### Rust 98 | 99 | - More consistent enum usage. Enums are always either newtype or struct variants within a single enum, not mixed. 100 | 101 | ## 0.4.11 (2025-10-20) 102 | 103 | ### Protocol 104 | 105 | - No changes 106 | 107 | ### Rust 108 | 109 | - Make id types easier to create and add `PartialEq` and `Eq` impls for as many types as possible. 110 | 111 | ## 0.4.10 (2025-10-16) 112 | 113 | ### Protocol 114 | 115 | - No changes 116 | 117 | ### Rust 118 | 119 | - Export `Result` type with a default of `acp::Error` 120 | 121 | ## 0.4.9 (2025-10-13) 122 | 123 | - Fix schema publishing 124 | 125 | ## 0.4.8 (2025-10-13) 126 | 127 | - Fix publishing 128 | 129 | ## 0.4.7 (2025-10-13) 130 | 131 | ### Protocol 132 | 133 | - Schema uploaded to GitHub releases 134 | 135 | ### Rust 136 | 137 | - SDK has moved to https://github.com/agentclientprotocol/rust-sdk 138 | - Start publishing schema types to crates.io: https://crates.io/crates/agent-client-protocol-schema 139 | 140 | ## 0.4.6 (2025-10-10) 141 | 142 | ### Protocol 143 | 144 | - No changes 145 | 146 | ### Rust 147 | 148 | - Fix: support all valid JSON-RPC ids (int, string, null) 149 | 150 | ## 0.4.5 (2025-10-02) 151 | 152 | ### Protocol 153 | 154 | - No changes 155 | 156 | ### Typescript 157 | 158 | - **Unstable** initial support for model selection. 159 | 160 | ## 0.4.4 (2025-09-30) 161 | 162 | ### Protocol 163 | 164 | - No changes 165 | 166 | ### Rust 167 | 168 | - Provide default trait implementations for optional capability-based `Agent` and `Client` methods. 169 | 170 | ### Typescript 171 | 172 | - Correctly mark capability-based `Agent` and `Client` methods as optional. 173 | 174 | ## 0.4.3 (2025-09-25) 175 | 176 | ### Protocol 177 | 178 | - Defined `Resource not found` error type as code `-32002` (same as MCP) 179 | 180 | ### Rust 181 | 182 | - impl `Agent` and `Client` for `Rc` and `Arc` where `T` implements either trait. 183 | 184 | ## 0.4.2 (2025-09-22) 185 | 186 | ### Rust 187 | 188 | **Unstable** fix missing method for model selection in Rust library. 189 | 190 | ## 0.4.1 (2025-09-22) 191 | 192 | ### Protocol 193 | 194 | **Unstable** initial support for model selection. 195 | 196 | ## 0.4.0 (2025-09-17) 197 | 198 | ### Protocol 199 | 200 | No changes. 201 | 202 | ### Rust Library 203 | 204 | - Make `Agent` and `Client` dyn compatible (you'll need to annotate them with `#[async_trait]`) [#97](https://github.com/agentclientprotocol/agent-client-protocol/pull/97) 205 | - `ext_method` and `ext_notification` methods are now more consistent with the other trait methods [#95](https://github.com/agentclientprotocol/agent-client-protocol/pull/95) 206 | - There are also distinct types for `ExtRequest`, `ExtResponse`, and `ExtNotification` 207 | - Rexport `serde_json::RawValue` for easier use [#95](https://github.com/agentclientprotocol/agent-client-protocol/pull/95) 208 | 209 | ### Typescript Library 210 | 211 | - Use Stream abstraction instead of raw byte streams [#93](https://github.com/agentclientprotocol/agent-client-protocol/pull/93) 212 | - Makes it easier to use with websockets instead of stdio 213 | - Improve type safety for method map helpers [#94](https://github.com/agentclientprotocol/agent-client-protocol/pull/94) 214 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | The Code of Conduct for this repository can be found online at [agentclientprotocol.com/community/code-of-conduct](https://agentclientprotocol.com/community/code-of-conduct). 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Welcome! 2 | 3 | Thank you for your interest in contributing to Agent Client Protocol! We welcome new contributors and are glad that you want to contribute to our project. This document explains how to get involved, what we expect from contributors, and how we work together. 4 | 5 | ## Ways to contribute 6 | 7 | We welcome many different types of contributions including: 8 | 9 | - New features 10 | - Builds, CI/CD 11 | - Bug fixes 12 | - Documentation 13 | - Issue Triage 14 | - Answering questions on Zulip/Mailing List 15 | - Web design 16 | - Communications / Social Media / Blog Posts 17 | - Release management 18 | 19 | ## Getting Started 20 | 21 | To get started, make sure you have the following installed: 22 | 23 | - [Rust](https://www.rust-lang.org/) 24 | - [Node.js](https://nodejs.org/) 25 | 26 | The schema files in the `/schema` directory are generated from the Rust code in the `rust` directory. You can always generate the latest schema files by running `npm run generate` which will also format the files for you. 27 | 28 | Spellchecking is done via `npm run spellcheck`. 29 | 30 | Tests are run via `cargo test`. 31 | 32 | Unreleased features will be behind an `unstable` feature flag in the Rust crate. 33 | 34 | If you notice a bug in the protocol, please file [an issue](https://github.com/agentclientprotocol/agent-client-protocol/issues/new?template=05_bug_report.yml) and we will be in touch. 35 | 36 | ## Coding Standards 37 | 38 | For our Rust code, we use [rustfmt](https://github.com/rust-lang/rustfmt) and [clippy](https://github.com/rust-lang/rust-clippy) to enforce a consistent style and catch common mistakes. 39 | 40 | For other files, like docs and schema files, we use [prettier](https://prettier.io/) to enforce a consistent style. 41 | 42 | Our CI jobs will make sure all new changes fit these coding standards. 43 | 44 | New features should be documented before being stabilized and released to users. 45 | 46 | Feel free to add tests for any portion of the schema files that would benefit, we'll make sure these run in CI as well. 47 | 48 | ## RFD Process 49 | 50 | Before a significant change or addition to the protocol is made, you should likely open an RFD (Request for Dialog) following [our RFD process](https://agentclientprotocol.com/rfds/about) to get feedback on your proposed changes before you do a lot of implementation work. This helps ensure that your changes align with the project's goals and should help avoid the frustration of doing work that may not be accepted. 51 | 52 | ## Pull Request Process 53 | 54 | 1. Ensure your branch is up to date with the main branch. 55 | 2. Open a pull request with a clear title and description. 56 | 3. At least one maintainer must review and approve the change before merging. 57 | 4. Maintainers may request changes or clarifications – this is part of the process. 58 | 5. Once approved, a maintainer will merge your pull request. 59 | 60 | ## Asking For Help 61 | 62 | If you’re unsure about anything, feel free to reach out! The best way to reach us with a question when contributing is to ask on: 63 | 64 | - The original GitHub issue or discussion thread 65 | - [Zulip](https://agentclientprotocol.zulipchat.com/) 66 | 67 | ## Code of Conduct 68 | 69 | All contributors are expected to follow the project’s [Code of Conduct](CODE_OF_CONDUCT.md). 70 | 71 | Please treat others with respect, foster an inclusive environment, and help keep this a welcoming project for everyone. 72 | 73 | ## Contribution Policy 74 | 75 | This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms: 76 | 77 | > 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). 78 | -------------------------------------------------------------------------------- /Cargo.lock: -------------------------------------------------------------------------------- 1 | # This file is automatically @generated by Cargo. 2 | # It is not intended for manual editing. 3 | version = 4 4 | 5 | [[package]] 6 | name = "agent-client-protocol-schema" 7 | version = "0.8.0" 8 | dependencies = [ 9 | "anyhow", 10 | "derive_more", 11 | "schemars", 12 | "serde", 13 | "serde_json", 14 | ] 15 | 16 | [[package]] 17 | name = "anyhow" 18 | version = "1.0.100" 19 | source = "registry+https://github.com/rust-lang/crates.io-index" 20 | checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61" 21 | 22 | [[package]] 23 | name = "derive_more" 24 | version = "2.0.1" 25 | source = "registry+https://github.com/rust-lang/crates.io-index" 26 | checksum = "093242cf7570c207c83073cf82f79706fe7b8317e98620a47d5be7c3d8497678" 27 | dependencies = [ 28 | "derive_more-impl", 29 | ] 30 | 31 | [[package]] 32 | name = "derive_more-impl" 33 | version = "2.0.1" 34 | source = "registry+https://github.com/rust-lang/crates.io-index" 35 | checksum = "bda628edc44c4bb645fbe0f758797143e4e07926f7ebf4e9bdfbd3d2ce621df3" 36 | dependencies = [ 37 | "proc-macro2", 38 | "quote", 39 | "syn", 40 | "unicode-xid", 41 | ] 42 | 43 | [[package]] 44 | name = "dyn-clone" 45 | version = "1.0.20" 46 | source = "registry+https://github.com/rust-lang/crates.io-index" 47 | checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555" 48 | 49 | [[package]] 50 | name = "itoa" 51 | version = "1.0.15" 52 | source = "registry+https://github.com/rust-lang/crates.io-index" 53 | checksum = "4a5f13b858c8d314ee3e8f639011f7ccefe71f97f96e50151fb991f267928e2c" 54 | 55 | [[package]] 56 | name = "memchr" 57 | version = "2.7.6" 58 | source = "registry+https://github.com/rust-lang/crates.io-index" 59 | checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273" 60 | 61 | [[package]] 62 | name = "proc-macro2" 63 | version = "1.0.103" 64 | source = "registry+https://github.com/rust-lang/crates.io-index" 65 | checksum = "5ee95bc4ef87b8d5ba32e8b7714ccc834865276eab0aed5c9958d00ec45f49e8" 66 | dependencies = [ 67 | "unicode-ident", 68 | ] 69 | 70 | [[package]] 71 | name = "quote" 72 | version = "1.0.42" 73 | source = "registry+https://github.com/rust-lang/crates.io-index" 74 | checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f" 75 | dependencies = [ 76 | "proc-macro2", 77 | ] 78 | 79 | [[package]] 80 | name = "ref-cast" 81 | version = "1.0.25" 82 | source = "registry+https://github.com/rust-lang/crates.io-index" 83 | checksum = "f354300ae66f76f1c85c5f84693f0ce81d747e2c3f21a45fef496d89c960bf7d" 84 | dependencies = [ 85 | "ref-cast-impl", 86 | ] 87 | 88 | [[package]] 89 | name = "ref-cast-impl" 90 | version = "1.0.25" 91 | source = "registry+https://github.com/rust-lang/crates.io-index" 92 | checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da" 93 | dependencies = [ 94 | "proc-macro2", 95 | "quote", 96 | "syn", 97 | ] 98 | 99 | [[package]] 100 | name = "ryu" 101 | version = "1.0.20" 102 | source = "registry+https://github.com/rust-lang/crates.io-index" 103 | checksum = "28d3b2b1366ec20994f1fd18c3c594f05c5dd4bc44d8bb0c1c632c8d6829481f" 104 | 105 | [[package]] 106 | name = "schemars" 107 | version = "1.1.0" 108 | source = "registry+https://github.com/rust-lang/crates.io-index" 109 | checksum = "9558e172d4e8533736ba97870c4b2cd63f84b382a3d6eb063da41b91cce17289" 110 | dependencies = [ 111 | "dyn-clone", 112 | "ref-cast", 113 | "schemars_derive", 114 | "serde", 115 | "serde_json", 116 | ] 117 | 118 | [[package]] 119 | name = "schemars_derive" 120 | version = "1.1.0" 121 | source = "registry+https://github.com/rust-lang/crates.io-index" 122 | checksum = "301858a4023d78debd2353c7426dc486001bddc91ae31a76fb1f55132f7e2633" 123 | dependencies = [ 124 | "proc-macro2", 125 | "quote", 126 | "serde_derive_internals", 127 | "syn", 128 | ] 129 | 130 | [[package]] 131 | name = "serde" 132 | version = "1.0.228" 133 | source = "registry+https://github.com/rust-lang/crates.io-index" 134 | checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" 135 | dependencies = [ 136 | "serde_core", 137 | "serde_derive", 138 | ] 139 | 140 | [[package]] 141 | name = "serde_core" 142 | version = "1.0.228" 143 | source = "registry+https://github.com/rust-lang/crates.io-index" 144 | checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" 145 | dependencies = [ 146 | "serde_derive", 147 | ] 148 | 149 | [[package]] 150 | name = "serde_derive" 151 | version = "1.0.228" 152 | source = "registry+https://github.com/rust-lang/crates.io-index" 153 | checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" 154 | dependencies = [ 155 | "proc-macro2", 156 | "quote", 157 | "syn", 158 | ] 159 | 160 | [[package]] 161 | name = "serde_derive_internals" 162 | version = "0.29.1" 163 | source = "registry+https://github.com/rust-lang/crates.io-index" 164 | checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711" 165 | dependencies = [ 166 | "proc-macro2", 167 | "quote", 168 | "syn", 169 | ] 170 | 171 | [[package]] 172 | name = "serde_json" 173 | version = "1.0.145" 174 | source = "registry+https://github.com/rust-lang/crates.io-index" 175 | checksum = "402a6f66d8c709116cf22f558eab210f5a50187f702eb4d7e5ef38d9a7f1c79c" 176 | dependencies = [ 177 | "itoa", 178 | "memchr", 179 | "ryu", 180 | "serde", 181 | "serde_core", 182 | ] 183 | 184 | [[package]] 185 | name = "syn" 186 | version = "2.0.111" 187 | source = "registry+https://github.com/rust-lang/crates.io-index" 188 | checksum = "390cc9a294ab71bdb1aa2e99d13be9c753cd2d7bd6560c77118597410c4d2e87" 189 | dependencies = [ 190 | "proc-macro2", 191 | "quote", 192 | "unicode-ident", 193 | ] 194 | 195 | [[package]] 196 | name = "unicode-ident" 197 | version = "1.0.22" 198 | source = "registry+https://github.com/rust-lang/crates.io-index" 199 | checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5" 200 | 201 | [[package]] 202 | name = "unicode-xid" 203 | version = "0.2.6" 204 | source = "registry+https://github.com/rust-lang/crates.io-index" 205 | checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853" 206 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "agent-client-protocol-schema" 3 | authors = ["Zed "] 4 | version = "0.8.0" 5 | edition = "2024" 6 | license = "Apache-2.0" 7 | description = "A protocol for standardizing communication between code editors and AI coding agents" 8 | repository = "https://github.com/agentclientprotocol/agent-client-protocol" 9 | homepage = "https://github.com/agentclientprotocol/agent-client-protocol" 10 | documentation = "https://docs.rs/agent-client-protocol-schema" 11 | readme = "README.md" 12 | keywords = ["agent", "client", "protocol", "ai", "editor"] 13 | categories = ["development-tools", "api-bindings"] 14 | include = ["/rust/**/*.rs", "/README.md", "/LICENSE", "/Cargo.toml"] 15 | 16 | [features] 17 | unstable = ["unstable_session_model", "unstable_session_list"] 18 | unstable_session_model = [] 19 | unstable_session_list = [] 20 | 21 | [lib] 22 | path = "rust/acp.rs" 23 | 24 | [[bin]] 25 | name = "generate" 26 | path = "rust/bin/generate.rs" 27 | 28 | [dependencies] 29 | anyhow = "1" 30 | derive_more = { version = "2", features = ["from", "display"] } 31 | schemars = { version = "1" } 32 | serde = { version = "1", features = ["derive", "rc"] } 33 | serde_json = { version = "1", features = ["raw_value"] } 34 | 35 | [lints.rust] 36 | future_incompatible = { level = "warn", priority = -1 } 37 | let-underscore = "warn" 38 | missing_debug_implementations = "warn" 39 | # missing_docs = "warn" 40 | nonstandard_style = { level = "warn", priority = -1 } 41 | rust_2018_idioms = { level = "warn", priority = -1 } 42 | unused = { level = "warn", priority = -1 } 43 | 44 | [lints.clippy] 45 | cargo = "warn" 46 | exhaustive_enums = "warn" 47 | exhaustive_structs = "warn" 48 | pedantic = "warn" 49 | -------------------------------------------------------------------------------- /GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # Governance 2 | 3 | The governance model for ACP can be found online at [agentclientprotocol.com/community/governance](https://agentclientprotocol.com/community/governance). 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | Copyright 2025 Zed Industries, Inc. and contributors 179 | 180 | Licensed under the Apache License, Version 2.0 (the "License"); 181 | you may not use this file except in compliance with the License. 182 | You may obtain a copy of the License at 183 | 184 | http://www.apache.org/licenses/LICENSE-2.0 185 | 186 | Unless required by applicable law or agreed to in writing, software 187 | distributed under the License is distributed on an "AS IS" BASIS, 188 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 189 | See the License for the specific language governing permissions and 190 | limitations under the License. 191 | -------------------------------------------------------------------------------- /MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | # Maintainers 2 | 3 | The current maintainers for ACP are: 4 | 5 | **Last updated:** November 18, 2025 6 | 7 | ## Lead Maintainers 8 | 9 | | Name | Email | GitHub | 10 | | ------------ | ---------------- | ---------------------------- | 11 | | Ben Brandt | benjamin@zed.dev | https://github.com/benbrandt | 12 | | Agus Zubiaga | agus@zed.dev | https://github.com/agu-z | 13 | 14 | ## Core Maintainers 15 | 16 | | Name | GitHub | 17 | | --------------- | ------------------------------- | 18 | | Richard Feldman | https://github.com/rtfeldman | 19 | | Sergey Ignatov | https://github.com/ignatov | 20 | | Anna Zhdan | https://github.com/anna239 | 21 | | Niko Matsakis | https://github.com/nikomatsakis | 22 | 23 | ## SDK Maintainers 24 | 25 | ### Java SDK 26 | 27 | | Name | GitHub | 28 | | ------------ | ------------------------------ | 29 | | Mark Pollack | https://github.com/markpollack | 30 | 31 | ### Kotlin SDK 32 | 33 | | Name | GitHub | 34 | | ----------------- | ----------------------------- | 35 | | Sergey Ignatov | https://github.com/ignatov | 36 | | Anna Zhdan | https://github.com/anna239 | 37 | | Artem Bukhonov | https://github.com/nerzhulart | 38 | | Stanislav Erokhin | https://github.com/erokhins | 39 | 40 | ### Python SDK 41 | 42 | | Name | GitHub | 43 | | ------------- | ------------------------- | 44 | | Chojan Shang | https://github.com/PsiACE | 45 | | Richard Chien | https://github.com/stdrc | 46 | 47 | ### Rust SDK 48 | 49 | | Name | GitHub | 50 | | ---------------- | ------------------------------- | 51 | | Ben Brandt | https://github.com/benbrandt | 52 | | Niko Matsakis | https://github.com/nikomatsakis | 53 | | Richard Feldman | https://github.com/rtfeldman | 54 | | Agus Zubiaga | https://github.com/agu-z | 55 | | Bennet Bo Fenner | https://github.com/bennetbo | 56 | 57 | ### TypeScript SDK 58 | 59 | | Name | GitHub | 60 | | ---------------- | ---------------------------- | 61 | | Ben Brandt | https://github.com/benbrandt | 62 | | Richard Feldman | https://github.com/rtfeldman | 63 | | Agus Zubiaga | https://github.com/agu-z | 64 | | Bennet Bo Fenner | https://github.com/bennetbo | 65 | 66 | ## Working Group & Interest Group Maintainers 67 | 68 | [Working Groups and Interest Groups](https://agentclientprotocol.com/community/working-interest-groups) are not required to have maintainers (they can be managed by informal facilitators), but maintainers may be appointed on an as-needed basis. 69 | 70 | _No current working or interest groups._ 71 | 72 | --- 73 | 74 | This document is updated by the ACP maintainers and reflects the current 75 | governance structure. For more information about ACP governance, see our 76 | [governance documentation](https://agentclientprotocol.com/community/governance). 77 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | Agent Client Protocol 3 | 4 | 5 | # Agent Client Protocol 6 | 7 | The Agent Client Protocol (ACP) standardizes communication between _code editors_ (interactive programs for viewing and editing source code) and _coding agents_ (programs that use generative AI to autonomously modify code). 8 | 9 | Learn more at [agentclientprotocol.com](https://agentclientprotocol.com/). 10 | 11 | ## Integrations 12 | 13 | - [Schema](./schema/schema.json) 14 | - [Agents](https://agentclientprotocol.com/overview/agents) 15 | - [Clients](https://agentclientprotocol.com/overview/clients) 16 | - Official Libraries 17 | - **Kotlin**: [`acp-kotlin`](https://github.com/agentclientprotocol/kotlin-sdk) - Supports JVM, other targets are in progress, see [samples](https://github.com/agentclientprotocol/kotlin-sdk/tree/master/samples/kotlin-acp-client-sample/src/main/kotlin/com/agentclientprotocol/samples) 18 | - **Python**: [`python-sdk`](https://github.com/agentclientprotocol/python-sdk) - See [examples](https://github.com/agentclientprotocol/python-sdk/tree/main/examples) 19 | - **Rust**: [`agent-client-protocol`](https://crates.io/crates/agent-client-protocol) - See [examples/agent.rs](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/agent.rs) and [examples/client.rs](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/client.rs) 20 | - **TypeScript**: [`@agentclientprotocol/sdk`](https://www.npmjs.com/package/@agentclientprotocol/sdk) - See [examples/](https://github.com/agentclientprotocol/typescript-sdk/tree/main/src/examples) 21 | - [Community Libraries](https://agentclientprotocol.com/libraries/community) 22 | 23 | ## Contributing 24 | 25 | ACP is a protocol intended for broad adoption across the ecosystem; we follow a structured process to ensure changes are well-considered. Read the [Contributing Guide](./CONTRIBUTING.md) for more information. 26 | 27 | ## Contribution Policy 28 | 29 | This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms: 30 | 31 | > 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). 32 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # ACP Documentation 2 | 3 | The ACP documentation uses [Mintlify](https://mintlify.com/). 4 | All files are MDX and can host custom components if there's a need to. 5 | 6 | ## Running 7 | 8 | Run the following command to have the documentation live locally: 9 | 10 | ```bash 11 | npm run docs 12 | ``` 13 | 14 | ## Preview changes locally 15 | 16 | To preview the changes locally, run the following command: 17 | 18 | ```bash 19 | mint dev 20 | ``` 21 | 22 | ### Install the CLI 23 | 24 | Before running the site locally you need to install Mint's CLI: 25 | 26 | ```bash 27 | npm i -g mint 28 | ``` 29 | 30 | ## Deployment 31 | 32 | The documentation site is updated every time changes get to `main`. 33 | -------------------------------------------------------------------------------- /docs/assets/acp-docs-logo-mark.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/21a8206c1304b602c50c32a75a33afd7462c2853/docs/assets/acp-docs-logo-mark.webp -------------------------------------------------------------------------------- /docs/assets/acp-docs-logo.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/21a8206c1304b602c50c32a75a33afd7462c2853/docs/assets/acp-docs-logo.webp -------------------------------------------------------------------------------- /docs/brand.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Brand" 3 | description: "Assets for the Agent Client Protocol brand." 4 | --- 5 | 6 | Following these guidelines helps maintain brand integrity while supporting ACP's mission to standardize communication between code editors and coding agents. 7 | 8 | [Download all of the assets here](https://cdn.agentclientprotocol.com/acp-brand.zip) 9 | 10 | ## Logo 11 | 12 | The ACP logo can be used with the "ACP" logomark with or without a gradient. 13 | We provide a vertical and horizontal variant for display flexibility. 14 | 15 | 16 | Agentic Client Protocol Logo 17 | 18 | 19 | ## Logomark 20 | 21 | The logomark has a variation that includes a slight gradient on the bottom right part of it. 22 | 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. 23 | 24 | 25 | Agentic Client Protocol Logomark 29 | 30 | -------------------------------------------------------------------------------- /docs/community/code-of-conduct.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Code of Conduct 3 | --- 4 | 5 | ## Our Pledge 6 | 7 | We as members, contributors, and leaders pledge to make participation in our 8 | community a harassment-free experience for everyone, regardless of age, body 9 | size, visible or invisible disability, ethnicity, sex characteristics, gender 10 | identity and expression, level of experience, education, socio-economic status, 11 | nationality, personal appearance, race, religion, or sexual identity 12 | and orientation. 13 | 14 | We pledge to act and interact in ways that contribute to an open, welcoming, 15 | diverse, inclusive, and healthy community. 16 | 17 | ## Our Standards 18 | 19 | Examples of behavior that contributes to a positive environment for our 20 | community include: 21 | 22 | - Demonstrating empathy and kindness toward other people 23 | - Being respectful of differing opinions, viewpoints, and experiences 24 | - Giving and gracefully accepting constructive feedback 25 | - Accepting responsibility and apologizing to those affected by our mistakes, 26 | and learning from the experience 27 | - Focusing on what is best not just for us as individuals, but for the 28 | overall community 29 | 30 | Examples of unacceptable behavior include: 31 | 32 | - The use of sexualized language or imagery, and sexual attention or 33 | advances of any kind 34 | - Trolling, insulting or derogatory comments, and personal or political attacks 35 | - Public or private harassment 36 | - Publishing others' private information, such as a physical or email 37 | address, without their explicit permission 38 | - Other conduct which could reasonably be considered inappropriate in a 39 | professional setting 40 | 41 | ## Enforcement Responsibilities 42 | 43 | Community leaders are responsible for clarifying and enforcing our standards of 44 | acceptable behavior and will take appropriate and fair corrective action in 45 | response to any behavior that they deem inappropriate, threatening, offensive, 46 | or harmful. 47 | 48 | Community leaders have the right and responsibility to remove, edit, or reject 49 | comments, commits, code, wiki edits, issues, and other contributions that are 50 | not aligned to this Code of Conduct, and will communicate reasons for moderation 51 | decisions when appropriate. 52 | 53 | ## Scope 54 | 55 | This Code of Conduct applies within all community spaces, and also applies when 56 | an individual is officially representing the community in public spaces. 57 | Examples of representing our community include using an official e-mail address, 58 | posting via an official social media account, or acting as an appointed 59 | representative at an online or offline event. 60 | 61 | ## Enforcement 62 | 63 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 64 | reported to the community leaders responsible for enforcement at 65 | hi@zed.dev. 66 | All complaints will be reviewed and investigated promptly and fairly. 67 | 68 | All community leaders are obligated to respect the privacy and security of the 69 | reporter of any incident. 70 | 71 | ## Enforcement Guidelines 72 | 73 | Community leaders will follow these Community Impact Guidelines in determining 74 | the consequences for any action they deem in violation of this Code of Conduct: 75 | 76 | ### 1. Correction 77 | 78 | **Community Impact**: Use of inappropriate language or other behavior deemed 79 | unprofessional or unwelcome in the community. 80 | 81 | **Consequence**: A private, written warning from community leaders, providing 82 | clarity around the nature of the violation and an explanation of why the 83 | behavior was inappropriate. A public apology may be requested. 84 | 85 | ### 2. Warning 86 | 87 | **Community Impact**: A violation through a single incident or series 88 | of actions. 89 | 90 | **Consequence**: A warning with consequences for continued behavior. No 91 | interaction with the people involved, including unsolicited interaction with 92 | those enforcing the Code of Conduct, for a specified period of time. This 93 | includes avoiding interactions in community spaces as well as external channels 94 | like social media. Violating these terms may lead to a temporary or 95 | permanent ban. 96 | 97 | ### 3. Temporary Ban 98 | 99 | **Community Impact**: A serious violation of community standards, including 100 | sustained inappropriate behavior. 101 | 102 | **Consequence**: A temporary ban from any sort of interaction or public 103 | communication with the community for a specified period of time. No public or 104 | private interaction with the people involved, including unsolicited interaction 105 | with those enforcing the Code of Conduct, is allowed during this period. 106 | Violating these terms may lead to a permanent ban. 107 | 108 | ### 4. Permanent Ban 109 | 110 | **Community Impact**: Demonstrating a pattern of violation of community 111 | standards, including sustained inappropriate behavior, harassment of an 112 | individual, or aggression toward or disparagement of classes of individuals. 113 | 114 | **Consequence**: A permanent ban from any sort of public interaction within 115 | the community. 116 | 117 | ## Attribution 118 | 119 | [homepage]: https://www.contributor-covenant.org 120 | 121 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 122 | version 2.0, available at 123 | [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html). 124 | 125 | Community Impact Guidelines were inspired by [Mozilla's code of conduct 126 | enforcement ladder](https://github.com/mozilla/diversity). 127 | 128 | For answers to common questions about this code of conduct, see [the Contributor Covenant FAQ](https://www.contributor-covenant.org/faq). 129 | For translations, see [Contributor Covenant Translations](https://www.contributor-covenant.org/translations). 130 | -------------------------------------------------------------------------------- /docs/community/communication.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Contributor Communication" 3 | description: "Communication methods for Agent Client Protocol contributors" 4 | --- 5 | 6 | This document explains how to communicate and collaborate within the Agent Client Protocol (ACP) project. 7 | 8 | ## Communication Channels 9 | 10 | In short: 11 | 12 | - **[Zulip](https://agentclientprotocol.zulipchat.com/)**: For real-time or ad-hoc discussions. 13 | - **[RFDs](https://agentclientprotocol.com/rfds/about)**: For proposed changes to the specification. 14 | - **[GitHub Discussions](https://github.com/orgs/agentclientprotocol/discussions)**: For structured, longer-form discussions. 15 | - **[GitHub Issues](https://github.com/agentclientprotocol/agent-client-protocol/issues)**: For actionable tasks, bug reports, and feature requests. 16 | 17 | 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. 18 | 19 | ### Zulip 20 | 21 | 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. 22 | 23 | The Zulip server will have both public and private channels. 24 | 25 | [Join the Zulip here](https://agentclientprotocol.zulipchat.com/). 26 | 27 | #### Public Channels (Default) 28 | 29 | - **Purpose**: Open community engagement, collaborative development, and transparent project coordination. 30 | - Primary use cases: 31 | - **Public SDK and tooling development** 32 | - **Community onboarding** and contribution guidance. 33 | - **Community feedback** and collaborative brainstorming. 34 | - Avoid: 35 | - ACP user support: participants are expected to read official documentation and start new GitHub Discussions for questions or support. 36 | - 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. 37 | 38 | #### Private channels (Exceptions) 39 | 40 | - **Purpose**: Confidential coordination and sensitive matters that cannot be discussed publicly. Access will be restricted to designated maintainers. 41 | - **Strict criteria for private use**: 42 | - **Security incidents** (CVEs, protocol vulnerabilities). 43 | - **People matters** (maintainer-related discussions, code of conduct policies). 44 | - Select channels will be configured to be **read-only**. This can be good for example for maintainer decision making. 45 | - Coordination requiring **immediate** or otherwise **focused response** with a limited audience. 46 | - **Transparency**: 47 | - **All technical and governance decisions** affecting the community **must be documented** in RFDs, GitHub Discussions and/or Issues. 48 | - **Some matters related to individual contributors** may remain private when appropriate (e.g., personal circumstances, disciplinary actions, or other sensitive individual matters). 49 | - Private channels are to be used as **temporary "incident rooms,"** not for routine development. 50 | 51 | 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. 52 | 53 | ### RFDs 54 | 55 | 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. 56 | 57 | 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. 58 | 59 | ### GitHub Discussions 60 | 61 | For structured, long-form discussion and debate on project direction, features, improvements, and community topics. 62 | 63 | When to use: 64 | 65 | - Announcements and release communications 66 | - Community polls and consensus-building processes 67 | - Feature requests with context and rationale 68 | - If a particular repository does not have GitHub Discussions enabled, feel free to open a GitHub Issue instead. 69 | 70 | ### GitHub Issues 71 | 72 | For bug reports, feature tracking, and actionable development tasks. 73 | 74 | When to use: 75 | 76 | - Bug reports with reproducible steps 77 | - Documentation improvements with specific scope 78 | - CI/CD problems and infrastructure issues 79 | - Release tasks and milestone tracking 80 | 81 | ### Security Issues 82 | 83 | **Do not post security issues publicly.** Instead: 84 | 85 | 1. Contact lead and/or core maintainers, or hi@zed.dev directly. 86 | 2. Follow responsible disclosure guidelines. 87 | -------------------------------------------------------------------------------- /docs/community/contributing.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Contributing" 3 | description: "How to participate in the development of ACP" 4 | --- 5 | 6 | We welcome contributions from the community! 7 | 8 | All contributors must adhere to our [Code of Conduct](./code-of-conduct). 9 | 10 | For questions and discussions, please use GitHub Discussions. 11 | -------------------------------------------------------------------------------- /docs/community/working-interest-groups.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Working and Interest Groups" 3 | description: "Learn about the two forms of collaborative groups within the Agent Client Protocol's governance structure - Working Groups and Interest Groups." 4 | --- 5 | 6 | Within the ACP contributor community we maintain two types of collaboration formats - **Interest** and **Working** groups. 7 | 8 | **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. 9 | 10 | 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. 11 | 12 | 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. 13 | 14 | Long-term projects in the ACP ecosystem, such as SDKs or other components are maintained by dedicated Working Groups. 15 | 16 | ## Purpose 17 | 18 | These groups exist to: 19 | 20 | - **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. 21 | - **Establish clear expectations and leadership roles** - guide collaborative efforts and ensure steady progress toward concrete deliverables that advance ACP evolution and adoption. 22 | 23 | ## Mechanisms 24 | 25 | ## Meeting Calendar 26 | 27 | All Interest Group and Working Group meetings are published on the public ACP community calendar (work in progress). 28 | 29 | Facilitators are responsible for posting their meeting schedules to this calendar in advance to ensure discoverability and enable broader community participation. 30 | 31 | ### Interest Groups (IGs) 32 | 33 | **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. 34 | 35 | **Expectations**: 36 | 37 | - Regular conversations in the Interest Group Zulip channel 38 | - **AND/OR** a recurring live meeting regularly attended by Interest Group members 39 | - 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 40 | - Notes publicly shared after meetings, and submitted to the [meetings repository](https://github.com/agentclientprotocol/meetings) 41 | 42 | **Lifecycle**: 43 | 44 | - Creation begins by proposing a new Interest Group to the core/lead maintainers with the template below 45 | - Majority positive vote by core maintainers over a 72h period approves creation of the group. 46 | - The creation of the group can be reversed at any time (e.g., after new information surfaces). Core and lead maintainers can veto. 47 | - Facilitator(s) and Maintainer(s) responsible for organizing IG into meeting expectations 48 | - Facilitator is an informal role responsible for shepherding or speaking for a group 49 | - 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. 50 | - IG is retired only when Core or Lead Maintainers determine it's no longer active and/or needed 51 | - Successful IGs do not have a time limit or expiration date - as long as they are active and maintained, they will remain available 52 | 53 | **Creation Template**: 54 | 55 | - Facilitator(s) 56 | - Maintainer(s) (optional) 57 | - IGs with potentially similar goals/discussions 58 | - How this IG differentiates itself from the related IGs 59 | - First topic you to discuss within the IG 60 | 61 | 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. 62 | 63 | ### Working Groups (WG) 64 | 65 | **Goal:** Facilitate collaboration within the ACP community on a RFD, a themed series of RFDs, or an otherwise officially endorsed project. 66 | 67 | **Expectations**: 68 | 69 | - Meaningful progress towards at least one RFD or spec-related implementation **OR** hold maintenance responsibilities for a project (e.g., SDKs) 70 | - Facilitators are responsible for keeping track of progress and communicating status when appropriate 71 | - 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 72 | - Notes publicly shared after meetings, and submitted to the [meetings repository](https://github.com/agentclientprotocol/meetings) 73 | 74 | **Lifecycle**: 75 | 76 | - Creation begins by proposing a new Interest Group to the core/lead maintainers with the template below 77 | - Majority positive vote by core maintainers over a 72h period approves creation of the group. 78 | - The creation of the group can be reversed at any time (e.g., after new information surfaces). Core and lead maintainers can veto. 79 | - Facilitator(s) and Maintainer(s) responsible for organizing WG into meeting expectations 80 | - Facilitator is an informal role responsible for shepherding or speaking for a group 81 | - 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 82 | - WG is retired when either: 83 | - Community moderators or Core and Lead Maintainers decide it is no longer active and/or needed 84 | - The WG no longer has an active Issue/PR for a month or more, or has completed all Issues/PRs it intended to pursue. 85 | 86 | **Creation Template**: 87 | 88 | - Facilitator(s) 89 | - Maintainer(s) (optional) 90 | - Explanation of interest/use cases, ideally originating from an IG discussion; however that is not a requirement 91 | - First Issue/PR/RFD that the WG will work on 92 | 93 | ## WG/IG Facilitators 94 | 95 | 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. 96 | 97 | A Facilitator is responsible for helping shepherd discussions and collaboration within an Interest or Working Group. 98 | 99 | Lead and Core Maintainers reserve the right to modify the list of Facilitators and Maintainers for any WG/IG at any time. 100 | 101 | ## FAQ 102 | 103 | ### How do I get involved contributing to ACP? 104 | 105 | These IG and WG abstractions help provide an elegant on-ramp: 106 | 107 | 1. [Join the Zulip](/community/communication#zulip) and follow conversations in IGs relevant to you. Attend live calls. Participate. 108 | 2. Offer to facilitate calls. Contribute your use cases in RFD proposals and other work. 109 | 3. When you're comfortable contributing to deliverables, jump in to contribute to WG work. 110 | 4. Active and valuable contributors will be nominated by WG maintainers as new maintainers. 111 | 112 | ### Where can I find a list of all current WGs and IGs? 113 | 114 | On the [ACP Zulip Chat](/community/communication#zulip) there is a section of channels for each Working and Interest Group. 115 | -------------------------------------------------------------------------------- /docs/docs.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://mintlify.com/docs.json", 3 | "theme": "maple", 4 | "name": "Agent Client Protocol", 5 | "description": "The Agent Client Protocol (ACP) is a protocol that standardizes communication between code editors.", 6 | "colors": { 7 | "primary": "#0084d1", 8 | "light": "#00bcff", 9 | "dark": "#0084d1" 10 | }, 11 | "background": { 12 | "color": { 13 | "light": "#f8f8f6", 14 | "dark": "#12141A" 15 | } 16 | }, 17 | "fonts": { 18 | "heading": { 19 | "family": "Lora", 20 | "format": "woff2" 21 | }, 22 | "body": { 23 | "family": "Public Sans", 24 | "format": "woff2" 25 | } 26 | }, 27 | "favicon": { 28 | "light": "/logo/fav-light.png", 29 | "dark": "/logo/fav-dark.png" 30 | }, 31 | "navbar": { 32 | "links": [ 33 | { 34 | "label": "GitHub", 35 | "href": "https://github.com/agentclientprotocol/agent-client-protocol" 36 | }, 37 | { 38 | "label": "Zed Industries", 39 | "href": "https://zed.dev" 40 | } 41 | ] 42 | }, 43 | "navigation": { 44 | "tabs": [ 45 | { 46 | "tab": "Protocol", 47 | "pages": [ 48 | { 49 | "group": "Overview", 50 | "pages": [ 51 | "overview/introduction", 52 | "overview/architecture", 53 | "overview/agents", 54 | "overview/clients" 55 | ] 56 | }, 57 | { 58 | "group": "Protocol", 59 | "pages": [ 60 | "protocol/overview", 61 | "protocol/initialization", 62 | "protocol/session-setup", 63 | "protocol/prompt-turn", 64 | "protocol/content", 65 | "protocol/tool-calls", 66 | "protocol/file-system", 67 | "protocol/terminals", 68 | "protocol/agent-plan", 69 | "protocol/session-modes", 70 | "protocol/slash-commands", 71 | "protocol/extensibility", 72 | "protocol/transports", 73 | "protocol/schema" 74 | ] 75 | }, 76 | { 77 | "group": "Libraries", 78 | "pages": [ 79 | "libraries/kotlin", 80 | "libraries/python", 81 | "libraries/rust", 82 | "libraries/typescript", 83 | "libraries/community" 84 | ] 85 | } 86 | ] 87 | }, 88 | { 89 | "tab": "RFDs", 90 | "pages": [ 91 | "rfds/about", 92 | { 93 | "group": "Draft", 94 | "pages": [ 95 | "rfds/session-list", 96 | "rfds/session-config-options", 97 | "rfds/session-fork", 98 | "rfds/request-cancellation", 99 | "rfds/session-resume" 100 | ] 101 | }, 102 | { "group": "Preview", "pages": [] }, 103 | { "group": "Completed", "pages": ["rfds/introduce-rfd-process"] } 104 | ] 105 | }, 106 | { 107 | "tab": "Community", 108 | "pages": [ 109 | "community/communication", 110 | "community/code-of-conduct", 111 | "community/governance", 112 | "community/working-interest-groups", 113 | "community/contributing" 114 | ] 115 | }, 116 | { 117 | "tab": "Updates", 118 | "pages": ["updates"] 119 | }, 120 | { 121 | "tab": "Brand", 122 | "pages": ["brand"] 123 | } 124 | ] 125 | }, 126 | "logo": { 127 | "light": "/logo/light.svg", 128 | "dark": "/logo/dark.svg" 129 | }, 130 | "seo": { 131 | "metatags": { 132 | "og:image": "https://zed.dev/img/acp/og-dark.webp" 133 | }, 134 | "indexing": "navigable" 135 | }, 136 | "footer": { 137 | "socials": { 138 | "github": "https://github.com/agentclientprotocol/agent-client-protocol" 139 | } 140 | }, 141 | "contextual": { 142 | "options": ["copy", "view"] 143 | } 144 | } 145 | -------------------------------------------------------------------------------- /docs/images/architecture-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/21a8206c1304b602c50c32a75a33afd7462c2853/docs/images/architecture-diagram.png -------------------------------------------------------------------------------- /docs/images/mcp-proxy.d2: -------------------------------------------------------------------------------- 1 | 'Code Editor': {near: top-center} 2 | 3 | 'MCP Proxy': {near: center-left} 4 | # 'MCP Server ...': { 5 | # near: center-right 6 | # style: { 7 | # stroke-dash: 3 8 | # } 9 | # } 10 | " ---------------------------------------------- ": { 11 | style: { 12 | fill: transparent 13 | font-color: transparent 14 | stroke-width: 0 15 | } 16 | } 17 | 18 | # Bottom row: Agent 19 | Agent: {near: bottom-center} 20 | 21 | # Connections 22 | 'Code Editor' -> Agent: MCP Proxy Configuration { 23 | style: { 24 | stroke-dash: 3 25 | } 26 | } 27 | 28 | # The agent connects up to the MCP servers 29 | Agent <-> 'MCP Proxy': MCP over stdio {direction: up} 30 | 'MCP Proxy' <-> 'Code Editor': MCP over socket { 31 | style: { 32 | stroke-dash: 3 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /docs/images/mcp.d2: -------------------------------------------------------------------------------- 1 | 'Code Editor': {near: top-center} 2 | 3 | 'MCP Server 1': {near: center-left} 4 | 'MCP Server ...': { 5 | near: center-right 6 | style: { 7 | stroke-dash: 3 8 | } 9 | } 10 | " ----------------------- ": { 11 | style: { 12 | fill: transparent 13 | font-color: transparent 14 | stroke-width: 0 15 | } 16 | } 17 | 18 | # Bottom row: Agent 19 | Agent: {near: bottom-center} 20 | 21 | # Connections 22 | 'Code Editor' -> Agent: MCP Configuration {direction: down} 23 | 24 | # The agent connects up to the MCP servers 25 | Agent -> 'MCP Server 1': MCP {direction: up} 26 | Agent -> 'MCP Server ...': MCP { 27 | style: { 28 | stroke-dash: 3 29 | } 30 | } 31 | -------------------------------------------------------------------------------- /docs/images/server-client.d2: -------------------------------------------------------------------------------- 1 | # file generated by putting this code into https://play.d2lang.com/ 2 | # and setting theme to Earth tones 3 | Code Editor -> agent1: stdio 4 | agent1: Agent 1 5 | Code Editor -> agent2: stdio 6 | agent2: Agent 2 7 | 8 | Code Editor -> "...": { 9 | style: { 10 | stroke-dash: 3 11 | } 12 | } 13 | "...": { 14 | style: { 15 | stroke-dash: 3 16 | } 17 | } 18 | -------------------------------------------------------------------------------- /docs/libraries/community.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Community" 3 | description: "Community managed libraries for the Agent Client Protocol" 4 | --- 5 | 6 | ## Dart 7 | 8 | - [acp_dart](https://github.com/SkrOYC/acp-dart) 9 | 10 | ## Emacs 11 | 12 | - [acp.el](https://github.com/xenodium/acp.el) 13 | 14 | ## Go 15 | 16 | - [acp-go-sdk](https://github.com/coder/acp-go-sdk) 17 | 18 | ## React 19 | 20 | - [use-acp](https://github.com/marimo-team/use-acp) 21 | -------------------------------------------------------------------------------- /docs/libraries/kotlin.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kotlin" 3 | description: "Kotlin library for the Agent Client Protocol" 4 | --- 5 | 6 | The [kotlin-sdk](https://github.com/agentclientprotocol/kotlin-sdk) provides implementations of both sides of the Agent Client Protocol that 7 | you can use to build your own agent server or client. 8 | 9 | **It currently supports JVM, other targets are in progress.** 10 | 11 | To get started, add the repository to your build file: 12 | 13 | ```kotlin 14 | repositories { 15 | mavenCentral() 16 | } 17 | ``` 18 | 19 | Add the dependency: 20 | 21 | ```kotlin 22 | dependencies { 23 | implementation("com.agentclientprotocol:acp:0.1.0-SNAPSHOT") 24 | } 25 | ``` 26 | 27 | The [sample](https://github.com/agentclientprotocol/kotlin-sdk/tree/master/samples/kotlin-acp-client-sample) demonstrates how to implement both sides of the protocol. 28 | -------------------------------------------------------------------------------- /docs/libraries/python.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Python" 3 | description: "Python library for the Agent Client Protocol" 4 | --- 5 | 6 | The [agentclientprotocol/python-sdk](https://github.com/agentclientprotocol/python-sdk) 7 | repository packages Pydantic models, async base classes, and JSON-RPC plumbing 8 | so you can build ACP-compatible agents and clients in Python. It mirrors the 9 | official ACP schema and ships helper utilities for both sides of the protocol. 10 | 11 | To get started, add the SDK to your project: 12 | 13 | ```bash 14 | pip install agent-client-protocol 15 | ``` 16 | 17 | (Using [uv](https://github.com/astral-sh/uv)? Run `uv add agent-client-protocol`.) 18 | 19 | The repository includes runnable examples for agents, clients, Gemini CLI 20 | bridges, and dual-agent/client demos under 21 | [`examples/`](https://github.com/agentclientprotocol/python-sdk/tree/main/examples). 22 | 23 | Browse the full documentation—including the quickstart, contrib helpers, and API 24 | reference—at 25 | [agentclientprotocol.github.io/python-sdk](https://agentclientprotocol.github.io/python-sdk/). 26 | -------------------------------------------------------------------------------- /docs/libraries/rust.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Rust" 3 | description: "Rust library for the Agent Client Protocol" 4 | --- 5 | 6 | The [agent-client-protocol](https://crates.io/crates/agent-client-protocol) Rust 7 | crate provides implementations of both sides of the Agent Client Protocol that 8 | you can use to build your own agent server or client. 9 | 10 | To get started, add the crate as a dependency to your project's `Cargo.toml`: 11 | 12 | ```bash 13 | cargo add agent-client-protocol 14 | ``` 15 | 16 | Depending on what kind of tool you're building, you'll need to implement either 17 | the 18 | [Agent](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/trait.Agent.html) 19 | trait or the 20 | [Client](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/trait.Client.html) 21 | trait to define the interaction with the ACP counterpart. 22 | 23 | The 24 | [agent](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/agent.rs) 25 | and 26 | [client](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/client.rs) 27 | example binaries provide runnable examples of how to do this, which you can use 28 | as a starting point. 29 | 30 | You can read the full documentation for the `agent-client-protocol` crate on 31 | [docs.rs](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/). 32 | 33 | ## Users 34 | 35 | The `agent-client-protocol` crate powers the integration with external agents in 36 | the [Zed](https://zed.dev) editor. 37 | -------------------------------------------------------------------------------- /docs/libraries/typescript.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "TypeScript" 3 | description: "TypeScript library for the Agent Client Protocol" 4 | --- 5 | 6 | The [@agentclientprotocol/sdk](https://www.npmjs.com/package/@agentclientprotocol/sdk) npm 7 | package provides implementations of both sides of the Agent Client Protocol that 8 | you can use to build your own agent server or client. 9 | 10 | To get started, add the package as a dependency to your project: 11 | 12 | ```bash 13 | npm install @agentclientprotocol/sdk 14 | ``` 15 | 16 | Depending on what kind of tool you're building, you'll need to use either the 17 | [AgentSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/AgentSideConnection.html) 18 | class or the 19 | [ClientSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/ClientSideConnection.html) 20 | class to establish communication with the ACP counterpart. 21 | 22 | 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! 23 | 24 | Browse the [TypeScript library reference](https://agentclientprotocol.github.io/typescript-sdk) for detailed API documentation. 25 | 26 | 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). 27 | -------------------------------------------------------------------------------- /docs/logo/dark.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /docs/logo/fav-dark.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/21a8206c1304b602c50c32a75a33afd7462c2853/docs/logo/fav-dark.png -------------------------------------------------------------------------------- /docs/logo/fav-light.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/21a8206c1304b602c50c32a75a33afd7462c2853/docs/logo/fav-light.png -------------------------------------------------------------------------------- /docs/logo/light.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /docs/overview/agents.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Agents" 3 | description: "Agents implementing the Agent Client Protocol" 4 | --- 5 | 6 | The following agents can be used with an ACP Client: 7 | 8 | - [Augment Code](https://docs.augmentcode.com/cli/acp) 9 | - [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) (via [Zed's SDK adapter](https://github.com/zed-industries/claude-code-acp)) 10 | - [Codex CLI](https://developers.openai.com/codex/cli) (via [Zed's adapter](https://github.com/zed-industries/codex-acp)) 11 | - [Code Assistant](https://github.com/stippi/code-assistant?tab=readme-ov-file#configuration) 12 | - [Docker's cagent](https://github.com/docker/cagent) 13 | - [fast-agent](https://fast-agent.ai/acp) 14 | - [Gemini CLI](https://github.com/google-gemini/gemini-cli) 15 | - [Goose](https://block.github.io/goose/docs/guides/acp-clients) 16 | - [JetBrains Junie _(coming soon)_](https://www.jetbrains.com/junie/) 17 | - [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) 18 | - [LLMling-Agent](https://phil65.github.io/llmling-agent/advanced/acp_integration/) 19 | - [OpenCode](https://github.com/sst/opencode) 20 | - [Stakpak](https://github.com/stakpak/agent?tab=readme-ov-file#agent-client-protocol-acp) 21 | - [VT Code](https://github.com/vinhnx/vtcode/blob/main/README.md#zed-ide-integration-agent-client-protocol) 22 | -------------------------------------------------------------------------------- /docs/overview/architecture.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Architecture" 3 | description: "Overview of the Agent Client Protocol architecture" 4 | --- 5 | 6 | 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. 7 | 8 | ## Design Philosophy 9 | 10 | The protocol architecture follows several key principles: 11 | 12 | 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. 13 | 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. 14 | 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. 15 | 16 | ## Setup 17 | 18 | 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. 19 | 20 | Each connection can support several concurrent sessions, so you can have multiple trains of thought going on at once. 21 | 22 | ![Server Client setup](../images/server-client.svg) 23 | 24 | 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. 25 | 26 | ## MCP 27 | 28 | 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. 29 | 30 | ![MCP Server connection](../images/mcp.svg) 31 | 32 | 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: 33 | 34 | ![MCP connection to self](../images/mcp-proxy.svg) 35 | -------------------------------------------------------------------------------- /docs/overview/clients.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Clients" 3 | description: "Clients implementing the Agent Client Protocol" 4 | --- 5 | 6 | The following clients can be used with an ACP Agent: 7 | 8 | - [AionUi](https://github.com/iOfficeAI/AionUi) 9 | - [aizen](https://aizen.win) 10 | - [DeepChat](https://github.com/ThinkInAIXYZ/deepchat) 11 | - Emacs via [agent-shell.el](https://github.com/xenodium/agent-shell) 12 | - [JetBrains _(coming soon)_](https://blog.jetbrains.com/ai/2025/10/jetbrains-zed-open-interoperability-for-ai-coding-agents-in-your-ide/) 13 | - [marimo notebook](https://github.com/marimo-team/marimo) 14 | - [neovim](https://neovim.io) 15 | - through the [CodeCompanion](https://github.com/olimorris/codecompanion.nvim) plugin 16 | - through the [yetone/avante.nvim](https://github.com/yetone/avante.nvim) plugin 17 | - [Obsidian](https://obsidian.md) 18 | - through the [Agent Client](https://github.com/RAIT-09/obsidian-agent-client) plugin 19 | - [Sidequery _(coming soon)_](https://sidequery.dev) 20 | - [Tidewave](https://tidewave.ai/) 21 | - [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)) 22 | - [Zed](https://zed.dev/docs/ai/external-agents) 23 | -------------------------------------------------------------------------------- /docs/overview/introduction.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Introduction" 3 | description: "Get started with the Agent Client Protocol (ACP)" 4 | --- 5 | 6 | The Agent Client Protocol standardizes communication between code editors/IDEs, and coding agents (programs that use generative AI to autonomously modify code). 7 | 8 | ## Why ACP? 9 | 10 | 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. 11 | This creates several problems: 12 | 13 | - Integration overhead: Every new agent-editor combination requires custom work 14 | - Limited compatibility: Agents work with only a subset of available editors 15 | - Developer lock-in: Choosing an agent often means accepting their available interfaces 16 | 17 | 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. 18 | 19 | Agents that implement ACP work with any compatible editor. Editors that support ACP gain access to the entire ecosystem of ACP-compatible agents. 20 | This decoupling allows both sides to innovate independently while giving developers the freedom to choose the best tools for their workflow. 21 | 22 | ## Overview 23 | 24 | ACP assumes that the user is primarily in their editor, and wants to reach out and use agents to assist them with specific tasks. 25 | 26 | Agents run as sub-processes of the code editor, and communicate using JSON-RPC over stdio. 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. 27 | 28 | 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. 29 | -------------------------------------------------------------------------------- /docs/protocol/agent-plan.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Agent Plan" 3 | description: "How Agents communicate their execution plans" 4 | --- 5 | 6 | Plans are execution strategies for complex tasks that require multiple steps. 7 | 8 | Agents may share plans with Clients through [`session/update`](./prompt-turn#3-agent-reports-output) notifications, providing real-time visibility into their thinking and progress. 9 | 10 | ## Creating Plans 11 | 12 | When the language model creates an execution plan, the Agent **SHOULD** report it to the Client: 13 | 14 | ```json 15 | { 16 | "jsonrpc": "2.0", 17 | "method": "session/update", 18 | "params": { 19 | "sessionId": "sess_abc123def456", 20 | "update": { 21 | "sessionUpdate": "plan", 22 | "entries": [ 23 | { 24 | "content": "Analyze the existing codebase structure", 25 | "priority": "high", 26 | "status": "pending" 27 | }, 28 | { 29 | "content": "Identify components that need refactoring", 30 | "priority": "high", 31 | "status": "pending" 32 | }, 33 | { 34 | "content": "Create unit tests for critical functions", 35 | "priority": "medium", 36 | "status": "pending" 37 | } 38 | ] 39 | } 40 | } 41 | } 42 | ``` 43 | 44 | 45 | An array of [plan entries](#plan-entries) representing the tasks to be 46 | accomplished 47 | 48 | 49 | ## Plan Entries 50 | 51 | Each plan entry represents a specific task or goal within the overall execution strategy: 52 | 53 | 54 | A human-readable description of what this task aims to accomplish 55 | 56 | 57 | 58 | The relative importance of this task. 59 | 60 | - `high` 61 | - `medium` 62 | - `low` 63 | 64 | 65 | 66 | 67 | The current [execution status](#status) of this task 68 | 69 | - `pending` 70 | - `in_progress` 71 | - `completed` 72 | 73 | 74 | 75 | ## Updating Plans 76 | 77 | As the Agent progresses through the plan, it **SHOULD** report updates by sending more `session/update` notifications with the same structure. 78 | 79 | 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. 80 | 81 | ### Dynamic Planning 82 | 83 | 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. 84 | -------------------------------------------------------------------------------- /docs/protocol/content.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Content" 3 | description: "Understanding content blocks in the Agent Client Protocol" 4 | --- 5 | 6 | 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. 7 | 8 | Content blocks appear in: 9 | 10 | - User prompts sent via [`session/prompt`](./prompt-turn#1-user-message) 11 | - Language model output streamed through [`session/update`](./prompt-turn#3-agent-reports-output) notifications 12 | - Progress updates and results from [tool calls](./tool-calls) 13 | 14 | ## Content Types 15 | 16 | The Agent Client Protocol uses the same `ContentBlock` structure as the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification/2025-06-18/schema#contentblock). 17 | 18 | This design choice enables Agents to seamlessly forward content from MCP tool outputs without transformation. 19 | 20 | ### Text Content 21 | 22 | Plain text messages form the foundation of most interactions. 23 | 24 | ```json 25 | { 26 | "type": "text", 27 | "text": "What's the weather like today?" 28 | } 29 | ``` 30 | 31 | All Agents **MUST** support text content blocks when included in prompts. 32 | 33 | 34 | The text content to display 35 | 36 | 37 | 38 | Optional metadata about how the content should be used or displayed. [Learn 39 | more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). 40 | 41 | 42 | ### Image Content 43 | 44 | Images can be included for visual context or analysis. 45 | 46 | ```json 47 | { 48 | "type": "image", 49 | "mimeType": "image/png", 50 | "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..." 51 | } 52 | ``` 53 | 54 | Requires the `image` [prompt 55 | capability](./initialization#prompt-capabilities) when included in prompts. 56 | 57 | 58 | Base64-encoded image data 59 | 60 | 61 | 62 | The MIME type of the image (e.g., "image/png", "image/jpeg") 63 | 64 | 65 | 66 | Optional URI reference for the image source 67 | 68 | 69 | 70 | Optional metadata about how the content should be used or displayed. [Learn 71 | more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). 72 | 73 | 74 | ### Audio Content 75 | 76 | Audio data for transcription or analysis. 77 | 78 | ```json 79 | { 80 | "type": "audio", 81 | "mimeType": "audio/wav", 82 | "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAAB..." 83 | } 84 | ``` 85 | 86 | Requires the `audio` [prompt 87 | capability](./initialization#prompt-capabilities) when included in prompts. 88 | 89 | 90 | Base64-encoded audio data 91 | 92 | 93 | 94 | The MIME type of the audio (e.g., "audio/wav", "audio/mp3") 95 | 96 | 97 | 98 | Optional metadata about how the content should be used or displayed. [Learn 99 | more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). 100 | 101 | 102 | ### Embedded Resource 103 | 104 | Complete resource contents embedded directly in the message. 105 | 106 | ```json 107 | { 108 | "type": "resource", 109 | "resource": { 110 | "uri": "file:///home/user/script.py", 111 | "mimeType": "text/x-python", 112 | "text": "def hello():\n print('Hello, world!')" 113 | } 114 | } 115 | ``` 116 | 117 | This is the preferred way to include context in prompts, such as when using @-mentions to reference files or other resources. 118 | 119 | By embedding the content directly in the request, Clients can include context from sources that the Agent may not have direct access to. 120 | 121 | Requires the `embeddedContext` [prompt 122 | capability](./initialization#prompt-capabilities) when included in prompts. 123 | 124 | 125 | The embedded resource contents, which can be either: 126 | 127 | 128 | 129 | The URI identifying the resource 130 | 131 | 132 | 133 | The text content of the resource 134 | 135 | 136 | 137 | Optional MIME type of the text content 138 | 139 | 140 | 141 | 142 | 143 | 144 | The URI identifying the resource 145 | 146 | 147 | 148 | Base64-encoded binary data 149 | 150 | 151 | 152 | Optional MIME type of the blob 153 | 154 | 155 | 156 | 157 | 158 | 159 | Optional metadata about how the content should be used or displayed. [Learn 160 | more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). 161 | 162 | 163 | ### Resource Link 164 | 165 | References to resources that the Agent can access. 166 | 167 | ```json 168 | { 169 | "type": "resource_link", 170 | "uri": "file:///home/user/document.pdf", 171 | "name": "document.pdf", 172 | "mimeType": "application/pdf", 173 | "size": 1024000 174 | } 175 | ``` 176 | 177 | 178 | The URI of the resource 179 | 180 | 181 | 182 | A human-readable name for the resource 183 | 184 | 185 | 186 | The MIME type of the resource 187 | 188 | 189 | 190 | Optional display title for the resource 191 | 192 | 193 | 194 | Optional description of the resource contents 195 | 196 | 197 | 198 | Optional size of the resource in bytes 199 | 200 | 201 | 202 | Optional metadata about how the content should be used or displayed. [Learn 203 | more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). 204 | 205 | -------------------------------------------------------------------------------- /docs/protocol/error.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Error" 3 | description: "Error handling in the Agent Client Protocol" 4 | --- 5 | 6 | _Documentation coming soon_ 7 | -------------------------------------------------------------------------------- /docs/protocol/extensibility.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Extensibility" 3 | description: "Adding custom data and capabilities" 4 | --- 5 | 6 | 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. 7 | 8 | ## The `_meta` Field 9 | 10 | All types in the protocol include a `_meta` field 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. 11 | 12 | ```json 13 | { 14 | "jsonrpc": "2.0", 15 | "id": 1, 16 | "method": "session/prompt", 17 | "params": { 18 | "sessionId": "sess_abc123def456", 19 | "prompt": [ 20 | { 21 | "type": "text", 22 | "text": "Hello, world!" 23 | } 24 | ], 25 | "_meta": { 26 | "zed.dev/debugMode": true 27 | } 28 | } 29 | } 30 | ``` 31 | 32 | 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. 33 | 34 | ## Extension Methods 35 | 36 | 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. 37 | 38 | Extension methods follow standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) semantics: 39 | 40 | - **[Requests](https://www.jsonrpc.org/specification#request_object)** - Include an `id` field and expect a response 41 | - **[Notifications](https://www.jsonrpc.org/specification#notification)** - Omit the `id` field and are one-way 42 | 43 | ### Custom Requests 44 | 45 | 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 (`_`). 46 | 47 | ```json 48 | { 49 | "jsonrpc": "2.0", 50 | "id": 1, 51 | "method": "_zed.dev/workspace/buffers", 52 | "params": { 53 | "language": "rust" 54 | } 55 | } 56 | ``` 57 | 58 | Upon receiving a custom request, implementations **MUST** respond accordingly with the provided `id`: 59 | 60 | ```json 61 | { 62 | "jsonrpc": "2.0", 63 | "id": 1, 64 | "result": { 65 | "buffers": [ 66 | { "id": 0, "path": "/home/user/project/src/main.rs" }, 67 | { "id": 1, "path": "/home/user/project/src/editor.rs" } 68 | ] 69 | } 70 | } 71 | ``` 72 | 73 | If the receiving end doesn't recognize the custom method name, it should respond with the standard "Method not found" error: 74 | 75 | ```json 76 | { 77 | "jsonrpc": "2.0", 78 | "id": 1, 79 | "error": { 80 | "code": -32601, 81 | "message": "Method not found" 82 | } 83 | } 84 | ``` 85 | 86 | To avoid such cases, extensions **SHOULD** advertise their [custom capabilities](#advertising-custom-capabilities) so that callers can check their availability first and adapt their behavior or interface accordingly. 87 | 88 | ### Custom Notifications 89 | 90 | Custom notifications are regular JSON-RPC notifications that start with an underscore (`_`). Like all notifications, they omit the `id` field: 91 | 92 | ```json 93 | { 94 | "jsonrpc": "2.0", 95 | "method": "_zed.dev/file_opened", 96 | "params": { 97 | "path": "/home/user/project/src/editor.rs" 98 | } 99 | } 100 | ``` 101 | 102 | Unlike with custom requests, implementations **SHOULD** ignore unrecognized notifications. 103 | 104 | ## Advertising Custom Capabilities 105 | 106 | Implementations **SHOULD** use the `_meta` field in capability objects to advertise support for extensions and their methods: 107 | 108 | ```json 109 | { 110 | "jsonrpc": "2.0", 111 | "id": 0, 112 | "result": { 113 | "protocolVersion": 1, 114 | "agentCapabilities": { 115 | "loadSession": true, 116 | "_meta": { 117 | "zed.dev": { 118 | "workspace": true, 119 | "fileNotifications": true 120 | } 121 | } 122 | } 123 | } 124 | } 125 | ``` 126 | 127 | This allows implementations to negotiate custom features during initialization without breaking compatibility with standard Clients and Agents. 128 | -------------------------------------------------------------------------------- /docs/protocol/file-system.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "File System" 3 | description: "Client filesystem access methods" 4 | --- 5 | 6 | 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. 7 | 8 | ## Checking Support 9 | 10 | Before attempting to use filesystem methods, Agents **MUST** verify that the Client supports these capabilities by checking the [Client Capabilities](./initialization#client-capabilities) field in the `initialize` response: 11 | 12 | ```json highlight={8,9} 13 | { 14 | "jsonrpc": "2.0", 15 | "id": 0, 16 | "result": { 17 | "protocolVersion": 1, 18 | "clientCapabilities": { 19 | "fs": { 20 | "readTextFile": true, 21 | "writeTextFile": true 22 | } 23 | } 24 | } 25 | } 26 | ``` 27 | 28 | If `readTextFile` or `writeTextFile` is `false` or not present, the Agent **MUST NOT** attempt to call the corresponding filesystem method. 29 | 30 | ## Reading Files 31 | 32 | The `fs/read_text_file` method allows Agents to read text file contents from the Client's filesystem, including unsaved changes in the editor. 33 | 34 | ```json 35 | { 36 | "jsonrpc": "2.0", 37 | "id": 3, 38 | "method": "fs/read_text_file", 39 | "params": { 40 | "sessionId": "sess_abc123def456", 41 | "path": "/home/user/project/src/main.py", 42 | "line": 10, 43 | "limit": 50 44 | } 45 | } 46 | ``` 47 | 48 | 49 | The [Session ID](./session-setup#session-id) for this request 50 | 51 | 52 | 53 | Absolute path to the file to read 54 | 55 | 56 | 57 | Optional line number to start reading from (1-based) 58 | 59 | 60 | 61 | Optional maximum number of lines to read 62 | 63 | 64 | The Client responds with the file contents: 65 | 66 | ```json 67 | { 68 | "jsonrpc": "2.0", 69 | "id": 3, 70 | "result": { 71 | "content": "def hello_world():\n print('Hello, world!')\n" 72 | } 73 | } 74 | ``` 75 | 76 | ## Writing Files 77 | 78 | The `fs/write_text_file` method allows Agents to write or update text files in the Client's filesystem. 79 | 80 | ```json 81 | { 82 | "jsonrpc": "2.0", 83 | "id": 4, 84 | "method": "fs/write_text_file", 85 | "params": { 86 | "sessionId": "sess_abc123def456", 87 | "path": "/home/user/project/config.json", 88 | "content": "{\n \"debug\": true,\n \"version\": \"1.0.0\"\n}" 89 | } 90 | } 91 | ``` 92 | 93 | 94 | The [Session ID](./session-setup#session-id) for this request 95 | 96 | 97 | 98 | Absolute path to the file to write. 99 | 100 | The Client **MUST** create the file if it doesn't exist. 101 | 102 | 103 | 104 | 105 | The text content to write to the file 106 | 107 | 108 | The Client responds with an empty result on success: 109 | 110 | ```json 111 | { 112 | "jsonrpc": "2.0", 113 | "id": 4, 114 | "result": null 115 | } 116 | ``` 117 | -------------------------------------------------------------------------------- /docs/protocol/initialization.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Initialization" 3 | description: "How all Agent Client Protocol connections begin" 4 | --- 5 | 6 | {/* todo! link to all concepts */} 7 | 8 | The Initialization phase allows [Clients](./overview#client) and [Agents](./overview#agent) to negotiate protocol versions, capabilities, and authentication methods. 9 | 10 |
11 | 12 | ```mermaid 13 | sequenceDiagram 14 | participant Client 15 | participant Agent 16 | 17 | Note over Client, Agent: Connection established 18 | Client->>Agent: initialize 19 | Note right of Agent: Negotiate protocol
version & capabilities 20 | Agent-->>Client: initialize response 21 | Note over Client,Agent: Ready for session setup 22 | ``` 23 | 24 |
25 | 26 | Before a Session can be created, Clients **MUST** initialize the connection by calling the `initialize` method with: 27 | 28 | - The latest [protocol version](#protocol-version) supported 29 | - The [capabilities](#client-capabilities) supported 30 | 31 | They **SHOULD** also provide a name and version to the Agent. 32 | 33 | ```json 34 | { 35 | "jsonrpc": "2.0", 36 | "id": 0, 37 | "method": "initialize", 38 | "params": { 39 | "protocolVersion": 1, 40 | "clientCapabilities": { 41 | "fs": { 42 | "readTextFile": true, 43 | "writeTextFile": true 44 | }, 45 | "terminal": true 46 | }, 47 | "clientInfo": { 48 | "name": "my-client", 49 | "title": "My Client", 50 | "version": "1.0.0" 51 | } 52 | } 53 | } 54 | ``` 55 | 56 | The Agent **MUST** respond with the chosen [protocol version](#protocol-version) and the [capabilities](#agent-capabilities) it supports. It **SHOULD** also provide a name and version to the Client as well: 57 | 58 | ```json 59 | { 60 | "jsonrpc": "2.0", 61 | "id": 0, 62 | "result": { 63 | "protocolVersion": 1, 64 | "agentCapabilities": { 65 | "loadSession": true, 66 | "promptCapabilities": { 67 | "image": true, 68 | "audio": true, 69 | "embeddedContext": true 70 | }, 71 | "mcp": { 72 | "http": true, 73 | "sse": true 74 | } 75 | }, 76 | "agentInfo": { 77 | "name": "my-agent", 78 | "title": "My Agent", 79 | "version": "1.0.0" 80 | }, 81 | "authMethods": [] 82 | } 83 | } 84 | ``` 85 | 86 | ## Protocol version 87 | 88 | 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. 89 | 90 | Clients and Agents **MUST** agree on a protocol version and act according to its specification. 91 | 92 | See [Capabilities](#capabilities) to learn how non-breaking features are introduced. 93 | 94 | ### Version Negotiation 95 | 96 | The `initialize` request **MUST** include the latest protocol version the Client supports. 97 | 98 | 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. 99 | 100 | 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. 101 | 102 | ## Capabilities 103 | 104 | Capabilities describe features supported by the Client and the Agent. 105 | 106 | All capabilities included in the `initialize` request are **OPTIONAL**. Clients and Agents **SHOULD** support all possible combinations of their peer's capabilities. 107 | 108 | 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**. 109 | 110 | Capabilities are high-level and are not attached to a specific base protocol concept. 111 | 112 | 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. 113 | 114 | Implementations can also [advertise custom capabilities](./extensibility#advertising-custom-capabilities) using the `_meta` field to indicate support for protocol extensions. 115 | 116 | ### Client Capabilities 117 | 118 | The Client **SHOULD** specify whether it supports the following capabilities: 119 | 120 | #### File System 121 | 122 | 123 | The `fs/read_text_file` method is available. 124 | 125 | 126 | 127 | The `fs/write_text_file` method is available. 128 | 129 | 130 | 131 | Learn more about File System methods 132 | 133 | 134 | #### Terminal 135 | 136 | 137 | All `terminal/*` methods are available, allowing the Agent to execute and 138 | manage shell commands. 139 | 140 | 141 | 142 | Learn more about Terminals 143 | 144 | 145 | ### Agent Capabilities 146 | 147 | The Agent **SHOULD** specify whether it supports the following capabilities: 148 | 149 | 150 | The [`session/load`](./session-setup#loading-sessions) method is available. 151 | 152 | 153 | 154 | Object indicating the different types of [content](./content) that may be 155 | included in `session/prompt` requests. 156 | 157 | 158 | #### Prompt capabilities 159 | 160 | As a baseline, all Agents **MUST** support `ContentBlock::Text` and `ContentBlock::ResourceLink` in `session/prompt` requests. 161 | 162 | Optionally, they **MAY** support richer types of [content](./content) by specifying the following capabilities: 163 | 164 | 165 | The prompt may include `ContentBlock::Image` 166 | 167 | 168 | 169 | The prompt may include `ContentBlock::Audio` 170 | 171 | 172 | 173 | The prompt may include `ContentBlock::Resource` 174 | 175 | 176 | #### MCP capabilities 177 | 178 | 179 | The Agent supports connecting to MCP servers over HTTP. 180 | 181 | 182 | 183 | The Agent supports connecting to MCP servers over SSE. 184 | 185 | Note: This transport has been deprecated by the MCP spec. 186 | 187 | 188 | 189 | #### Session Capabilities 190 | 191 | As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`. 192 | 193 | Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities. 194 | 195 | 196 | `session/load` is still handled by the top-level `load_session` capability. 197 | This will be unified in future versions of the protocol. 198 | 199 | 200 | ## Implementation Information 201 | 202 | Both Clients and Agents **SHOULD** provide information about their implementation in the `clientInfo` and `agentInfo` fields respectively. Both take the following three fields: 203 | 204 | 205 | Intended for programmatic or logical use, but can be used as a display name 206 | fallback if title isn’t present. 207 | 208 | 209 | 210 | Intended for UI and end-user contexts — optimized to be human-readable and 211 | easily understood. If not provided, the name should be used for display. 212 | 213 | 214 | 215 | Version of the implementation. Can be displayed to the user or used for 216 | debugging or metrics purposes. 217 | 218 | 219 | 220 | Note: in future versions of the protocol, this information will be required. 221 | 222 | 223 | --- 224 | 225 | Once the connection is initialized, you're ready to [create a session](./session-setup) and begin the conversation with the Agent. 226 | -------------------------------------------------------------------------------- /docs/protocol/overview.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Overview" 3 | description: "How the Agent Client Protocol works" 4 | --- 5 | 6 | The Agent Client Protocol allows [Agents](#agent) and [Clients](#client) to communicate by exposing methods that each side can call and sending notifications to inform each other of events. 7 | 8 | ## Communication Model 9 | 10 | The protocol follows the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification with two types of messages: 11 | 12 | - **Methods**: Request-response pairs that expect a result or error 13 | - **Notifications**: One-way messages that don't expect a response 14 | 15 | ## Message Flow 16 | 17 | A typical flow follows this pattern: 18 | 19 | 20 | 21 | 22 | - Client → Agent: `initialize` to establish connection 23 | - Client → Agent: `authenticate` if required by the Agent 24 | 25 | 26 | 27 | 28 | 29 | - Client → Agent: `session/new` to create a new session 30 | - Client → Agent: `session/load` to resume an existing session if supported 31 | 32 | 33 | 34 | 35 | - Client → Agent: `session/prompt` to send user message 36 | - Agent → Client: `session/update` notifications for progress updates 37 | - Agent → Client: File operations or permission requests as needed 38 | - Client → Agent: `session/cancel` to interrupt processing if needed 39 | - Turn ends and the Agent sends the `session/prompt` response with a stop reason 40 | 41 | 42 | 43 | ## Agent 44 | 45 | Agents are programs that use generative AI to autonomously modify code. They typically run as subprocesses of the Client. 46 | 47 | ### Baseline Methods 48 | 49 | Schema]} 52 | > 53 | [Negotiate versions and exchange capabilities.](./initialization). 54 | 55 | 56 | Schema]} 59 | > 60 | Authenticate with the Agent (if required). 61 | 62 | 63 | Schema]} 66 | > 67 | [Create a new conversation session](./session-setup#creating-a-session). 68 | 69 | 70 | Schema]} 73 | > 74 | [Send user prompts](./prompt-turn#1-user-message) to the Agent. 75 | 76 | 77 | ### Optional Methods 78 | 79 | Schema]} 82 | > 83 | [Load an existing session](./session-setup#loading-sessions) (requires 84 | `loadSession` capability). 85 | 86 | 87 | Schema]} 90 | > 91 | [Switch between agent operating 92 | modes](./session-modes#setting-the-current-mode). 93 | 94 | 95 | ### Notifications 96 | 97 | Schema]} 100 | > 101 | [Cancel ongoing operations](./prompt-turn#cancellation) (no response 102 | expected). 103 | 104 | 105 | ## Client 106 | 107 | 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. 108 | 109 | ### Baseline Methods 110 | 111 | Schema]} 114 | > 115 | [Request user authorization](./tool-calls#requesting-permission) for tool 116 | calls. 117 | 118 | 119 | ### Optional Methods 120 | 121 | Schema]} 124 | > 125 | [Read file contents](./file-system#reading-files) (requires `fs.readTextFile` 126 | capability). 127 | 128 | 129 | Schema]} 132 | > 133 | [Write file contents](./file-system#writing-files) (requires 134 | `fs.writeTextFile` capability). 135 | 136 | 137 | Schema]} 140 | > 141 | [Create a new terminal](./terminals) (requires `terminal` capability). 142 | 143 | 144 | Schema]} 147 | > 148 | Get terminal output and exit status (requires `terminal` capability). 149 | 150 | 151 | Schema]} 154 | > 155 | Release a terminal (requires `terminal` capability). 156 | 157 | 158 | Schema]} 161 | > 162 | Wait for terminal command to exit (requires `terminal` capability). 163 | 164 | 165 | Schema]} 168 | > 169 | Kill terminal command without releasing (requires `terminal` capability). 170 | 171 | 172 | ### Notifications 173 | 174 | Schema]} 177 | > 178 | [Send session updates](./prompt-turn#3-agent-reports-output) to inform the 179 | Client of changes (no response expected). This includes: - [Message 180 | chunks](./content) (agent, user, thought) - [Tool calls and 181 | updates](./tool-calls) - [Plans](./agent-plan) - [Available commands 182 | updates](./slash-commands#advertising-commands) - [Mode 183 | changes](./session-modes#from-the-agent) 184 | 185 | 186 | ## Argument requirements 187 | 188 | - All file paths in the protocol **MUST** be absolute. 189 | - Line numbers are 1-based 190 | 191 | ## Error Handling 192 | 193 | All methods follow standard JSON-RPC 2.0 [error handling](https://www.jsonrpc.org/specification#error_object): 194 | 195 | - Successful responses include a `result` field 196 | - Errors include an `error` object with `code` and `message` 197 | - Notifications never receive responses (success or error) 198 | 199 | ## Extensibility 200 | 201 | The protocol provides built-in mechanisms for adding custom functionality while maintaining compatibility: 202 | 203 | - Add custom data using `_meta` fields 204 | - Create custom methods by prefixing their name with underscore (`_`) 205 | - Advertise custom capabilities during initialization 206 | 207 | Learn about [protocol extensibility](./extensibility) to understand how to use these mechanisms. 208 | 209 | ## Next Steps 210 | 211 | - Learn about [Initialization](./initialization) to understand version and capability negotiation 212 | - Understand [Session Setup](./session-setup) for creating and loading sessions 213 | - Review the [Prompt Turn](./prompt-turn) lifecycle 214 | - Explore [Extensibility](./extensibility) to add custom features 215 | -------------------------------------------------------------------------------- /docs/protocol/prompt-turn.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Prompt Turn" 3 | description: "Understanding the core conversation flow" 4 | --- 5 | 6 | A prompt turn represents a complete interaction cycle between the [Client](./overview#client) and [Agent](./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. 7 | 8 | Before sending prompts, Clients **MUST** first complete the [initialization](./initialization) phase and [session setup](./session-setup). 9 | 10 | ## The Prompt Turn Lifecycle 11 | 12 | A prompt turn follows a structured flow that enables rich interactions between the user, Agent, and any connected tools. 13 | 14 |
15 | 16 | ```mermaid 17 | sequenceDiagram 18 | participant Client 19 | participant Agent 20 | 21 | Note over Agent,Client: Session ready 22 | 23 | Note left of Client: User sends message 24 | Client->>Agent: session/prompt (user message) 25 | Note right of Agent: Process with LLM 26 | 27 | loop Until completion 28 | Note right of Agent: LLM responds with
content/tool calls 29 | Agent->>Client: session/update (plan) 30 | Agent->>Client: session/update (agent_message_chunk) 31 | 32 | opt Tool calls requested 33 | Agent->>Client: session/update (tool_call) 34 | opt Permission required 35 | Agent->>Client: session/request_permission 36 | Note left of Client: User grants/denies 37 | Client-->>Agent: Permission response 38 | end 39 | Agent->>Client: session/update (tool_call status: in_progress) 40 | Note right of Agent: Execute tool 41 | Agent->>Client: session/update (tool_call status: completed) 42 | Note right of Agent: Send tool results
back to LLM 43 | end 44 | 45 | opt User cancelled during execution 46 | Note left of Client: User cancels prompt 47 | Client->>Agent: session/cancel 48 | Note right of Agent: Abort operations 49 | Agent-->>Client: session/prompt response (cancelled) 50 | end 51 | end 52 | 53 | Agent-->>Client: session/prompt response (stopReason) 54 | 55 | ``` 56 | 57 | ### 1. User Message 58 | 59 | The turn begins when the Client sends a `session/prompt`: 60 | 61 | ```json 62 | { 63 | "jsonrpc": "2.0", 64 | "id": 2, 65 | "method": "session/prompt", 66 | "params": { 67 | "sessionId": "sess_abc123def456", 68 | "prompt": [ 69 | { 70 | "type": "text", 71 | "text": "Can you analyze this code for potential issues?" 72 | }, 73 | { 74 | "type": "resource", 75 | "resource": { 76 | "uri": "file:///home/user/project/main.py", 77 | "mimeType": "text/x-python", 78 | "text": "def process_data(items):\n for item in items:\n print(item)" 79 | } 80 | } 81 | ] 82 | } 83 | } 84 | ``` 85 | 86 | 87 | The [ID](./session-setup#session-id) of the session to send this message to. 88 | 89 | 90 | The contents of the user message, e.g. text, images, files, etc. 91 | 92 | Clients **MUST** restrict types of content according to the [Prompt Capabilities](./initialization#prompt-capabilities) established during [initialization](./initialization). 93 | 94 | 95 | Learn more about Content 96 | 97 | 98 | 99 | 100 | ### 2. Agent Processing 101 | 102 | 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. 103 | 104 | ### 3. Agent Reports Output 105 | 106 | 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: 107 | 108 | ```json expandable 109 | { 110 | "jsonrpc": "2.0", 111 | "method": "session/update", 112 | "params": { 113 | "sessionId": "sess_abc123def456", 114 | "update": { 115 | "sessionUpdate": "plan", 116 | "entries": [ 117 | { 118 | "content": "Check for syntax errors", 119 | "priority": "high", 120 | "status": "pending" 121 | }, 122 | { 123 | "content": "Identify potential type issues", 124 | "priority": "medium", 125 | "status": "pending" 126 | }, 127 | { 128 | "content": "Review error handling patterns", 129 | "priority": "medium", 130 | "status": "pending" 131 | }, 132 | { 133 | "content": "Suggest improvements", 134 | "priority": "low", 135 | "status": "pending" 136 | } 137 | ] 138 | } 139 | } 140 | } 141 | ``` 142 | 143 | 144 | Learn more about Agent Plans 145 | 146 | 147 | The Agent then reports text responses from the model: 148 | 149 | ```json 150 | { 151 | "jsonrpc": "2.0", 152 | "method": "session/update", 153 | "params": { 154 | "sessionId": "sess_abc123def456", 155 | "update": { 156 | "sessionUpdate": "agent_message_chunk", 157 | "content": { 158 | "type": "text", 159 | "text": "I'll analyze your code for potential issues. Let me examine it..." 160 | } 161 | } 162 | } 163 | } 164 | ``` 165 | 166 | If the model requested tool calls, these are also reported immediately: 167 | 168 | ```json 169 | { 170 | "jsonrpc": "2.0", 171 | "method": "session/update", 172 | "params": { 173 | "sessionId": "sess_abc123def456", 174 | "update": { 175 | "sessionUpdate": "tool_call", 176 | "toolCallId": "call_001", 177 | "title": "Analyzing Python code", 178 | "kind": "other", 179 | "status": "pending" 180 | } 181 | } 182 | } 183 | ``` 184 | 185 | ### 4. Check for Completion 186 | 187 | If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`: 188 | 189 | ```json 190 | { 191 | "jsonrpc": "2.0", 192 | "id": 2, 193 | "result": { 194 | "stopReason": "end_turn" 195 | } 196 | } 197 | ``` 198 | 199 | Agents **MAY** stop the turn at any point by returning the corresponding [`StopReason`](#stop-reasons). 200 | 201 | ### 5. Tool Invocation and Status Reporting 202 | 203 | Before proceeding with execution, the Agent **MAY** request permission from the Client via the `session/request_permission` method. 204 | 205 | Once permission is granted (if required), the Agent **SHOULD** invoke the tool and report a status update marking the tool as `in_progress`: 206 | 207 | ```json 208 | { 209 | "jsonrpc": "2.0", 210 | "method": "session/update", 211 | "params": { 212 | "sessionId": "sess_abc123def456", 213 | "update": { 214 | "sessionUpdate": "tool_call_update", 215 | "toolCallId": "call_001", 216 | "status": "in_progress" 217 | } 218 | } 219 | } 220 | ``` 221 | 222 | As the tool runs, the Agent **MAY** send additional updates, providing real-time feedback about tool execution progress. 223 | 224 | 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. 225 | 226 | When the tool completes, the Agent sends another update with the final status and any content: 227 | 228 | ```json 229 | { 230 | "jsonrpc": "2.0", 231 | "method": "session/update", 232 | "params": { 233 | "sessionId": "sess_abc123def456", 234 | "update": { 235 | "sessionUpdate": "tool_call_update", 236 | "toolCallId": "call_001", 237 | "status": "completed", 238 | "content": [ 239 | { 240 | "type": "content", 241 | "content": { 242 | "type": "text", 243 | "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" 244 | } 245 | } 246 | ] 247 | } 248 | } 249 | } 250 | ``` 251 | 252 | 253 | Learn more about Tool Calls 254 | 255 | 256 | ### 6. Continue Conversation 257 | 258 | The Agent sends the tool results back to the language model as another request. 259 | 260 | The cycle returns to [step 2](#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. 261 | 262 | ## Stop Reasons 263 | 264 | When an Agent stops a turn, it must specify the corresponding `StopReason`: 265 | 266 | 267 | The language model finishes responding without requesting more tools 268 | 269 | 270 | 271 | The maximum token limit is reached 272 | 273 | 274 | 275 | The maximum number of model requests in a single turn is exceeded 276 | 277 | 278 | The Agent refuses to continue 279 | 280 | The Client cancels the turn 281 | 282 | ## Cancellation 283 | 284 | Clients **MAY** cancel an ongoing prompt turn at any time by sending a `session/cancel` notification: 285 | 286 | ```json 287 | { 288 | "jsonrpc": "2.0", 289 | "method": "session/cancel", 290 | "params": { 291 | "sessionId": "sess_abc123def456" 292 | } 293 | } 294 | ``` 295 | 296 | 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. 297 | 298 | The Client **MUST** respond to all pending `session/request_permission` requests with the `cancelled` outcome. 299 | 300 | When the Agent receives this notification, it **SHOULD** stop all language model requests and all tool call invocations as soon as possible. 301 | 302 | 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](#stop-reasons). 303 | 304 | 305 | API client libraries and tools often throw an exception when their operation is aborted, which may propagate as an error response to `session/prompt`. 306 | 307 | Clients often display unrecognized errors from the Agent to the user, which would be undesirable for cancellations as they aren't considered errors. 308 | 309 | Agents **MUST** catch these errors and return the semantically meaningful `cancelled` stop reason, so that Clients can reliably confirm the cancellation. 310 | 311 | 312 | 313 | 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. 314 | 315 | The Client **SHOULD** still accept tool call updates received after sending `session/cancel`. 316 | 317 | --- 318 | 319 | Once a prompt turn completes, the Client may send another `session/prompt` to continue the conversation, building on the context established in previous turns. 320 | -------------------------------------------------------------------------------- /docs/protocol/session-modes.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Session Modes" 3 | description: "Switch between different agent operating modes" 4 | --- 5 | 6 | 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. 7 | 8 | ## Initial state 9 | 10 | During [Session Setup](./session-setup) the Agent **MAY** return a list of modes it can operate in and the currently active mode: 11 | 12 | ```json 13 | { 14 | "jsonrpc": "2.0", 15 | "id": 1, 16 | "result": { 17 | "sessionId": "sess_abc123def456", 18 | "modes": { 19 | "currentModeId": "ask", 20 | "availableModes": [ 21 | { 22 | "id": "ask", 23 | "name": "Ask", 24 | "description": "Request permission before making any changes" 25 | }, 26 | { 27 | "id": "architect", 28 | "name": "Architect", 29 | "description": "Design and plan software systems without implementation" 30 | }, 31 | { 32 | "id": "code", 33 | "name": "Code", 34 | "description": "Write and modify code with full tool access" 35 | } 36 | ] 37 | } 38 | } 39 | } 40 | ``` 41 | 42 | 43 | The current mode state for the session 44 | 45 | 46 | ### SessionModeState 47 | 48 | 49 | The ID of the mode that is currently active 50 | 51 | 52 | 53 | The set of modes that the Agent can operate in 54 | 55 | 56 | ### SessionMode 57 | 58 | 59 | Unique identifier for this mode 60 | 61 | 62 | 63 | Human-readable name of the mode 64 | 65 | 66 | 67 | Optional description providing more details about what this mode does 68 | 69 | 70 | ## Setting the current mode 71 | 72 | The current mode can be changed at any point during a session, whether the Agent is idle or generating a response. 73 | 74 | ### From the Client 75 | 76 | 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`](./schema#session%2Fset-mode) method. 77 | 78 | ```json 79 | { 80 | "jsonrpc": "2.0", 81 | "id": 2, 82 | "method": "session/set_mode", 83 | "params": { 84 | "sessionId": "sess_abc123def456", 85 | "modeId": "code" 86 | } 87 | } 88 | ``` 89 | 90 | 91 | The ID of the session to set the mode for 92 | 93 | 94 | 95 | The ID of the mode to switch to. Must be one of the modes listed in 96 | `availableModes` 97 | 98 | 99 | ### From the Agent 100 | 101 | The Agent can also change its own mode and let the Client know by sending the `current_mode_update` session notification: 102 | 103 | ```json 104 | { 105 | "jsonrpc": "2.0", 106 | "method": "session/update", 107 | "params": { 108 | "sessionId": "sess_abc123def456", 109 | "update": { 110 | "sessionUpdate": "current_mode_update", 111 | "modeId": "code" 112 | } 113 | } 114 | } 115 | ``` 116 | 117 | #### Exiting plan modes 118 | 119 | 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. 120 | 121 | This "switch mode" tool will usually request permission before running, which it can do just like any other tool: 122 | 123 | ```json 124 | { 125 | "jsonrpc": "2.0", 126 | "id": 3, 127 | "method": "session/request_permission", 128 | "params": { 129 | "sessionId": "sess_abc123def456", 130 | "toolCall": { 131 | "toolCallId": "call_switch_mode_001", 132 | "title": "Ready for implementation", 133 | "kind": "switch_mode", 134 | "status": "pending", 135 | "content": [ 136 | { 137 | "type": "text", 138 | "text": "## Implementation Plan..." 139 | } 140 | ] 141 | }, 142 | "options": [ 143 | { 144 | "optionId": "code", 145 | "name": "Yes, and auto-accept all actions", 146 | "kind": "allow_always" 147 | }, 148 | { 149 | "optionId": "ask", 150 | "name": "Yes, and manually accept actions", 151 | "kind": "allow_once" 152 | }, 153 | { 154 | "optionId": "reject", 155 | "name": "No, stay in architect mode", 156 | "kind": "reject_once" 157 | } 158 | ] 159 | } 160 | } 161 | ``` 162 | 163 | When an option is chosen, the tool runs, setting the mode and sending the `current_mode_update` notification mentioned above. 164 | 165 | 166 | Learn more about permission requests 167 | 168 | -------------------------------------------------------------------------------- /docs/protocol/slash-commands.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Slash Commands" 3 | description: "Advertise available slash commands to clients" 4 | --- 5 | 6 | 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](./prompt-turn) requests where the Client includes the command text in the prompt. 7 | 8 | ## Advertising commands 9 | 10 | After creating a session, the Agent **MAY** send a list of available commands via the `available_commands_update` session notification: 11 | 12 | ```json 13 | { 14 | "jsonrpc": "2.0", 15 | "method": "session/update", 16 | "params": { 17 | "sessionId": "sess_abc123def456", 18 | "update": { 19 | "sessionUpdate": "available_commands_update", 20 | "availableCommands": [ 21 | { 22 | "name": "web", 23 | "description": "Search the web for information", 24 | "input": { 25 | "hint": "query to search for" 26 | } 27 | }, 28 | { 29 | "name": "test", 30 | "description": "Run tests for the current project" 31 | }, 32 | { 33 | "name": "plan", 34 | "description": "Create a detailed implementation plan", 35 | "input": { 36 | "hint": "description of what to plan" 37 | } 38 | } 39 | ] 40 | } 41 | } 42 | } 43 | ``` 44 | 45 | 46 | The list of commands available in this session 47 | 48 | 49 | ### AvailableCommand 50 | 51 | 52 | The command name (e.g., "web", "test", "plan") 53 | 54 | 55 | 56 | Human-readable description of what the command does 57 | 58 | 59 | 60 | Optional input specification for the command 61 | 62 | 63 | ### AvailableCommandInput 64 | 65 | Currently supports unstructured text input: 66 | 67 | 68 | A hint to display when the input hasn't been provided yet 69 | 70 | 71 | ## Dynamic updates 72 | 73 | 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. 74 | 75 | ## Running commands 76 | 77 | Commands are included as regular user messages in prompt requests: 78 | 79 | ```json 80 | { 81 | "jsonrpc": "2.0", 82 | "id": 3, 83 | "method": "session/prompt", 84 | "params": { 85 | "sessionId": "sess_abc123def456", 86 | "prompt": [ 87 | { 88 | "type": "text", 89 | "text": "/web agent client protocol" 90 | } 91 | ] 92 | } 93 | } 94 | ``` 95 | 96 | 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. 97 | -------------------------------------------------------------------------------- /docs/protocol/terminals.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Terminals" 3 | description: "Executing and managing terminal commands" 4 | --- 5 | 6 | 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. 7 | 8 | ## Checking Support 9 | 10 | Before attempting to use terminal methods, Agents **MUST** verify that the Client supports this capability by checking the [Client Capabilities](./initialization#client-capabilities) field in the `initialize` response: 11 | 12 | ```json highlight={7} 13 | { 14 | "jsonrpc": "2.0", 15 | "id": 0, 16 | "result": { 17 | "protocolVersion": 1, 18 | "clientCapabilities": { 19 | "terminal": true 20 | } 21 | } 22 | } 23 | ``` 24 | 25 | If `terminal` is `false` or not present, the Agent **MUST NOT** attempt to call any terminal methods. 26 | 27 | ## Executing Commands 28 | 29 | The `terminal/create` method starts a command in a new terminal: 30 | 31 | ```json 32 | { 33 | "jsonrpc": "2.0", 34 | "id": 5, 35 | "method": "terminal/create", 36 | "params": { 37 | "sessionId": "sess_abc123def456", 38 | "command": "npm", 39 | "args": ["test", "--coverage"], 40 | "env": [ 41 | { 42 | "name": "NODE_ENV", 43 | "value": "test" 44 | } 45 | ], 46 | "cwd": "/home/user/project", 47 | "outputByteLimit": 1048576 48 | } 49 | } 50 | ``` 51 | 52 | 53 | The [Session ID](./session-setup#session-id) for this request 54 | 55 | 56 | 57 | The command to execute 58 | 59 | 60 | 61 | Array of command arguments 62 | 63 | 64 | 65 | Environment variables for the command. 66 | 67 | Each variable has: 68 | 69 | - `name`: The environment variable name 70 | - `value`: The environment variable value 71 | 72 | 73 | 74 | 75 | Working directory for the command (absolute path) 76 | 77 | 78 | 79 | Maximum number of output bytes to retain. Once exceeded, earlier output is 80 | truncated to stay within this limit. 81 | 82 | When the limit is exceeded, the Client truncates from the beginning of the output 83 | to stay within the limit. 84 | 85 | The Client **MUST** ensure truncation happens at a character boundary to maintain valid 86 | string output, even if this means the retained output is slightly less than the 87 | specified limit. 88 | 89 | 90 | 91 | The Client returns a Terminal ID immediately without waiting for completion: 92 | 93 | ```json 94 | { 95 | "jsonrpc": "2.0", 96 | "id": 5, 97 | "result": { 98 | "terminalId": "term_xyz789" 99 | } 100 | } 101 | ``` 102 | 103 | This allows the command to run in the background while the Agent performs other operations. 104 | 105 | After creating the terminal, the Agent can use the `terminal/wait_for_exit` method to wait for the command to complete. 106 | 107 | 108 | The Agent **MUST** release the terminal using `terminal/release` when it's no 109 | longer needed. 110 | 111 | 112 | ## Embedding in Tool Calls 113 | 114 | Terminals can be embedded directly in [tool calls](./tool-calls) to provide real-time output to users: 115 | 116 | ```json 117 | { 118 | "jsonrpc": "2.0", 119 | "method": "session/update", 120 | "params": { 121 | "sessionId": "sess_abc123def456", 122 | "update": { 123 | "sessionUpdate": "tool_call", 124 | "toolCallId": "call_002", 125 | "title": "Running tests", 126 | "kind": "execute", 127 | "status": "in_progress", 128 | "content": [ 129 | { 130 | "type": "terminal", 131 | "terminalId": "term_xyz789" 132 | } 133 | ] 134 | } 135 | } 136 | } 137 | ``` 138 | 139 | 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. 140 | 141 | ## Getting Output 142 | 143 | The `terminal/output` method retrieves the current terminal output without waiting for the command to complete: 144 | 145 | ```json 146 | { 147 | "jsonrpc": "2.0", 148 | "id": 6, 149 | "method": "terminal/output", 150 | "params": { 151 | "sessionId": "sess_abc123def456", 152 | "terminalId": "term_xyz789" 153 | } 154 | } 155 | ``` 156 | 157 | The Client responds with the current output and exit status (if the command has finished): 158 | 159 | ```json 160 | { 161 | "jsonrpc": "2.0", 162 | "id": 6, 163 | "result": { 164 | "output": "Running tests...\n✓ All tests passed (42 total)\n", 165 | "truncated": false, 166 | "exitStatus": { 167 | "exitCode": 0, 168 | "signal": null 169 | } 170 | } 171 | } 172 | ``` 173 | 174 | 175 | The terminal output captured so far 176 | 177 | 178 | 179 | Whether the output was truncated due to byte limits 180 | 181 | 182 | 183 | Present only if the command has exited. Contains: 184 | 185 | - `exitCode`: The process exit code (may be null) 186 | - `signal`: The signal that terminated the process (may be null) 187 | 188 | 189 | 190 | ## Waiting for Exit 191 | 192 | The `terminal/wait_for_exit` method returns once the command completes: 193 | 194 | ```json 195 | { 196 | "jsonrpc": "2.0", 197 | "id": 7, 198 | "method": "terminal/wait_for_exit", 199 | "params": { 200 | "sessionId": "sess_abc123def456", 201 | "terminalId": "term_xyz789" 202 | } 203 | } 204 | ``` 205 | 206 | The Client responds once the command exits: 207 | 208 | ```json 209 | { 210 | "jsonrpc": "2.0", 211 | "id": 7, 212 | "result": { 213 | "exitCode": 0, 214 | "signal": null 215 | } 216 | } 217 | ``` 218 | 219 | 220 | The process exit code (may be null if terminated by signal) 221 | 222 | 223 | 224 | The signal that terminated the process (may be null if exited normally) 225 | 226 | 227 | ## Killing Commands 228 | 229 | The `terminal/kill` method terminates a command without releasing the terminal: 230 | 231 | ```json 232 | { 233 | "jsonrpc": "2.0", 234 | "id": 8, 235 | "method": "terminal/kill", 236 | "params": { 237 | "sessionId": "sess_abc123def456", 238 | "terminalId": "term_xyz789" 239 | } 240 | } 241 | ``` 242 | 243 | After killing a command, the terminal remains valid and can be used with: 244 | 245 | - `terminal/output` to get the final output 246 | - `terminal/wait_for_exit` to get the exit status 247 | 248 | The Agent **MUST** still call `terminal/release` when it's done using it. 249 | 250 | ### Building a Timeout 251 | 252 | Agents can implement command timeouts by combining terminal methods: 253 | 254 | 1. Create a terminal with `terminal/create` 255 | 2. Start a timer for the desired timeout duration 256 | 3. Concurrently wait for either the timer to expire or `terminal/wait_for_exit` to return 257 | 4. If the timer expires first: 258 | - Call `terminal/kill` to terminate the command 259 | - Call `terminal/output` to retrieve any final output 260 | - Include the output in the response to the model 261 | 5. Call `terminal/release` when done 262 | 263 | ## Releasing Terminals 264 | 265 | The `terminal/release` kills the command if still running and releases all resources: 266 | 267 | ```json 268 | { 269 | "jsonrpc": "2.0", 270 | "id": 9, 271 | "method": "terminal/release", 272 | "params": { 273 | "sessionId": "sess_abc123def456", 274 | "terminalId": "term_xyz789" 275 | } 276 | } 277 | ``` 278 | 279 | After release the terminal ID becomes invalid for all other `terminal/*` methods. 280 | 281 | If the terminal was added to a tool call, the client **SHOULD** continue to display its output after release. 282 | -------------------------------------------------------------------------------- /docs/protocol/tool-calls.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Tool Calls" 3 | description: "How Agents report tool call execution" 4 | --- 5 | 6 | Tool calls represent actions that language models request Agents to perform during a [prompt turn](./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. 7 | 8 | Agents report tool calls through [`session/update`](./prompt-turn#3-agent-reports-output) notifications, allowing Clients to display real-time progress and results to users. 9 | 10 | While Agents handle the actual execution, they may leverage Client capabilities like [permission requests](#requesting-permission) or [file system access](./file-system) to provide a richer, more integrated experience. 11 | 12 | ## Creating 13 | 14 | When the language model requests a tool invocation, the Agent **SHOULD** report it to the Client: 15 | 16 | ```json 17 | { 18 | "jsonrpc": "2.0", 19 | "method": "session/update", 20 | "params": { 21 | "sessionId": "sess_abc123def456", 22 | "update": { 23 | "sessionUpdate": "tool_call", 24 | "toolCallId": "call_001", 25 | "title": "Reading configuration file", 26 | "kind": "read", 27 | "status": "pending" 28 | } 29 | } 30 | } 31 | ``` 32 | 33 | 34 | A unique identifier for this tool call within the session 35 | 36 | 37 | 38 | A human-readable title describing what the tool is doing 39 | 40 | 41 | 42 | The category of tool being invoked. 43 | 44 | 45 | - `read` - Reading files or data - `edit` - Modifying files or content - 46 | `delete` - Removing files or data - `move` - Moving or renaming files - 47 | `search` - Searching for information - `execute` - Running commands or code - 48 | `think` - Internal reasoning or planning - `fetch` - Retrieving external data 49 | - `other` - Other tool types (default) 50 | 51 | 52 | Tool kinds help Clients choose appropriate icons and optimize how they display tool execution progress. 53 | 54 | 55 | 56 | 57 | The current [execution status](#status) (defaults to `pending`) 58 | 59 | 60 | 61 | [Content produced](#content) by the tool call 62 | 63 | 64 | 65 | [File locations](#following-the-agent) affected by this tool call 66 | 67 | 68 | 69 | The raw input parameters sent to the tool 70 | 71 | 72 | 73 | The raw output returned by the tool 74 | 75 | 76 | ## Updating 77 | 78 | As tools execute, Agents send updates to report progress and results. 79 | 80 | Updates use the `session/update` notification with `tool_call_update`: 81 | 82 | ```json 83 | { 84 | "jsonrpc": "2.0", 85 | "method": "session/update", 86 | "params": { 87 | "sessionId": "sess_abc123def456", 88 | "update": { 89 | "sessionUpdate": "tool_call_update", 90 | "toolCallId": "call_001", 91 | "status": "in_progress", 92 | "content": [ 93 | { 94 | "type": "content", 95 | "content": { 96 | "type": "text", 97 | "text": "Found 3 configuration files..." 98 | } 99 | } 100 | ] 101 | } 102 | } 103 | } 104 | ``` 105 | 106 | All fields except `toolCallId` are optional in updates. Only the fields being changed need to be included. 107 | 108 | ## Requesting Permission 109 | 110 | The Agent **MAY** request permission from the user before executing a tool call by calling the `session/request_permission` method: 111 | 112 | ```json 113 | { 114 | "jsonrpc": "2.0", 115 | "id": 5, 116 | "method": "session/request_permission", 117 | "params": { 118 | "sessionId": "sess_abc123def456", 119 | "toolCall": { 120 | "toolCallId": "call_001" 121 | }, 122 | "options": [ 123 | { 124 | "optionId": "allow-once", 125 | "name": "Allow once", 126 | "kind": "allow_once" 127 | }, 128 | { 129 | "optionId": "reject-once", 130 | "name": "Reject", 131 | "kind": "reject_once" 132 | } 133 | ] 134 | } 135 | } 136 | ``` 137 | 138 | 139 | The session ID for this request 140 | 141 | 142 | 143 | The tool call update containing details about the operation 144 | 145 | 146 | 147 | Available [permission options](#permission-options) for the user to choose 148 | from 149 | 150 | 151 | The Client responds with the user's decision: 152 | 153 | ```json 154 | { 155 | "jsonrpc": "2.0", 156 | "id": 5, 157 | "result": { 158 | "outcome": { 159 | "outcome": "selected", 160 | "optionId": "allow-once" 161 | } 162 | } 163 | } 164 | ``` 165 | 166 | Clients **MAY** automatically allow or reject permission requests according to the user settings. 167 | 168 | If the current prompt turn gets [cancelled](./prompt-turn#cancellation), the Client **MUST** respond with the `"cancelled"` outcome: 169 | 170 | ```json 171 | { 172 | "jsonrpc": "2.0", 173 | "id": 5, 174 | "result": { 175 | "outcome": { 176 | "outcome": "cancelled" 177 | } 178 | } 179 | } 180 | ``` 181 | 182 | 183 | The user's decision, either: - `cancelled` - The [prompt turn was 184 | cancelled](./prompt-turn#cancellation) - `selected` with an `optionId` - The 185 | ID of the selected permission option 186 | 187 | 188 | ### Permission Options 189 | 190 | Each permission option provided to the Client contains: 191 | 192 | 193 | Unique identifier for this option 194 | 195 | 196 | 197 | Human-readable label to display to the user 198 | 199 | 200 | 201 | A hint to help Clients choose appropriate icons and UI treatment for each option. 202 | 203 | - `allow_once` - Allow this operation only this time 204 | - `allow_always` - Allow this operation and remember the choice 205 | - `reject_once` - Reject this operation only this time 206 | - `reject_always` - Reject this operation and remember the choice 207 | 208 | 209 | 210 | ## Status 211 | 212 | Tool calls progress through different statuses during their lifecycle: 213 | 214 | 215 | The tool call hasn't started running yet because the input is either streaming 216 | or awaiting approval 217 | 218 | 219 | 220 | The tool call is currently running 221 | 222 | 223 | 224 | The tool call completed successfully 225 | 226 | 227 | The tool call failed with an error 228 | 229 | ## Content 230 | 231 | Tool calls can produce different types of content: 232 | 233 | ### Regular Content 234 | 235 | Standard [content blocks](./content) like text, images, or resources: 236 | 237 | ```json 238 | { 239 | "type": "content", 240 | "content": { 241 | "type": "text", 242 | "text": "Analysis complete. Found 3 issues." 243 | } 244 | } 245 | ``` 246 | 247 | ### Diffs 248 | 249 | File modifications shown as diffs: 250 | 251 | ```json 252 | { 253 | "type": "diff", 254 | "path": "/home/user/project/src/config.json", 255 | "oldText": "{\n \"debug\": false\n}", 256 | "newText": "{\n \"debug\": true\n}" 257 | } 258 | ``` 259 | 260 | 261 | The absolute file path being modified 262 | 263 | 264 | 265 | The original content (null for new files) 266 | 267 | 268 | 269 | The new content after modification 270 | 271 | 272 | ### Terminals 273 | 274 | Live terminal output from command execution: 275 | 276 | ```json 277 | { 278 | "type": "terminal", 279 | "terminalId": "term_xyz789" 280 | } 281 | ``` 282 | 283 | 284 | The ID of a terminal created with `terminal/create` 285 | 286 | 287 | 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. 288 | 289 | 290 | Learn more about Terminals 291 | 292 | 293 | ## Following the Agent 294 | 295 | 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. 296 | 297 | ```json 298 | { 299 | "path": "/home/user/project/src/main.py", 300 | "line": 42 301 | } 302 | ``` 303 | 304 | 305 | The absolute file path being accessed or modified 306 | 307 | 308 | 309 | Optional line number within the file 310 | 311 | -------------------------------------------------------------------------------- /docs/protocol/transports.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Transports" 3 | description: "Mechanisms for agents and clients to communicate with each other" 4 | --- 5 | 6 | ACP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded. 7 | 8 | The protocol currently defines the following transport mechanisms for agent-client communication: 9 | 10 | 1. [stdio](#stdio), communication over standard in and standard out 11 | 2. _[Streamable HTTP](#streamable-http) (draft proposal in progress)_ 12 | 13 | Agents and clients **SHOULD** support stdio whenever possible. 14 | 15 | It is also possible for agents and clients to implement [custom transports](#custom-transports). 16 | 17 | ## stdio 18 | 19 | In the **stdio** transport: 20 | 21 | - The client launches the agent as a subprocess. 22 | - The agent reads JSON-RPC messages from its standard input (`stdin`) and sends messages to its standard output (`stdout`). 23 | - Messages are individual JSON-RPC requests, notifications, or responses. 24 | - Messages are delimited by newlines (`\n`), and **MUST NOT** contain embedded newlines. 25 | - The agent **MAY** write UTF-8 strings to its standard error (`stderr`) for logging purposes. Clients **MAY** capture, forward, or ignore this logging. 26 | - The agent **MUST NOT** write anything to its `stdout` that is not a valid ACP message. 27 | - The client **MUST NOT** write anything to the agent's `stdin` that is not a valid ACP message. 28 | 29 | ```mermaid 30 | sequenceDiagram 31 | participant Client 32 | participant Agent Process 33 | 34 | Client->>+Agent Process: Launch subprocess 35 | loop Message Exchange 36 | Client->>Agent Process: Write to stdin 37 | Agent Process->>Client: Write to stdout 38 | Agent Process--)Client: Optional logs on stderr 39 | end 40 | Client->>Agent Process: Close stdin, terminate subprocess 41 | deactivate Agent Process 42 | ``` 43 | 44 | ## _Streamable HTTP_ 45 | 46 | _In discussion, draft proposal in progress._ 47 | 48 | ## Custom Transports 49 | 50 | 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. 51 | 52 | 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. 53 | -------------------------------------------------------------------------------- /docs/rfds/TEMPLATE: -------------------------------------------------------------------------------- 1 | --- 2 | title: "INSERT RFD TITLE HERE" 3 | --- 4 | 5 | 16 | 17 | Author(s): [githubhandle](url) 18 | 19 | ## Elevator pitch 20 | 21 | > What are you proposing to change? 22 | 23 | 26 | 27 | ## Status quo 28 | 29 | > How do things work today and what problems does this cause? Why would we change things? 30 | 31 | ## What we propose to do about it 32 | 33 | > What are you proposing to improve the situation? 34 | 35 | 42 | 43 | ## Shiny future 44 | 45 | > How will things will play out once this feature exists? 46 | 47 | 53 | 54 | ## Implementation details and plan 55 | 56 | > Tell me more about your implementation. What is your detailed implementation plan? 57 | 58 | 63 | 64 | ## Frequently asked questions 65 | 66 | > What questions have arisen over the course of authoring this document or during subsequent discussions? 67 | 68 | 71 | 72 | ### What alternative approaches did you consider, and why did you settle on this one? 73 | 74 | None. The idea came to me fully formed, like Athena springing from Zeus's head. 75 | 76 | 77 | 78 | ## Revision history 79 | 80 | 81 | -------------------------------------------------------------------------------- /docs/rfds/about.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Requests for Dialog (RFDs)" 3 | description: "Our process for introducing changes to the protocol" 4 | --- 5 | 6 | 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. 7 | 8 | ## When to write an RFD 9 | 10 | 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. 11 | 12 | Some changes do not require an RFD: 13 | 14 | - Rephrasing, reorganizing or refactoring 15 | - Addition or removal of warnings 16 | - Additions that strictly improve objective, numerical quality criteria (speedup, better browser support) 17 | - Fixing objectively incorrect behavior 18 | 19 | ## The RFD Process 20 | 21 | ### 1. Propose by opening a PR 22 | 23 | [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. 24 | 25 | ### 2. Merge to "Draft" when championed 26 | 27 | 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. 28 | 29 | RFDs are living documents that track implementation progress. PRs working towards an RFC will typically update it to reflect changes in design or direction. 30 | 31 | ### 2b. Move to "To be removed" 32 | 33 | 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. 34 | 35 | ### 3. Move to "Preview" when fully implemented 36 | 37 | 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. 38 | 39 | ### 4. Completed 40 | 41 | 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. 42 | 43 | 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". 44 | 45 | ### 5. Implementation and completion 46 | 47 | #### RFD Lifecycle 48 | 49 | - **Early drafts**: Initial ideas, brainstorming, early exploration 50 | - **Mature drafts**: Well-formed proposals ready for broader review 51 | - **Accepted**: Approved for implementation, may reference implementation work 52 | - **To be removed (yet?)**: Decided against for now, but preserved for future consideration 53 | - **Completed**: Implementation finished and merged 54 | 55 | ## Governance 56 | 57 | The project currently has a design team with the [Zed team as the lead (BDFL)](../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. 58 | 59 | ## Discussion and Moderation 60 | 61 | 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. 62 | 63 | ## Licensing 64 | 65 | All RFDs are licensed under Apache 2.0. The project remains open source. 66 | 67 | ## 68 | -------------------------------------------------------------------------------- /docs/rfds/introduce-rfd-process.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Introduce RFD Process" 3 | --- 4 | 5 | Author(s): [@benbrandt](https://github.com/benbrandt) 6 | 7 | ## Elevator pitch 8 | 9 | > What are you proposing to change? Bullet points welcome. 10 | 11 | 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. 12 | 13 | ## Status quo 14 | 15 | > How do things work today and what problems does this cause? Why would we change things? 16 | 17 | 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. 18 | 19 | ## Shiny future 20 | 21 | > How will things will play out once this feature exists? 22 | 23 | ### Project licensing 24 | 25 | 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. 26 | 27 | ### Decision making 28 | 29 | 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. 30 | 31 | ### RFD lifecycle 32 | 33 | #### RFDs are proposed by opening a PR 34 | 35 | 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. 36 | 37 | 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. 38 | 39 | #### The PR is merged into "draft" once a core team member decides to champion it 40 | 41 | 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. 42 | 43 | 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. 44 | 45 | Further discussion on the RFD can take place on [Zulip](https://agentclientprotocol.zulipchat.com/) if needed. 46 | 47 | #### Moving to the "preview" section 48 | 49 | 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. 50 | 51 | #### Deciding to accept an RFD 52 | 53 | 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. 54 | 55 | #### Implementation of an RFD 56 | 57 | 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. 58 | 59 | ### Moderating and managing RFD discussions 60 | 61 | 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. 62 | 63 | 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. 64 | 65 | ## Implementation plan 66 | 67 | > What is your implementation plan? 68 | 69 | - ✅ Create RFD infrastructure (about, TEMPLATE, navigation setup) 70 | - ✅ Establish lifecycle: Draft → Preview → Accepted → Completed 71 | - ⏳ Write RFDs for major in-progress features 72 | 73 | ## Frequently asked questions 74 | 75 | ### Why "Request for Dialog" and not "Request for Comment"? 76 | 77 | 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. 78 | 79 | ## Revision history 80 | 81 | - 2025-10-28: Initial version, created alongside RFD infrastructure 82 | -------------------------------------------------------------------------------- /docs/rfds/session-fork.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Forking of existing sessions" 3 | --- 4 | 5 | - Author(s): [@josevalim](https://github.com/josevalim) 6 | - Champion: [@benbrandt](https://github.com/benbrandt) 7 | 8 | ## Elevator pitch 9 | 10 | > What are you proposing to change? 11 | 12 | We propose adding the ability to "fork" a new session based on an existing one. 13 | This will allow us to use the current conversation as context to generate pull 14 | request descriptions, summaries, etc. without polluting the user history. 15 | 16 | ## Status quo 17 | 18 | > How do things work today and what problems does this cause? Why would we change things? 19 | 20 | Imagine we want to summarize the current conversation to use it in a future chat. If we send a message 21 | asking for the summary, it will become part of its context, affecting future user interactions. 22 | Therefore we want to be able to fork a session, issue additional messages, and then close the fork. 23 | 24 | ## What we propose to do about it 25 | 26 | > What are you proposing to improve the situation? 27 | 28 | To add a "session/fork" method. 29 | 30 | ## Shiny future 31 | 32 | > How will things will play out once this feature exists? 33 | 34 | We will be able to implement functionality that requires using the current chat 35 | without polluting its history, ranging from summaries to potentially subagents. 36 | 37 | I can also see this feature being extended in the future to support an optional 38 | message ID, so the fork happens at a specific message, allowing clients to implement 39 | functionality like editing previous messages and similar. 40 | 41 | ## Implementation details and plan 42 | 43 | > Tell me more about your implementation. What is your detailed implementation plan? 44 | 45 | We propose to add a new "session/fork" method. Agents must declare this option is 46 | available by returning `session: { fork : {} }` in its capabilities. The object is reserved 47 | to declare future capabilities, such as forking from a specific message, a tool call, or similar. 48 | 49 | Then the client would be able to request a fork of the current session: 50 | 51 | ```json 52 | { 53 | "jsonrpc": "2.0", 54 | "id": 1, 55 | "method": "session/fork", 56 | "params": { 57 | "sessionId": "sess_789xyz" 58 | } 59 | } 60 | ``` 61 | 62 | And the agent would respond with optional data such as config options, the same as `session/load`. 63 | 64 | A proof of concept is available here: https://github.com/zed-industries/claude-code-acp/pull/145 65 | 66 | ## Frequently asked questions 67 | 68 | > What questions have arisen over the course of authoring this document or during subsequent discussions? 69 | 70 | **Q: Should a new method be introduced or should "session/new" be expanded?** 71 | 72 | They must be different because they will effectively require different options. 73 | For example, "session/new" has options such as capabilities and MCP which are not 74 | recommended to be set when forking, as the context being forked was built with other 75 | tools, and forking may accept a messageId for checkpoints. 76 | 77 | ### What alternative approaches did you consider, and why did you settle on this one? 78 | 79 | None. This proposal is inspired by the abilities exposed in Claude Agent SDK. It must be validated against other agents too. 80 | 81 | ## Revision history 82 | 83 | - 2025-11-17: Mentioned capabilities format, updated FAQ. 84 | - 2025-11-20: Added request format and updated capabilities format. 85 | -------------------------------------------------------------------------------- /docs/rfds/session-resume.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Resuming of existing sessions" 3 | --- 4 | 5 | - Author(s): [@josevalim](https://github.com/josevalim) 6 | - Champion: [@benbrandt](https://github.com/benbrandt) 7 | 8 | ## Elevator pitch 9 | 10 | > What are you proposing to change? 11 | 12 | We propose adding the ability to resume existing sessions. This is similar to "session/load", 13 | except it does not return previous messages. 14 | 15 | ## Status quo 16 | 17 | > How do things work today and what problems does this cause? Why would we change things? 18 | 19 | While the spec provides a "session/load" command, not all coding agents implement it. 20 | This means that, once you close your editor, browser, etc, you can't resume the conversation. 21 | 22 | This is particularly a problem for agents that do not directly implement ACP and the 23 | functionality is implemented via a wrapper. In such cases, they may provide the ability 24 | to resume (without history), which we would like to hook into. Not only that, resuming 25 | could be used as a mechanism for proxies and adapter libraries to emulate "session/load". 26 | 27 | ## What we propose to do about it 28 | 29 | > What are you proposing to improve the situation? 30 | 31 | Add a "session/resume" command and a capability `{ session: { resume: {} }`. 32 | 33 | ## Shiny future 34 | 35 | > How will things will play out once this feature exists? 36 | 37 | We will be able to resume existing conversations, providing a better user experience. 38 | 39 | Not only that, if an agent does not implement "session/load" but it does implement 40 | "session/resume", it is now possible to implement a proxy/adapter that intercepts 41 | the agents messages and writes them to disk. Now when the client issues a 42 | "session/load", the proxy/adapter converts it to a "session/resume", and then returns 43 | the stored messages. 44 | 45 | ## Implementation details and plan 46 | 47 | > Tell me more about your implementation. What is your detailed implementation plan? 48 | 49 | ## Frequently asked questions 50 | 51 | > What questions have arisen over the course of authoring this document or during subsequent discussions? 52 | 53 | ### Should we introduce a new operation (session/resume) or add an option to (session/load)? 54 | 55 | A separate method provides a few benefits: 56 | 57 | - for clients that for whatever reason don't want the history, they can just resume 58 | 59 | - for agents that can only supply resume, a proxy on top could provide load on top of it, 60 | but the agent is still clear on what it supports 61 | 62 | - for agents who support both, it should be trivial to use the same resume functionality, 63 | they just either replay events or do not 64 | 65 | ### What alternative approaches did you consider, and why did you settle on this one? 66 | 67 | The biggest question is if it makes sense to support both "session/load" and 68 | "session/resume". 69 | 70 | When we start a new session over ACP, we introduce custom MCP tools and configuration. 71 | This means that, while we could use "session/load" to load our own chats, loading 72 | third-party chats would likely lead to a flawed user experience, as our tools would 73 | not be available. And depending on the ACP implementation, not even the capabilities 74 | would be respected (as loading a third-party session would not include our capabilities 75 | in its history, misleading the agent). 76 | 77 | Therefore, if we assume "session/load" is for loading conversations started by the client 78 | itself, "session/resume" is effectively a subset of "session/load", decoupled from storage 79 | mechanics. If an agent implements "session/load", then it can be used directly, but if it 80 | doesn't, a proxy or adapter can provide a reasonable fallback on top of "session/resume". 81 | This argues "session/resume" is the basic primitive which "session/load" builds on top of. 82 | 83 | ## Revision history 84 | 85 | - 2025-11-24: Update FAQ to mention session/resume vs session/load 86 | -------------------------------------------------------------------------------- /docs/updates.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Updates 3 | description: Updates and announcements about the Agent Client Protocol 4 | rss: true 5 | --- 6 | 7 | 8 | ## session/resume RFD moves to Draft stage 9 | 10 | The RFD for adding a "session/resume" method to the protocol has been moved to Draft stage. Please review the [RFD](./rfds/session-resume) for more information on the current proposal and provide feedback as work on the implementation begins. 11 | 12 | 13 | 14 | 15 | ## $/cancelRequest RFD moves to Draft stage 16 | 17 | The RFD for adding a "$/cancelRequest" method to the protocol has been moved to Draft stage. Please review the [RFD](./rfds/request-cancellation) for more information on the current proposal and provide feedback as work on the implementation begins. 18 | 19 | 20 | 21 | 22 | ## session/fork RFD moves to Draft stage 23 | 24 | The RFD for adding a "session/fork" method to the protocol has been moved to Draft stage. Please review the [RFD](./rfds/session-fork) for more information on the current proposal and provide feedback as work on the implementation begins. 25 | 26 | 27 | 28 | 29 | ## Session Config Options RFD moves to Draft stage 30 | 31 | The RFD for adding more generic Session Config Options to the protocol has been moved to Draft stage. Please review the [RFD](./rfds/session-config-options) for more information on the current proposal and provide feedback as work on the implementation begins. 32 | 33 | 34 | 35 | 36 | ## session/list RFD moves to Draft stage 37 | 38 | The RFD for adding a "session/list" method to the protocol has been moved to Draft stage. Please review the [RFD](./rfds/session-list) for more information on the current proposal and provide feedback as work on the implementation begins. 39 | 40 | 41 | 42 | 43 | ## Implementation Information for Agents and Clients 44 | 45 | Agents and Clients are [now able to provide information about themselves](./protocol/initialization#implementation-information) to the other party. The [`InitializeRequest`](./protocol/schema#initializerequest) message now includes an optional `clientInfo` field and the [`InitializeResponse`](./protocol/schema#initializeresponse) message includes an optional `agentInfo` field. 46 | 47 | This information can be used by Clients to show users which Agent is running and what version, by both sides to track usage metrics of which agents and clients are most popular among their users, and also to help track down if any issues are encountered with particular implementation version. This follows the existing pattern laid out in the [Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization). 48 | 49 | This is being introduced as an optional field for now for backwards compatibility. It is possible it will be made into a required field in a future version of the protocol, like MCP, so that both sides can count on this information being available. 50 | 51 | 52 | -------------------------------------------------------------------------------- /docs/v2-changes.md: -------------------------------------------------------------------------------- 1 | # Proposal for changes in an ACP v2 2 | 3 | A WIP document to keep track of ideas and proposals for breaking changes that would require a version bump in the protocol. 4 | 5 | ## Proposed Changes 6 | 7 | - Make `clientInfo` and `agentInfo` required in the `initialize` request. 8 | 9 | ## Agreed on Changes 10 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@agentclientprotocol/schema", 3 | "version": "0.0.0", 4 | "publishConfig": { 5 | "access": "public" 6 | }, 7 | "description": "The Agent Client Protocol (ACP) is a protocol that standardizes communication between *code editors* (interactive programs for viewing and editing source code) and *coding agents* (programs that use generative AI to autonomously modify code).", 8 | "homepage": "https://github.com/agentclientprotocol/agent-client-protocol#readme", 9 | "bugs": { 10 | "url": "https://github.com/agentclientprotocol/agent-client-protocol/issues" 11 | }, 12 | "repository": { 13 | "type": "git", 14 | "url": "git+https://github.com/agentclientprotocol/agent-client-protocol.git" 15 | }, 16 | "license": "Apache-2.0", 17 | "author": "Zed Industries", 18 | "files": [ 19 | "schema/schema.json", 20 | "LICENSE" 21 | ], 22 | "type": "module", 23 | "scripts": { 24 | "generate:json-schema": "cd rust && cargo run --bin generate", 25 | "generate:json-schema:unstable": "cd rust && cargo run --bin generate --features unstable", 26 | "generate": "npm run generate:json-schema && npm run generate:json-schema:unstable && npm run format", 27 | "format": "prettier --write . && cargo fmt", 28 | "format:check": "prettier --check . && cargo fmt -- --check", 29 | "spellcheck": "./scripts/spellcheck.sh", 30 | "spellcheck:fix": "./scripts/spellcheck.sh --write-changes", 31 | "check": "cargo clippy --all-features && npm run format:check && npm run spellcheck && cargo test", 32 | "docs": "cd docs && npx mint dev" 33 | }, 34 | "devDependencies": { 35 | "prettier": "^3.3.3", 36 | "tsx": "^4.20.5" 37 | } 38 | } 39 | -------------------------------------------------------------------------------- /rust/acp.rs: -------------------------------------------------------------------------------- 1 | //! [![Agent Client Protocol](https://zed.dev/img/acp/banner-dark.webp)](https://agentclientprotocol.com/) 2 | //! 3 | //! # Agent Client Protocol (ACP) 4 | //! 5 | //! The Agent Client Protocol standardizes communication between code editors 6 | //! (IDEs, text-editors, etc.) and coding agents (programs that use generative AI 7 | //! to autonomously modify code). 8 | //! 9 | //! ## Protocol & Transport 10 | //! 11 | //! ACP is a JSON-RPC based protocol. While clients typically start agents as 12 | //! subprocesses and communicate over stdio (stdin/stdout), this crate is 13 | //! transport-agnostic. 14 | //! 15 | //! You can use any bidirectional stream that implements `AsyncRead` and `AsyncWrite`. 16 | //! 17 | //! ## Core Components 18 | //! 19 | //! - **Agent**: Programs that use generative AI to autonomously modify code 20 | //! - See: [Agent](https://agentclientprotocol.com/protocol/overview#agent) 21 | //! - **Client**: Code editors that provide the interface between users and agents 22 | //! - See: [Client](https://agentclientprotocol.com/protocol/overview#client) 23 | //! 24 | //! ## Getting Started 25 | //! 26 | //! To understand the protocol, start by exploring the [`Agent`] and [`Client`] traits, 27 | //! which define the core methods and capabilities of each side of the connection. 28 | //! 29 | //! To see working examples of these traits in action, check out the 30 | //! [agent](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/agent.rs) 31 | //! and 32 | //! [client](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/client.rs) 33 | //! example binaries included with this crate. 34 | //! 35 | //! ### Implementation Pattern 36 | //! 37 | //! ACP uses a symmetric design where each participant implements one trait and 38 | //! creates a connection that provides the complementary trait: 39 | //! 40 | //! - **Agent builders** implement the [`Agent`] trait to handle client requests 41 | //! (like initialization, authentication, and prompts). They pass this implementation 42 | //! to [`AgentSideConnection::new`], which returns a connection providing [`Client`] 43 | //! methods for requesting permissions and accessing the file system. 44 | //! 45 | //! - **Client builders** implement the [`Client`] trait to handle agent requests 46 | //! (like file system operations and permission checks). They pass this implementation 47 | //! to [`ClientSideConnection::new`], which returns a connection providing [`Agent`] 48 | //! methods for managing sessions and sending prompts. 49 | //! 50 | //! For the complete protocol specification and documentation, visit: 51 | //! [https://agentclientprotocol.com](https://agentclientprotocol.com) 52 | 53 | mod agent; 54 | mod client; 55 | mod content; 56 | mod error; 57 | mod ext; 58 | mod plan; 59 | mod rpc; 60 | mod tool_call; 61 | mod version; 62 | 63 | pub use agent::*; 64 | pub use client::*; 65 | pub use content::*; 66 | use derive_more::{Display, From}; 67 | pub use error::*; 68 | pub use ext::*; 69 | pub use plan::*; 70 | pub use rpc::*; 71 | pub use serde_json::value::RawValue; 72 | pub use tool_call::*; 73 | pub use version::*; 74 | 75 | use schemars::JsonSchema; 76 | use serde::{Deserialize, Serialize}; 77 | use std::sync::Arc; 78 | 79 | /// A unique identifier for a conversation session between a client and agent. 80 | /// 81 | /// Sessions maintain their own context, conversation history, and state, 82 | /// allowing multiple independent interactions with the same agent. 83 | /// 84 | /// See protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id) 85 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq, Hash, Display, From)] 86 | #[serde(transparent)] 87 | #[from(Arc, String, &'static str)] 88 | #[non_exhaustive] 89 | pub struct SessionId(pub Arc); 90 | 91 | impl SessionId { 92 | pub fn new(id: impl Into>) -> Self { 93 | Self(id.into()) 94 | } 95 | } 96 | -------------------------------------------------------------------------------- /rust/error.rs: -------------------------------------------------------------------------------- 1 | //! Error handling for the Agent Client Protocol. 2 | //! 3 | //! This module provides error types and codes following the JSON-RPC 2.0 specification, 4 | //! with additional protocol-specific error codes for authentication and other ACP-specific scenarios. 5 | //! 6 | //! All methods in the protocol follow standard JSON-RPC 2.0 error handling: 7 | //! - Successful responses include a `result` field 8 | //! - Errors include an `error` object with `code` and `message` 9 | //! - Notifications never receive responses (success or error) 10 | //! 11 | //! See: [Error Handling](https://agentclientprotocol.com/protocol/overview#error-handling) 12 | 13 | use std::fmt::Display; 14 | 15 | use schemars::JsonSchema; 16 | use serde::{Deserialize, Serialize}; 17 | 18 | pub type Result = std::result::Result; 19 | 20 | /// JSON-RPC error object. 21 | /// 22 | /// Represents an error that occurred during method execution, following the 23 | /// JSON-RPC 2.0 error object specification with optional additional data. 24 | /// 25 | /// See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object) 26 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] 27 | #[non_exhaustive] 28 | pub struct Error { 29 | /// A number indicating the error type that occurred. 30 | /// This must be an integer as defined in the JSON-RPC specification. 31 | pub code: i32, 32 | /// A string providing a short description of the error. 33 | /// The message should be limited to a concise single sentence. 34 | pub message: String, 35 | /// Optional primitive or structured value that contains additional information about the error. 36 | /// This may include debugging information or context-specific details. 37 | #[serde(skip_serializing_if = "Option::is_none")] 38 | pub data: Option, 39 | } 40 | 41 | impl Error { 42 | /// Creates a new error with the given code and message. 43 | /// 44 | /// The code parameter can be an `ErrorCode` constant or a tuple of (code, message). 45 | pub fn new(code: i32, message: impl Into) -> Self { 46 | Error { 47 | code, 48 | message: message.into(), 49 | data: None, 50 | } 51 | } 52 | 53 | /// Adds additional data to the error. 54 | /// 55 | /// This method is chainable and allows attaching context-specific information 56 | /// to help with debugging or provide more details about the error. 57 | #[must_use] 58 | pub fn data(mut self, data: impl Into) -> Self { 59 | self.data = Some(data.into()); 60 | self 61 | } 62 | 63 | /// Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. 64 | #[must_use] 65 | pub fn parse_error() -> Self { 66 | ErrorCode::PARSE_ERROR.into() 67 | } 68 | 69 | /// The JSON sent is not a valid Request object. 70 | #[must_use] 71 | pub fn invalid_request() -> Self { 72 | ErrorCode::INVALID_REQUEST.into() 73 | } 74 | 75 | /// The method does not exist / is not available. 76 | #[must_use] 77 | pub fn method_not_found() -> Self { 78 | ErrorCode::METHOD_NOT_FOUND.into() 79 | } 80 | 81 | /// Invalid method parameter(s). 82 | #[must_use] 83 | pub fn invalid_params() -> Self { 84 | ErrorCode::INVALID_PARAMS.into() 85 | } 86 | 87 | /// Internal JSON-RPC error. 88 | #[must_use] 89 | pub fn internal_error() -> Self { 90 | ErrorCode::INTERNAL_ERROR.into() 91 | } 92 | 93 | /// Authentication required. 94 | #[must_use] 95 | pub fn auth_required() -> Self { 96 | ErrorCode::AUTH_REQUIRED.into() 97 | } 98 | 99 | /// A given resource, such as a file, was not found. 100 | #[must_use] 101 | pub fn resource_not_found(uri: Option) -> Self { 102 | let err: Self = ErrorCode::RESOURCE_NOT_FOUND.into(); 103 | if let Some(uri) = uri { 104 | err.data(serde_json::json!({ "uri": uri })) 105 | } else { 106 | err 107 | } 108 | } 109 | 110 | /// Converts a standard error into an internal JSON-RPC error. 111 | /// 112 | /// The error's string representation is included as additional data. 113 | pub fn into_internal_error(err: impl std::error::Error) -> Self { 114 | Error::internal_error().data(err.to_string()) 115 | } 116 | } 117 | 118 | /// Predefined error codes for common JSON-RPC and ACP-specific errors. 119 | /// 120 | /// These codes follow the JSON-RPC 2.0 specification for standard errors 121 | /// and use the reserved range (-32000 to -32099) for protocol-specific errors. 122 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] 123 | #[non_exhaustive] 124 | pub struct ErrorCode { 125 | /// The numeric error code. 126 | pub code: i32, 127 | /// The standard error message for this code. 128 | pub message: &'static str, 129 | } 130 | 131 | impl ErrorCode { 132 | /// Invalid JSON was received by the server. 133 | /// An error occurred on the server while parsing the JSON text. 134 | pub const PARSE_ERROR: ErrorCode = ErrorCode { 135 | code: -32700, 136 | message: "Parse error", 137 | }; 138 | 139 | /// The JSON sent is not a valid Request object. 140 | pub const INVALID_REQUEST: ErrorCode = ErrorCode { 141 | code: -32600, 142 | message: "Invalid Request", 143 | }; 144 | 145 | /// The method does not exist or is not available. 146 | pub const METHOD_NOT_FOUND: ErrorCode = ErrorCode { 147 | code: -32601, 148 | message: "Method not found", 149 | }; 150 | 151 | /// Invalid method parameter(s). 152 | pub const INVALID_PARAMS: ErrorCode = ErrorCode { 153 | code: -32602, 154 | message: "Invalid params", 155 | }; 156 | 157 | /// Internal JSON-RPC error. 158 | /// Reserved for implementation-defined server errors. 159 | pub const INTERNAL_ERROR: ErrorCode = ErrorCode { 160 | code: -32603, 161 | message: "Internal error", 162 | }; 163 | 164 | /// Authentication is required before this operation can be performed. 165 | /// This is an ACP-specific error code in the reserved range. 166 | pub const AUTH_REQUIRED: ErrorCode = ErrorCode { 167 | code: -32000, 168 | message: "Authentication required", 169 | }; 170 | 171 | /// A given resource, such as a file, was not found. 172 | /// This is an ACP-specific error code in the reserved range. 173 | pub const RESOURCE_NOT_FOUND: ErrorCode = ErrorCode { 174 | code: -32002, 175 | message: "Resource not found", 176 | }; 177 | } 178 | 179 | impl From for Error { 180 | fn from(error_code: ErrorCode) -> Self { 181 | Error::new(error_code.code, error_code.message) 182 | } 183 | } 184 | 185 | impl std::error::Error for Error {} 186 | 187 | impl Display for Error { 188 | fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 189 | if self.message.is_empty() { 190 | write!(f, "{}", self.code)?; 191 | } else { 192 | write!(f, "{}", self.message)?; 193 | } 194 | 195 | if let Some(data) = &self.data { 196 | let pretty = serde_json::to_string_pretty(data).unwrap_or_else(|_| data.to_string()); 197 | write!(f, ": {pretty}")?; 198 | } 199 | 200 | Ok(()) 201 | } 202 | } 203 | 204 | impl From for Error { 205 | fn from(error: anyhow::Error) -> Self { 206 | match error.downcast::() { 207 | Ok(error) => error, 208 | Err(error) => Error::into_internal_error(&*error), 209 | } 210 | } 211 | } 212 | 213 | impl From for Error { 214 | fn from(error: serde_json::Error) -> Self { 215 | Error::invalid_params().data(error.to_string()) 216 | } 217 | } 218 | -------------------------------------------------------------------------------- /rust/ext.rs: -------------------------------------------------------------------------------- 1 | //! Extension types and constants for protocol extensibility. 2 | use derive_more::From; 3 | use schemars::JsonSchema; 4 | use serde::{Deserialize, Serialize}; 5 | use serde_json::value::RawValue; 6 | use std::sync::Arc; 7 | 8 | /// Allows for sending an arbitrary request that is not part of the ACP spec. 9 | /// Extension methods provide a way to add custom functionality while maintaining 10 | /// protocol compatibility. 11 | /// 12 | /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) 13 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] 14 | #[serde(transparent)] 15 | #[non_exhaustive] 16 | pub struct ExtRequest { 17 | #[serde(skip)] // this is used for routing, but when serializing we only want the params 18 | pub method: Arc, 19 | #[schemars(with = "serde_json::Value")] 20 | pub params: Arc, 21 | } 22 | 23 | impl ExtRequest { 24 | pub fn new(method: impl Into>, params: Arc) -> Self { 25 | Self { 26 | method: method.into(), 27 | params, 28 | } 29 | } 30 | } 31 | 32 | /// Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec. 33 | /// Extension methods provide a way to add custom functionality while maintaining 34 | /// protocol compatibility. 35 | /// 36 | /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) 37 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, From)] 38 | #[serde(transparent)] 39 | #[non_exhaustive] 40 | pub struct ExtResponse(#[schemars(with = "serde_json::Value")] pub Arc); 41 | 42 | impl ExtResponse { 43 | #[must_use] 44 | pub fn new(params: Arc) -> Self { 45 | Self(params) 46 | } 47 | } 48 | 49 | /// Allows the Agent to send an arbitrary notification that is not part of the ACP spec. 50 | /// Extension notifications provide a way to send one-way messages for custom functionality 51 | /// while maintaining protocol compatibility. 52 | /// 53 | /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) 54 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] 55 | #[serde(transparent)] 56 | #[non_exhaustive] 57 | pub struct ExtNotification { 58 | #[serde(skip)] // this is used for routing, but when serializing we only want the params 59 | pub method: Arc, 60 | #[schemars(with = "serde_json::Value")] 61 | pub params: Arc, 62 | } 63 | 64 | impl ExtNotification { 65 | pub fn new(method: impl Into>, params: Arc) -> Self { 66 | Self { 67 | method: method.into(), 68 | params, 69 | } 70 | } 71 | } 72 | -------------------------------------------------------------------------------- /rust/plan.rs: -------------------------------------------------------------------------------- 1 | //! Execution plans for complex tasks that require multiple steps. 2 | //! 3 | //! Plans are strategies that agents share with clients through session updates, 4 | //! providing real-time visibility into their thinking and progress. 5 | //! 6 | //! See: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan) 7 | 8 | use schemars::JsonSchema; 9 | use serde::{Deserialize, Serialize}; 10 | 11 | /// An execution plan for accomplishing complex tasks. 12 | /// 13 | /// Plans consist of multiple entries representing individual tasks or goals. 14 | /// Agents report plans to clients to provide visibility into their execution strategy. 15 | /// Plans can evolve during execution as the agent discovers new requirements or completes tasks. 16 | /// 17 | /// See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan) 18 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] 19 | #[serde(rename_all = "camelCase")] 20 | #[non_exhaustive] 21 | pub struct Plan { 22 | /// The list of tasks to be accomplished. 23 | /// 24 | /// When updating a plan, the agent must send a complete list of all entries 25 | /// with their current status. The client replaces the entire plan with each update. 26 | pub entries: Vec, 27 | /// Extension point for implementations 28 | #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] 29 | pub meta: Option, 30 | } 31 | 32 | impl Plan { 33 | #[must_use] 34 | pub fn new(entries: Vec) -> Self { 35 | Self { 36 | entries, 37 | meta: None, 38 | } 39 | } 40 | 41 | /// Extension point for implementations 42 | #[must_use] 43 | pub fn meta(mut self, meta: serde_json::Value) -> Self { 44 | self.meta = Some(meta); 45 | self 46 | } 47 | } 48 | 49 | /// A single entry in the execution plan. 50 | /// 51 | /// Represents a task or goal that the assistant intends to accomplish 52 | /// as part of fulfilling the user's request. 53 | /// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) 54 | #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] 55 | #[serde(rename_all = "camelCase")] 56 | #[non_exhaustive] 57 | pub struct PlanEntry { 58 | /// Human-readable description of what this task aims to accomplish. 59 | pub content: String, 60 | /// The relative importance of this task. 61 | /// Used to indicate which tasks are most critical to the overall goal. 62 | pub priority: PlanEntryPriority, 63 | /// Current execution status of this task. 64 | pub status: PlanEntryStatus, 65 | /// Extension point for implementations 66 | #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] 67 | pub meta: Option, 68 | } 69 | 70 | impl PlanEntry { 71 | pub fn new( 72 | content: impl Into, 73 | priority: PlanEntryPriority, 74 | status: PlanEntryStatus, 75 | ) -> Self { 76 | Self { 77 | content: content.into(), 78 | priority, 79 | status, 80 | meta: None, 81 | } 82 | } 83 | 84 | /// Extension point for implementations 85 | #[must_use] 86 | pub fn meta(mut self, meta: serde_json::Value) -> Self { 87 | self.meta = Some(meta); 88 | self 89 | } 90 | } 91 | 92 | /// Priority levels for plan entries. 93 | /// 94 | /// Used to indicate the relative importance or urgency of different 95 | /// tasks in the execution plan. 96 | /// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) 97 | #[derive(Deserialize, Serialize, JsonSchema, Debug, Clone, PartialEq, Eq)] 98 | #[serde(rename_all = "snake_case")] 99 | #[non_exhaustive] 100 | pub enum PlanEntryPriority { 101 | /// High priority task - critical to the overall goal. 102 | High, 103 | /// Medium priority task - important but not critical. 104 | Medium, 105 | /// Low priority task - nice to have but not essential. 106 | Low, 107 | } 108 | 109 | /// Status of a plan entry in the execution flow. 110 | /// 111 | /// Tracks the lifecycle of each task from planning through completion. 112 | /// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries) 113 | #[derive(Deserialize, Serialize, JsonSchema, Debug, Clone, PartialEq, Eq)] 114 | #[serde(rename_all = "snake_case")] 115 | #[non_exhaustive] 116 | pub enum PlanEntryStatus { 117 | /// The task has not started yet. 118 | Pending, 119 | /// The task is currently being worked on. 120 | InProgress, 121 | /// The task has been successfully completed. 122 | Completed, 123 | } 124 | -------------------------------------------------------------------------------- /rust/version.rs: -------------------------------------------------------------------------------- 1 | use derive_more::{Display, From}; 2 | use schemars::JsonSchema; 3 | use serde::Serialize; 4 | 5 | /// Protocol version identifier. 6 | /// 7 | /// This version is only bumped for breaking changes. 8 | /// Non-breaking changes should be introduced via capabilities. 9 | #[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq, PartialOrd, Ord, From, Display)] 10 | pub struct ProtocolVersion(u16); 11 | 12 | impl ProtocolVersion { 13 | /// Version `0` of the protocol. 14 | /// 15 | /// This was a pre-release version that shouldn't be used in production. 16 | /// It is used as a fallback for any request whose version cannot be parsed 17 | /// as a valid version, and should likely be treated as unsupported. 18 | pub const V0: Self = Self(0); 19 | /// Version `1` of the protocol. 20 | /// 21 | /// 22 | pub const V1: Self = Self(1); 23 | /// The latest supported version of the protocol. 24 | /// 25 | /// Currently, this is version `1`. 26 | pub const LATEST: Self = Self::V1; 27 | 28 | #[cfg(test)] 29 | #[must_use] 30 | pub const fn new(version: u16) -> Self { 31 | Self(version) 32 | } 33 | } 34 | 35 | use serde::{Deserialize, Deserializer}; 36 | 37 | impl<'de> Deserialize<'de> for ProtocolVersion { 38 | fn deserialize(deserializer: D) -> Result 39 | where 40 | D: Deserializer<'de>, 41 | { 42 | use serde::de::{self, Visitor}; 43 | use std::fmt; 44 | 45 | struct ProtocolVersionVisitor; 46 | 47 | impl Visitor<'_> for ProtocolVersionVisitor { 48 | type Value = ProtocolVersion; 49 | 50 | fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { 51 | formatter.write_str("a protocol version number or string") 52 | } 53 | 54 | fn visit_u64(self, value: u64) -> Result 55 | where 56 | E: de::Error, 57 | { 58 | match u16::try_from(value) { 59 | Ok(value) => Ok(ProtocolVersion(value)), 60 | Err(_) => Err(E::custom(format!("protocol version {value} is too large"))), 61 | } 62 | } 63 | 64 | fn visit_str(self, _value: &str) -> Result 65 | where 66 | E: de::Error, 67 | { 68 | // Old versions used strings, we consider all of those version 0 69 | Ok(ProtocolVersion::V0) 70 | } 71 | 72 | fn visit_string(self, _value: String) -> Result 73 | where 74 | E: de::Error, 75 | { 76 | // Old versions used strings, we consider all of those version 0 77 | Ok(ProtocolVersion::V0) 78 | } 79 | } 80 | 81 | deserializer.deserialize_any(ProtocolVersionVisitor) 82 | } 83 | } 84 | 85 | #[cfg(test)] 86 | mod tests { 87 | use super::*; 88 | 89 | #[test] 90 | fn test_deserialize_u64() { 91 | let json = "1"; 92 | let version: ProtocolVersion = serde_json::from_str(json).unwrap(); 93 | assert_eq!(version, ProtocolVersion::new(1)); 94 | } 95 | 96 | #[test] 97 | fn test_deserialize_string() { 98 | let json = "\"1.0.0\""; 99 | let version: ProtocolVersion = serde_json::from_str(json).unwrap(); 100 | assert_eq!(version, ProtocolVersion::new(0)); 101 | } 102 | 103 | #[test] 104 | fn test_deserialize_large_number() { 105 | let json = "100000"; 106 | let result: Result = serde_json::from_str(json); 107 | assert!(result.is_err()); 108 | } 109 | 110 | #[test] 111 | fn test_deserialize_zero() { 112 | let json = "0"; 113 | let version: ProtocolVersion = serde_json::from_str(json).unwrap(); 114 | assert_eq!(version, ProtocolVersion::new(0)); 115 | } 116 | 117 | #[test] 118 | fn test_deserialize_max_u16() { 119 | let json = "65535"; 120 | let version: ProtocolVersion = serde_json::from_str(json).unwrap(); 121 | assert_eq!(version, ProtocolVersion::new(65535)); 122 | } 123 | } 124 | -------------------------------------------------------------------------------- /schema/meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "agentMethods": { 3 | "authenticate": "authenticate", 4 | "initialize": "initialize", 5 | "session_cancel": "session/cancel", 6 | "session_load": "session/load", 7 | "session_new": "session/new", 8 | "session_prompt": "session/prompt", 9 | "session_set_mode": "session/set_mode" 10 | }, 11 | "clientMethods": { 12 | "fs_read_text_file": "fs/read_text_file", 13 | "fs_write_text_file": "fs/write_text_file", 14 | "session_request_permission": "session/request_permission", 15 | "session_update": "session/update", 16 | "terminal_create": "terminal/create", 17 | "terminal_kill": "terminal/kill", 18 | "terminal_output": "terminal/output", 19 | "terminal_release": "terminal/release", 20 | "terminal_wait_for_exit": "terminal/wait_for_exit" 21 | }, 22 | "version": 1 23 | } 24 | -------------------------------------------------------------------------------- /schema/meta.unstable.json: -------------------------------------------------------------------------------- 1 | { 2 | "agentMethods": { 3 | "authenticate": "authenticate", 4 | "initialize": "initialize", 5 | "session_cancel": "session/cancel", 6 | "session_list": "session/list", 7 | "session_load": "session/load", 8 | "session_new": "session/new", 9 | "session_prompt": "session/prompt", 10 | "session_set_mode": "session/set_mode", 11 | "session_set_model": "session/set_model" 12 | }, 13 | "clientMethods": { 14 | "fs_read_text_file": "fs/read_text_file", 15 | "fs_write_text_file": "fs/write_text_file", 16 | "session_request_permission": "session/request_permission", 17 | "session_update": "session/update", 18 | "terminal_create": "terminal/create", 19 | "terminal_kill": "terminal/kill", 20 | "terminal_output": "terminal/output", 21 | "terminal_release": "terminal/release", 22 | "terminal_wait_for_exit": "terminal/wait_for_exit" 23 | }, 24 | "version": 1 25 | } 26 | -------------------------------------------------------------------------------- /scripts/spellcheck.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Check if typos is installed 4 | if ! command -v typos &> /dev/null; then 5 | echo "Error: typos is not installed." 6 | echo "Please install it using one of the following methods:" 7 | echo "" 8 | echo " Using Cargo:" 9 | echo " cargo install typos-cli" 10 | echo "" 11 | echo "" 12 | echo "For more installation options, see: https://github.com/crate-ci/typos" 13 | exit 1 14 | fi 15 | 16 | # Run typos with the provided arguments, defaulting to current directory 17 | if [ $# -eq 0 ]; then 18 | typos --config ./typos.toml 19 | else 20 | typos --config ./typos.toml "$@" 21 | fi 22 | -------------------------------------------------------------------------------- /typos.toml: -------------------------------------------------------------------------------- 1 | [files] 2 | ignore-files = true 3 | ignore-hidden = false 4 | extend-exclude = [ 5 | ".git/", 6 | "target/", 7 | "node_modules/", 8 | "dist/", 9 | 10 | # Generated schema files 11 | "schema/", 12 | 13 | # Package lock files contain hashes and encoded data 14 | "package-lock.json", 15 | "Cargo.lock", 16 | ] 17 | 18 | [default] 19 | extend-ignore-re = [ 20 | ] 21 | check-filename = true 22 | 23 | [default.extend-identifiers] 24 | ndJsonStream = "ndJsonStream" 25 | --------------------------------------------------------------------------------