---
title: "Agent Client Protocol"
description: "基於 Cursor 官方 ACP 文件解釋 agent acp、stdio JSON-RPC、認證、session 流程、permissions、MCP 限制和自定義客戶端邊界。"
verifiedAt: "2026-05-09"
---

ACP 是給高階整合和自定義客戶端用的協議入口。普通終端工作流繼續用 `agent`；只有你要把 Cursor Agent 接進自己的 editor、IDE、TUI（Terminal User Interface，終端圖形化介面，如 Neovim / lazygit 風格）或自動化客戶端時，才需要 `agent acp`。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能解釋 ACP 的 transport、訊息格式、session 生命週期、許可權回撥，以及為什麼它不是普通使用者的第一入口。

## 1. ACP 適合誰

| 需求 | 是否適合 ACP | 理由 |
| --- | --- | --- |
| 在終端裡和 Agent 對話 | 不適合 | 直接用 `agent` 更簡單 |
| 給自研 IDE 外掛接 Cursor Agent | 適合 | 需要穩定協議和 UI 事件 |
| 給 Neovim / Zed 這類編輯器接入 Agent | 適合 | 由外掛作為 ACP client |
| 在 CI 裡跑一次審查 | 通常不需要 | `agent -p` 更直接 |
| 做多使用者 SaaS 後臺代理 | 高風險 | 需要認證、許可權、租戶隔離和審計設計 |

一句話：ACP 是整合介面（integration surface，給第三方編輯器 / IDE / TUI 接入 Cursor Agent 的協議入口），不是日常命令別名。

## 2. 啟動方式和協議形態

啟動 ACP server：

```bash
agent acp
```

官方定義的通訊形態：

| 專案 | 行為 |
| --- | --- |
| Transport | `stdio` |
| Envelope | JSON-RPC 2.0 |
| Framing | newline-delimited JSON |
| Client input | client 寫入 Cursor CLI 的 `stdin` |
| Agent output | Cursor CLI 向 `stdout` 寫 responses / notifications |
| Logs | 可能寫入 `stderr` |

這意味著你的客戶端必須正確處理 stdout 的逐行 JSON，不能把日誌、普通文本和協議訊息混在一起解析。

## 3. 標準 session 流程

官方給出的典型 ACP 流程可以理解為：

```mermaid
sequenceDiagram
  participant Client
  participant Agent as agent acp
  Client->>Agent: initialize
  Client->>Agent: authenticate cursor_login
  Client->>Agent: session/new or session/load
  Client->>Agent: session/prompt
  Agent-->>Client: session/update notifications
  Agent-->>Client: session/request_permission
  Client-->>Agent: permission decision
  Client->>Agent: session/cancel optional
```

如果客戶端不處理 `session/request_permission`，工具執行可能卡住。商業級客戶端必須把許可權請求做成明確 UI，而不是後臺預設允許。

## 4. 認證方式

ACP 會使用 `cursor_login` 認證方法。你也可以在啟動前透過 CLI 認證路徑準備好身份：

```bash
agent login
agent --api-key "$CURSOR_API_KEY" acp
agent --auth-token "$CURSOR_AUTH_TOKEN" acp
```

還可以傳 endpoint 和 TLS 相關選項：

```bash
agent -e https://api2.cursor.sh acp
agent -k acp
```

上線整合時不要把 `CURSOR_API_KEY` 或 `CURSOR_AUTH_TOKEN` 打進日誌。ACP 客戶端通常會處理更長的 stdout/stderr 流，更容易意外洩露環境變數和錯誤上下文。

## 5. Sessions、modes 和 permissions

ACP 支援建立或恢復 session：

| 能力 | 方法 |
| --- | --- |
| 新會話 | `session/new` |
| 恢復會話 | `session/load` |
| 發 prompt | `session/prompt` |
| 取消 | `session/cancel` |

核心 modes 與 CLI 一致：

| Mode | 含義 |
| --- | --- |
| `agent` | 完整工具訪問 |
| `plan` | 計劃模式，偏只讀和方案確認 |
| `ask` | 問答/只讀理解 |

許可權請求會透過 `session/request_permission` 回到 client。官方列出的決策包括：

- `allow-once`
- `allow-always`
- `reject-once`

商業級客戶端要預設 `allow-once` 起步，只有穩定低風險命令才允許使用者顯式選擇長期允許。

## 6. MCP 支援和限制

ACP 可以使用專案級或使用者級 `.cursor/mcp.json` 裡的 MCP servers。啟動 `agent` 時應從專案目錄啟動，並審批需要的 servers。

當前官方文件明確限制：Cursor dashboard 配置的 team-level MCP servers 不支援 ACP mode。

這對企業整合很重要。不要假設編輯器裡可用的 team MCP，在 ACP 自定義客戶端裡也能用。

## 7. Cursor extension methods

Cursor 會傳送一組擴充套件方法，讓自定義客戶端呈現更完整的 UI。

| Method | Type | 用途 |
| --- | --- | --- |
| `cursor/ask_question` | Blocking | 多選問題，需要使用者回答 |
| `cursor/create_plan` | Blocking | 請求使用者批准計劃 |
| `cursor/update_todos` | Notification | 更新 todo 狀態 |
| `cursor/task` | Notification | 通知 subagent task 完成 |
| `cursor/generate_image` | Notification | 通知生成圖片輸出 |

Blocking method 必須響應，否則 Agent 會等待。Notification 可以展示，但不需要回復。

一個最小許可權響應的思路：

```json
{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}
```

不要在客戶端裡把 permission request 靜默變成 `allow-always`。這會繞過使用者審查，也會讓企業許可權策略失去意義。

## 8. IDE 和自定義客戶端

官方文件列出的典型整合方向包括：

- JetBrains IDE：透過 JetBrains integration guide 接入。
- Neovim：例如 avante.nvim 透過 ACP provider 連線 `agent acp`。
- Zed：由 Zed extension spawn `agent acp` 並處理 stdio。
- Custom editors：自己實現 ACP client。

實現一個客戶端至少要覆蓋：

1. spawn `agent acp`。
2. 按行讀寫 JSON-RPC。
3. 處理 streaming `session/update`。
4. 處理 `session/request_permission`。
5. 根據需要實現 Cursor extension methods。
6. 安全處理認證、日誌和退出。

<details>
<summary>深讀：ACP 客戶端最容易漏掉什麼</summary>

最容易漏的是“等待使用者決定”的阻塞方法。比如計劃審批、問題回答、許可權請求，如果客戶端只展示文本流，不處理這些事件，Agent 看起來就像卡住。

第二個常見問題是把 stdout 當普通文本流。ACP 的 stdout 是協議流，必須逐行解析 JSON-RPC；日誌和除錯輸出應該走 stderr 或單獨面板。
</details>

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. 為什麼普通終端使用者不應該優先使用 ACP？
2. `session/request_permission` 如果不響應會發生什麼？
3. team-level MCP servers 為什麼不能直接假設在 ACP mode 可用？

透過標準：你能畫出一個最小 ACP client 的資料流，並說明認證、session、permission、streaming update 和日誌隔離怎麼處理。

## 官方來源

- [Cursor ACP](https://cursor.com/docs/cli/acp.md) —— 官方 ACP overview、啟動方式、transport、request flow、authentication、sessions、permissions、MCP、extension methods 和 IDE integrations。
- [Agent Client Protocol](https://agentclientprotocol.com/) —— ACP 官方協議說明。
- [Cursor MCP](https://cursor.com/docs/mcp.md) —— Cursor MCP 配置和使用背景。

## 接下來去哪

<Cards>
  <Card title="Headless 模式" description="繼續學習 scripts 和 automation 中如何使用 print mode。" href="/zh-Hant/docs/cursor/official/03-cli-automation/35-headless" />
  <Card title="MCP 與擴充套件" description="回到 Cursor MCP 配置和工具邊界。" href="/zh-Hant/docs/cursor/official/02-context-customization/21-mcp" />
</Cards>
