agentclientprotocol/agent-client-protocol

Agent Client Protocol (ACP)

是什麼 – ACP 是一種 標準化、語言無關的協定，讓 程式碼編輯器 能與 程式碼代理（使用生成式 AI 自動讀取、撰寫與重構原始碼的程式）進行通訊。此協定定義了雙方之間傳輸的 JSON-RPC 風格訊息（請求、回應、通知），並包含版本協商機制，讓編輯器與代理能獨立演進而不互相破壞。

為何重要 – 隨著 AI 驅動的「結對程式設計」工具（如 GitHub Copilot、Cursor、基於 Code Llama 的助手）日益普及，各廠商過去都自行設計臨時的 API。ACP 提供一個 共同契約，使：

• 編輯器可透過單一整合層支援多個代理。
• 代理只需撰寫一次，即可在任何實作 ACP 的編輯器中執行。
• 多種語言的 SDK 可從同一 JSON-Schema 定義生成類型安全的客戶端/代理程式碼。

核心資產

• Rust crate agent-client-protocol-schema – 與網路格式（訊息、封包、版本資訊）對應的低階 Rust 類型。當你需要直接存取模式或希望為其他語言生成程式碼時使用。
• Rust crate agent-client-protocol – 高階執行時，實作客戶端與代理端，處理連接設定、訊息路由與能力協商。
• JSON-Schema 檔案 – 版本化的模式檔案位於 schema/v1/ 與 schema/v2/。每次發行都會將 .json 檔案作為 GitHub 資產打包，供 SDK 產生器（Kotlin、Java、Python、TypeScript 等）消費，生成特定語言的函式庫。

版本控制模型

• 協定版本（目前為 1）透過 initialize 請求的 protocolVersion 欄位在執行時協商。這決定了可交換訊息的結構。
• crate 與 schema 的發行號與網路相容性 獨立；它們僅反映 Rust API 或 JSON-Schema 檔案佈局的變更。相容性由協商的協定版本與雙方宣告的能力決定。

官方 SDK

語言	倉儲	亮點
Kotlin	acp-kotlin	JVM 支援，範例客戶端/代理專案
Java	java-sdk	Maven/Gradle 資產，範例
Python	python-sdk	pip 套件，快速入門指令碼
Rust	agent-client-protocol	Crates.io 套件，範例 agent.rs / client.rs
TypeScript	@agentclientprotocol/sdk	npm 套件，瀏覽器與 Node 範例

典型工作流程

1. 選擇與你的編輯器或代理實作相匹配的語言 SDK。
2. 產生或匯入 SDK（大多已發佈於 crates.io、Maven Central、PyPI、npm 等平台）。
3. 在編輯器中實作客戶端：註冊通知（如 codeChange、applyEdits）並發送 generateCode 或 refactor 等請求。
4. 實作代理端：接收請求，呼叫生成式 AI 模型，並回傳編輯或診斷結果。
5. 在 initialize 交換期間協商能力，使雙方知道哪些可選訊息被支援。

快速入門

• Rust: cargo add agent-client-protocol → 執行 rust-sdk/examples/ 中的範例，查看透過 stdin/stdout 通訊的最小客戶端與代理。
• Python: pip install agentclientprotocol → 按照 Python SDK 倉儲中的 examples/ 資料夾操作。
• Java/Kotlin/TypeScript: 克隆對應 SDK 倉儲，使用標準工具鏈建置，並執行提供的範例專案。

社群與貢獻

• 協定是故意 開放 的；任何人都可透過 GitHub 問題追蹤器與 CONTRIBUTING.md 中描述的正式貢獻流程提出擴充。
• 無需 CLA；貢獻採用 Apache 2.0 授權。
• 社群維護的函式庫清單可在官方網站取得。

誰應該關注？

• 希望以即插即用方式新增 AI 程式碼助手的 編輯器開發者（VS Code、JetBrains、Neovim 等）。
• 希望其服務能在多個開發環境中使用而無需撰寫自訂編輯器整合的 AI 代理建構者。
• 創建由 AI 代理驅動的程式碼分析、linting 或重構工具的 工具作者。

---

TL;DR – ACP 是一種跨語言協定，標準化了程式碼編輯器與生成式 AI 程式碼代理之間交換 JSON-RPC 訊息的方式。該倉儲託管權威的 Rust 模式 crate、版本化的 JSON-Schema 檔案，並提供 Kotlin、Java、Python、Rust 與 TypeScript 的官方 SDK 連結，推動 AI 輔助程式設計的統一生態系。