跳至主要內容

Agent Client Protocol

Mastra 支援 Agent Client Protocol (ACP)，可從 Mastra Agent 執行相容 ACP 的程式設計 Agent。使用 @mastra/acp，可將程式設計 Agent 處理程序包裝成 Mastra Tool 或子 Agent。

ACP 適用於 Claude Code、Amp、Codex 等程式設計 Agent，或任何透過標準輸入與輸出實作 ACP 的其他可執行檔。

何時使用 ACP
「何時使用 ACP」的直接連結

  • Mastra Agent 應將程式碼檢查、編輯或儲存庫任務委派給外部程式設計 Agent。
  • 相容 ACP 的 Agent 處理程序應在多次呼叫之間持續運作，以保留工作階段情境。
  • 父 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/core 的專案中安裝 @mastra/acp。此套件需要 1.34.0 以上版本的 @mastra/core。

npm install @mastra/acp

@mastra/acp 匯出兩個 API：

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

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

當父 Mastra Agent 應直接將工作委派給相容 ACP 的程式設計 Agent 時，請使用 AcpAgent 將其作為子 Agent。

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 應自行決定何時將 ACP Agent 作為 Tool 呼叫時，請使用 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 選項；若 Tool 執行情境中有目前的 Mastra Workspace，createACPTool() 則會使用該 Workspace。若沒有 Workspace，@mastra/acp 會改用以 cwd 或 process.cwd() 位置之 LocalFilesystem 為基礎的 Workspace。

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

On this page