> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# createACPTool()

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

若要改將 ACP Agent 註冊為 Mastra subagent，請使用 [`AcpAgent` 類別](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)。

## 使用範例

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

```typescript
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 可執行檔的引數。 (Default: `[]`)

**env** (`Record<string, string>`): 產生 ACP 處理程序時，要與目前處理程序環境合併的環境變數。

**cwd** (`string`): ACP 處理程序與 ACP session 的工作目錄，也會作為預設的本機檔案系統基底路徑。 (Default: `process.cwd()`)

**session** (`Partial<NewSessionRequest>`): ACP session 建立選項。預設使用 cwd 或 process.cwd()，並使用空的 MCP 伺服器清單。

**initialize** (`Partial<InitializeRequest>`): ACP 初始化選項。預設使用 Mastra 使用者端資訊、目前 ACP 通訊協定版本，以及檔案系統讀寫功能。

**authMethodId** (`string`): 初始化後、建立 session 前要叫用的 ACP 驗證方法 ID。

**persistSession** (`boolean`): 為執行 Tool 建立的 ACP connection 是否在 prompt 後中斷連線。設為 false 可在每個 prompt 完成後停止處理程序。 (Default: `true`)

**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`](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)。

## 權限處理

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

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

```typescript
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 使用的使用者端：

```typescript
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 文件](https://mastra.zisheng.pro/zh-TW/docs/agents/acp)
- [AcpAgent 類別參考文件](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)
- [Tool 參考文件](https://mastra.zisheng.pro/zh-TW/reference/tools/create-tool)
- [Agent Client Protocol 簡介](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)