連線 Buda ACP

按步驟把 Zed、JetBrains 或你自己的程式連線到託管在 Buda 雲端的智慧體。

透過 Agent Client Protocol（ACP），你可以在 Zed、JetBrains 或自己的程式裡，直接與一個託管在 Buda 雲端的智慧體對話。回覆、思考過程和工具呼叫會透過標準 ACP 事件串流返回，不需要在本機執行智慧體或模型。

完成接入後，你將得到這條連線：

Zed / JetBrains / 你的程式
          │ ACP
          ▼
wss://buda.im/api/acp?agentId=...
          │
          ▼
Buda 智慧體 → 雲端沙箱 → 已連線的知識庫與整合

Buda 智慧體執行在雲端沙箱中，不會自動讀取你編輯器目前開啟的本機目錄。要讓它處理程式碼倉庫，請先為該智慧體連線 GitHub，或把所需內容放進它能存取的知識庫與整合中。

選擇接入方式

你的場景	建議方式	是否需要橋接
在 Zed 中使用	`acpremote` + Zed 自訂智慧體	需要
在 JetBrains AI Chat 中使用	`acpremote` + `~/.jetbrains/acp.json`	需要
Node.js、指令碼或 CI	使用 `@agentclientprotocol/sdk` 直連 WebSocket	不需要
其他支援遠端 WebSocket 和自訂請求標頭的 ACP 用戶端	直接連線 Buda 端點	不需要
瀏覽器前端	不建議直接連線	瀏覽器 WebSocket 無法傳送 `Authorization` 標頭

Zed 和 JetBrains 的自訂 ACP 設定會啟動一個本機 command，而 Buda 提供的是遠端 WebSocket 端點。因此編輯器場景需要一個很小的 stdio ↔ WebSocket 橋接程式。本文使用第三方開源工具 acpremote；它只轉發 ACP 訊息，不會在本機執行 Buda 智慧體。

開始之前

準備以下內容：

一個你有權存取的 Buda 智慧體；
該智慧體的 agentId；
一個以 sk_ 開頭的 Buda API 金鑰；
如果使用編輯器：本機已安裝 Python，並能執行 acpremote。

目前 ACP 連線會自動批准智慧體發起的工具呼叫，不會彈出逐次權限確認。請只連線你信任的倉庫、知識庫和外部系統，並為測試與正式環境使用不同的 API 金鑰。

第 1 步：取得智慧體 ID

開啟要連線的智慧體。瀏覽器網址通常如下：

https://buda.im/agents/your_agent_id

/agents/ 後面的值就是可使用的 agentId。如果你透過 REST API 建立智慧體，也可以直接使用建立介面返回的 id。

例如：

export BUDA_AGENT_ID="your_agent_id"

一條 ACP 連線只會繫結一個智慧體。要驅動另一個智慧體，請使用不同的 agentId 建立新連線。

第 2 步：建立 API 金鑰

開啟「設定 → API 金鑰」

在 Buda 控制台中進入 設定 → API 金鑰，選擇 新建金鑰。

為用途命名並設定有效期

例如命名為 zed-acp、jetbrains-acp 或 ci-acp。測試時優先選擇較短的有效期。

立即複製完整金鑰

完整的 sk_... 只會顯示一次。請把它儲存到密碼管理器或密鑰儲存服務中。

設定 ACP 前，先用 REST API 驗證金鑰：

export BUDA_API_KEY="sk_your_api_key"

curl https://buda.im/api/v1/users/me \
  -H "Authorization: Bearer $BUDA_API_KEY"

端點返回目前使用者後，再繼續設定 ACP。若返回 401 Unauthorized，請先重新建立或更換金鑰。

第 3 步：組成 ACP 端點

Buda ACP 使用以下連線參數：

設定項	值
WebSocket 端點	`wss://buda.im/api/acp?agentId=<agentId>`
認證標頭	`Authorization: Bearer sk_...`
傳輸方式	WebSocket
每條連線可驅動的智慧體	1 個

組成完整網址：

export BUDA_ACP_URL="wss://buda.im/api/acp?agentId=$BUDA_AGENT_ID"

API 金鑰必須屬於有權存取該智慧體的 Buda 使用者。金鑰無效、agentId 不存在，或金鑰所有者沒有權限時，initialize 會失敗，連線隨後關閉。

第 4 步：連線編輯器

安裝橋接程式

建議把 acpremote 安裝成獨立命令：

uv tool install acpremote

沒有使用 uv 時，也可以透過 Python 安裝：

python -m pip install --user acpremote

確認編輯器能找到該命令：

command -v acpremote
acpremote --help

記下 command -v acpremote 返回的絕對路徑。從桌面啟動的圖形介面編輯器可能不會繼承終端機的 PATH，因此使用絕對路徑最可靠。

Zed

在 Zed 中開啟 Agent Settings → External Agents → Add Agent → Add Custom Agent，然後在 settings.json 加入：

Zed settings.json

{
  "agent_servers": {
    "Buda": {
      "type": "custom",
      "command": "/absolute/path/to/acpremote",
      "args": [
        "mirror",
        "wss://buda.im/api/acp?agentId=your_agent_id",
        "--token-env",
        "BUDA_API_KEY"
      ],
      "env": {
        "BUDA_API_KEY": "sk_your_api_key"
      }
    }
  }
}

儲存設定後，在 Agent Panel 中建立一個新的 Buda 會話，並傳送：

只回覆：Buda ACP connected

看到串流回覆即表示連線成功。如果智慧體選擇器裡沒有出現 Buda，請重新啟動 Zed，並確認 command 指向真實存在的可執行檔。

JetBrains

在 AI Chat 中選擇 Add Custom Agent。JetBrains 會建立並開啟 ~/.jetbrains/acp.json：

~/.jetbrains/acp.json

{
  "default_mcp_settings": {},
  "agent_servers": {
    "Buda": {
      "command": "/absolute/path/to/acpremote",
      "args": [
        "mirror",
        "wss://buda.im/api/acp?agentId=your_agent_id",
        "--token-env",
        "BUDA_API_KEY"
      ],
      "env": {
        "BUDA_API_KEY": "sk_your_api_key"
      }
    }
  }
}

儲存檔案後，在 AI Chat 的智慧體選擇器中選擇 Buda，建立會話並傳送一條測試訊息。

以上最短設定會把 API 金鑰儲存在編輯器的本機設定檔中。不要把該檔案同步到公開倉庫；請限制檔案讀取權限，並在不再使用時刪除或輪換金鑰。團隊環境建議為每位成員、每個環境分別建立金鑰。

其他編輯器

如果其他編輯器的自訂 ACP 設定同樣接受 command 和 args，讓編輯器啟動以下本機命令：

BUDA_API_KEY="sk_your_api_key" acpremote mirror \
  "wss://buda.im/api/acp?agentId=your_agent_id" \
  --token-env BUDA_API_KEY

如果用戶端原生支援遠端 ACP WebSocket，並能在握手時傳送自訂 Authorization 標頭，便可略過 acpremote，直接連線 Buda。

第 5 步：從 Node.js 或 CI 直連

程式化用戶端不需要 stdio 橋接。安裝 ACP SDK 與 Node WebSocket 實作：

npm install @agentclientprotocol/sdk ws

建立 buda-acp.mjs：

buda-acp.mjs

import * as acp from "@agentclientprotocol/sdk";
import { createWebSocketStream } from "@agentclientprotocol/sdk/experimental/ws-client";
import WebSocket from "ws";

const apiKey = process.env.BUDA_API_KEY;
const agentId = process.env.BUDA_AGENT_ID;

if (!apiKey || !agentId) {
  throw new Error("Set BUDA_API_KEY and BUDA_AGENT_ID first.");
}

const stream = createWebSocketStream(
  `wss://buda.im/api/acp?agentId=${encodeURIComponent(agentId)}`,
  {
    WebSocket,
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

const client = acp
  .client({ name: "buda-acp-quickstart" })
  .onNotification(acp.methods.client.session.update, ({ params }) => {
    const update = params.update;
    if (update.sessionUpdate === "agent_message_chunk" && update.content.type === "text") {
      process.stdout.write(update.content.text);
    }
  });

const result = await client.connectWith(stream, async (connection) => {
  const initialized = await connection.request(acp.methods.agent.initialize, {
    protocolVersion: acp.PROTOCOL_VERSION,
    clientCapabilities: {},
  });

  const session = await connection.request(acp.methods.agent.session.new, {
    cwd: process.cwd(),
    mcpServers: [],
  });

  const response = await connection.request(acp.methods.agent.session.prompt, {
    sessionId: session.sessionId,
    prompt: [{ type: "text", text: "只回覆：Buda ACP connected" }],
  });

  return {
    sessionId: session.sessionId,
    stopReason: response.stopReason,
    canLoadSession: initialized.agentCapabilities?.loadSession === true,
  };
});

console.log("\n", result);

執行：

BUDA_API_KEY="sk_your_api_key" \
BUDA_AGENT_ID="your_agent_id" \
node buda-acp.mjs

你應該先看到串流文字，隨後看到包含 sessionId、stopReason 和 canLoadSession: true 的結果。

createWebSocketStream 目前位於 SDK 的 experimental/ws-client 匯出路徑。升級 @agentclientprotocol/sdk 時，請檢查該匯出路徑是否有變更。

會話如何運作

一次正常的 ACP 呼叫順序如下：

initialize：協商協定版本與能力；
session/new：建立一個 Buda 會話並取得 sessionId；
session/prompt：傳送訊息；
接收多個 session/update：串流顯示回覆、思考與工具呼叫；
儲存 sessionId；斷線後重新 initialize，再使用 session/load 恢復會話；
需要停止執行時傳送 session/cancel。

ACP 方法	Buda 行為
`initialize`	協商版本；宣告支援 `loadSession`
`session/new`	為目前連線繫結的智慧體建立新會話
`session/prompt`	傳送一輪訊息，並透過 `session/update` 串流返回結果
`session/load`	重新接入進行中的串流，或重播已儲存的會話歷史
`session/cancel`	停止指定會話中正在執行的一輪任務

目前 prompt 內容支援 text 和 resource_link。圖片、音訊與內嵌資源內容尚未開放。

故障排查

現象	最可能的原因	解決方法
編輯器裡沒有出現 Buda	編輯器找不到 `acpremote`	把 `command` 改為 `command -v acpremote` 返回的絕對路徑，然後重新啟動編輯器
`initialize` 後立即斷線	金鑰無效、過期，或 `agentId` 錯誤	先呼叫 `/api/v1/users/me` 驗證金鑰，再從智慧體網址重新複製 ID
伺服器返回無權存取	API 金鑰所屬使用者不是智慧體擁有者或空間成員	使用有權限的帳戶建立金鑰，或把使用者加入對應空間
智慧體看不到本機專案檔案	Buda 使用遠端沙箱，不使用編輯器本機目錄	為智慧體連線 GitHub，或把檔案上傳到它能存取的位置
第二條訊息提示已有任務執行中	同一會話不支援並行 `session/prompt`	等待目前任務結束，或先傳送 `session/cancel`
瀏覽器 WebSocket 無法認證	瀏覽器無法設定 WebSocket 握手的 `Authorization` 標頭	從可信後端或 Node.js 用戶端連線；不要把 `sk_` 金鑰放進前端程式碼
長時間任務中途斷線	VPN、代理或網路閘道關閉了長連線 WebSocket	檢查 WebSocket 支援與閒置逾時，然後用已儲存的 `sessionId` 執行 `session/load`
工具呼叫沒有確認視窗	目前 Buda ACP 會自動批准工具	限制智慧體可存取的資料與整合，使用最小權限金鑰，並避免連線敏感系統

在 Zed 中，可以從命令面板執行 ACP: Open ACP Logs，檢視 Zed 與橋接程序之間的 ACP 訊息。JetBrains 使用者可從 AI Assistant 日誌與 acpremote 的標準錯誤輸出檢查啟動失敗原因。

目前限制

僅支援 WebSocket。 Buda ACP 尚未提供 Streamable HTTP profile。
沒有逐次權限確認。 目前工具呼叫會自動批准。
同一會話一次只能執行一條 prompt。 並行傳送會被拒絕，不會自動排隊。
一條連線只對應一個智慧體。 多個智慧體需要多條連線。
僅接受 sk_ API 金鑰。 不接受瀏覽器會話 Cookie、OAuth 令牌或內部智慧體金鑰。
遠端沙箱擁有工作目錄。 用戶端傳入的本機 cwd 與 MCP server 清單不會讓 Buda 存取本機電腦。

參考實作

本文的接入方式與以下資料保持一致：