createACPTool()

createACPTool() 函式會建立 Mastra Tool，將 task 字串傳送給 Agent Client Protocol（ACP）相容的 Coding Agent，並以 output 傳回最終 ACP 回應。當上層 Agent 應決定何時將 ACP Agent 當作 Tool 呼叫時，可使用此函式。

若要改將 ACP Agent 註冊為 Mastra subagent，請使用 AcpAgent 類別。

使用範例

建立程式碼編輯 Tool，並在上層 Agent 上註冊：

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,
  },
})

參數

id:

string

Mastra Tool 的唯一識別碼。

description:

string

模型可呼叫此 Tool 時顯示的說明。

command:

string

要產生的 ACP Agent 可執行檔。

args?:

string[]

= []

傳給 ACP Agent 可執行檔的引數。

env?:

Record<string, string>

產生 ACP 處理程序時，要與目前處理程序環境合併的環境變數。

cwd?:

string

= process.cwd()

ACP 處理程序與 ACP session 的工作目錄，也會作為預設的本機檔案系統基底路徑。

session?:

Partial<NewSessionRequest>

ACP session 建立選項。預設使用 cwd 或 process.cwd()，並使用空的 MCP 伺服器清單。

initialize?:

Partial<InitializeRequest>

ACP 初始化選項。預設使用 Mastra 使用者端資訊、目前 ACP 通訊協定版本，以及檔案系統讀寫功能。

authMethodId?:

string

初始化後、建立 session 前要叫用的 ACP 驗證方法 ID。

persistSession?:

boolean

= true

為執行 Tool 建立的 ACP connection 是否在 prompt 後中斷連線。設為 false 可在每個 prompt 完成後停止處理程序。

onPermissionRequest?:

(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>

ACP Agent 要求權限時叫用的 callback。預設會選取第一個權限選項；沒有可用選項時則取消。

createClient?:

(defaultClient: Client) => Client

自訂用來回應 Agent 要求的 ACP 使用者端。此函式會接收預設使用者端，以便加以包裝或擴充，例如加入 extMethod 與 extNotification handler。

workspace?:

Workspace

共用 ACP connection 選項中的 Workspace 選項。執行 Tool 時，若執行 context 中有目前的 Mastra Workspace，createACPTool() 會將其傳入；否則 ACP connection 會退回使用本機檔案系統 Workspace。若需要提供明確的 Workspace 執行個體，請使用 AcpAgent。

model?:

ModelId

建立 ACP session 後，使用 ACP session/set_model 方法選取的模型 ID。

輸入 schema

task:

string

要傳送給 ACP Agent 的工作。

輸出 schema

output:

string

ACP Agent 傳回的最終文字輸出。

Suspend 與 resume schema

createACPTool() 會為權限要求 payload 定義 suspend 與 resume schema。權限決策會透過 onPermissionRequest 傳回；@mastra/acp 預設會選取 ACP Agent 傳回的第一個選項，沒有可用選項時則取消。

Suspend payload

permissionRequest:

{ title: string; options: { optionId: string; name: string }[] }

ACP Agent 傳回的權限要求標題與可選選項。

Resume payload

optionId?:

string

以 outcome: "selected" 繼續時，要選取的權限選項 ID。

outcome?:

"selected" | "cancelled"

用於繼續或取消 ACP 要求的權限決策。

Session 生命週期

每次執行 Tool 都會建立 ACP connection，並啟動所設定的 command。它會先初始化 ACP 使用者端並建立 ACP session，再透過 ACP session/prompt 傳送 task。

執行 Tool 時建立的 ACP connection，其 persistSession 預設為 true。若 ACP 處理程序應在該 prompt 完成後立即停止，請設定 persistSession: false。

若需要在多次呼叫之間重複使用 ACP subagent 執行個體，並明確控制 session 生命週期，請使用 AcpAgent。

權限處理

ACP Agent 可能會要求使用者端先選擇權限選項，才繼續執行。@mastra/acp 預設會選取 ACP Agent 傳回的第一個選項；沒有可用選項時則取消。

傳入 onPermissionRequest 可檢查要求並傳回自己的權限回應：

src/mastra/agents/code-agent.ts

import { createACPTool } from '@mastra/acp'

export const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent',
  command: 'acp-agent',
  args: ['--stdio'],
  async onPermissionRequest(request) {
    const allowOption = request.options.find(option => option.name === 'Allow')

    if (!allowOption) {
      return { outcome: { outcome: 'cancelled' } }
    }

    return {
      outcome: {
        outcome: 'selected',
        optionId: allowOption.optionId,
      },
    }
  },
})

可使用此 callback 強制執行本機 policy，或檢查權限標題，也可以將決策導向自己的核准流程。

擴充方法

某些 ACP Agent 會在標準 ACP 要求集合之外，呼叫使用者端上的自訂擴充方法。預設使用者端會以「Method not found」錯誤拒絕未知方法，這可能會中止 Agent 的 turn。

傳入 createClient 可擴充或取代預設使用者端。callback 會接收預設使用者端，並傳回 connection 使用的使用者端：

src/mastra/agents/code-agent.ts

import { createACPTool } from '@mastra/acp'

export const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent',
  command: 'acp-agent',
  args: ['--stdio'],
  createClient: defaultClient =>
    Object.assign(defaultClient, {
      async extMethod(method: string, params: Record<string, unknown>) {
        return {}
      },
      async extNotification(method: string, params: Record<string, unknown>) {},
    }),
})

若也需要變更標準 handler，請傳回完全自訂的 Client 實作。Client 型別會從 @mastra/acp 重新匯出。

相關內容

• Agent Client Protocol 文件
• AcpAgent 類別參考文件
• Tool 參考文件
• Agent Client Protocol 簡介
• Agent Client Protocol schema