跳至主要內容

Agent Client Protocol

Mastra 支援 Agent Client Protocol (ACP)，讓你從 Mastra Agent 執行兼容 ACP 的編程助手。你可以使用 @mastra/acp，將編程助手進程封裝為 Mastra Tool 或子 Agent。

ACP 適用於 Claude Code、Amp、Codex 等編程助手，以及任何透過標準輸入和輸出實作 ACP 的可執行檔案。

適合使用 ACP 的情況
適合使用 ACP 的情況 的直接連結

  • Mastra Agent 應將程式碼檢查、編輯或程式碼庫任務委派給外部編程助手。
  • 兼容 ACP 的 Agent 進程應在多次呼叫之間保持運行，以保留工作階段上下文。
  • 父 Agent 需要在任務執行期間接收編程助手的即時輸出。
  • 兼容 ACP 的 Agent 在讀取或寫入檔案前，或執行操作前，需要顯示權限提示。
  • 檔案存取應透過 Mastra 的 Workspace 抽象層處理，而不是僅由進程直接存取。

ACP 的運作方式
ACP 的運作方式 的直接連結

@mastra/acp 會以子進程啟動已配置的 ACP Agent 命令，並透過標準輸入和輸出，以換行分隔的 JSON 與其通訊。

流程如下：

  1. 配置 command、args 和可選的連線設定。
  2. @mastra/acp 在首次使用時產生 ACP Agent 進程。
  3. 客戶端傳送 ACP initialize 和 session/new 請求。
  4. Mastra 透過 session/prompt 將使用者任務傳送給 ACP Agent。
  5. ACP Agent 將工作階段更新和訊息區塊串流傳回 Mastra。
  6. Mastra 傳回已緩衝的輸出、發出串流區塊，或處理權限輸入。
  7. 當 persistSession 為 false 時，ACP 連線會在提示完成後停止進程。AcpAgent 預設可讓可重用的進程在多次呼叫之間保持運行。

執行期間，ACP 客戶端也會處理權限請求和檔案操作。檔案讀寫會透過 Mastra 的 Workspace 進行，因此 ACP Agent 會在你提供的 Workspace 內運作。

開始使用
開始使用 的直接連結

將 @mastra/acp 安裝到已使用 @mastra/core 的項目中。此依賴套件需要 @mastra/core 的 1.34.0 或以上版本。

npm install @mastra/acp

@mastra/acp 匯出兩個 API：

  • createACPTool()：建立 Mastra Tool，將 task 字串傳送給 ACP Agent，並傳回 output 字串。
  • AcpAgent：將 ACP Agent 封裝為 Mastra 子 Agent，並支援 generate() 和 stream()。

將 ACP 用作子 Agent
將 ACP 用作子 Agent 的直接連結

當父 Mastra Agent 應以子 Agent 形式直接將任務委派給兼容 ACP 的編程助手時，請使用 AcpAgent。

src/mastra/agents/code-supervisor.ts
import { AcpAgent } from '@mastra/acp'
import { Agent } from '@mastra/core/agent'

const codeAgent = new AcpAgent({
  id: 'code-agent',
  name: 'Code Agent',
  description: 'An ACP-compatible coding agent that can inspect and edit files',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
})

export const codeSupervisor = new Agent({
  id: 'code-supervisor',
  name: 'Code Supervisor',
  instructions: 'Delegate code editing tasks to the code-agent subagent.',
  model: 'openai/gpt-5.6-sol',
  agents: {
    codeAgent,
  },
})

如需所有選項、方法和配置，請參閱 AcpAgent 參考資料。

將 ACP 用作 Tool
將 ACP 用作 Tool 的直接連結

當父 Mastra Agent 應自行決定何時以 Tool 形式呼叫 ACP Agent 時，請使用 createACPTool()。

src/mastra/agents/code-supervisor.ts
import { createACPTool } from '@mastra/acp'
import { Agent } from '@mastra/core/agent'

const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent to inspect and edit code',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
})

export const codeSupervisor = new Agent({
  id: 'code-supervisor',
  name: 'Code Supervisor',
  instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
  model: 'openai/gpt-5.6-sol',
  tools: {
    codeAgentTool,
  },
})

如需所有選項和配置，請參閱 createACPTool() 參考資料。

選擇模型
選擇模型 的直接連結

ACP Agent 可能會提供可選模型。在 ACP 配置中傳入 model，即可在建立工作階段後選擇模型；你亦可使用 AcpAgent.getAvailableModels() 和 AcpAgent.setModel()，在執行階段管理模型。

如需範例，請參閱 AcpAgent 模型管理方法。

工作階段生命週期
工作階段生命週期 的直接連結

AcpAgent 會在首次使用時啟動已配置的命令，並建立 ACP 工作階段。persistSession 預設為 true，因此子進程會在多次呼叫之間保持運行。如果每個提示都應在獨立進程中執行，請設定 persistSession: false。

詳情請參閱 AcpAgent 工作階段生命週期章節。

權限處理
權限處理 的直接連結

ACP Agent 在繼續執行前，可能會要求客戶端選擇權限選項。@mastra/acp 預設會選擇 ACP Agent 傳回的第一個選項。如需自訂權限行為，請傳入 onPermissionRequest。

如需完整範例，請參閱 createACPTool() 權限處理章節。

Workspace 整合
Workspace 整合 的直接連結

ACP 檔案操作會透過 Mastra 的 Workspace 抽象層進行。AcpAgent 可使用 workspace 選項，而在 Workspace 可用時，createACPTool() 會使用 Tool 執行上下文中的目前 Mastra Workspace。如果沒有 Workspace，@mastra/acp 會改用 Workspace，其後端為 LocalFilesystem，位置則為 cwd 或 process.cwd()。

如需自訂 Workspace 範例，請參閱 AcpAgent Workspace 整合章節。

On this page