createACPTool()

createACPTool() 函數會建立 Mastra Tool，將 task 字串傳送給兼容 Agent Client Protocol (ACP) 的編程助手，並以 output 傳回最終 ACP 回應。當父 Agent 應自行決定何時以 Tool 形式呼叫 ACP Agent 時，可使用此函數。

如希望改為將 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 client 資訊、目前的 ACP protocol 版本，以及檔案系統讀寫功能。

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 client。函數會接收預設 client，讓你包裝或擴充它，例如加入 extMethod 和 extNotification handler。

workspace?:

Workspace

來自共用 ACP connection 選項的 Workspace 選項。執行 Tool 時，如執行環境提供目前的 Mastra workspace，createACPTool() 會將其傳入；否則 ACP connection 會改用本機檔案系統 workspace。如需提供明確的 workspace instance，請使用 AcpAgent。

model?:

ModelId

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

輸入 schema

task:

string

要傳送給 ACP Agent 的工作。

輸出 schema

output:

string

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

暫停及繼續 schema

createACPTool() 為權限要求 payload 定義暫停及繼續 schema。權限決定會透過 onPermissionRequest 傳回；@mastra/acp 預設會選擇 ACP Agent 傳回的第一個選項，如沒有可用選項則取消要求。

暫停 payload

permissionRequest:

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

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

繼續 payload

optionId?:

string

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

outcome?:

"selected" | "cancelled"

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

Session 生命週期

每次執行 Tool 都會建立 ACP connection，並啟動已設定的 command。它會先初始化 ACP client 和建立 ACP session，然後使用 ACP session/prompt 傳送 task。

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

如需可重用的 ACP subagent instance，並在多次呼叫之間明確控制 session 生命週期，請使用 AcpAgent。

權限處理

ACP Agent 在繼續操作前，可能會要求 client 選擇權限選項。@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 可強制執行本機政策或檢查權限要求的標題，亦可把決定轉交至你自己的核准流程。

擴充方法

部分 ACP Agent 會在標準 ACP 要求集合以外，呼叫 client 上的自訂擴充方法。預設 client 會以「找不到方法」錯誤拒絕未知方法，這可能會中止 Agent 的回合。

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

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 type 會從 @mastra/acp 重新匯出。

相關內容

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