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

# Agent Client Protocol

Mastra 支援 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction)，可從 Mastra Agent 執行相容 ACP 的程式設計 Agent。使用 `@mastra/acp`，可將程式設計 Agent 處理程序包裝成 Mastra Tool 或子 Agent。

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

## 何時使用 ACP

- Mastra Agent 應將程式碼檢查、編輯或儲存庫任務委派給外部程式設計 Agent。
- 相容 ACP 的 Agent 處理程序應在多次呼叫之間持續運作，以保留工作階段情境。
- 父 Agent 需要在程式設計 Agent 執行任務時取得即時輸出。
- 相容 ACP 的 Agent 在讀取或寫入檔案前需要權限提示，或需要以其他方式執行動作。
- 檔案存取應透過 Mastra 的 Workspace 抽象層，而非僅由處理程序直接存取檔案。

## 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**:

```bash
npm install @mastra/acp
```

**pnpm**:

```bash
pnpm add @mastra/acp
```

**Yarn**:

```bash
yarn add @mastra/acp
```

**Bun**:

```bash
bun add @mastra/acp
```

`@mastra/acp` 匯出兩個 API：

- [`createACPTool()`](https://mastra.zisheng.pro/zh-TW/reference/acp/create-acp-tool)：建立 Mastra Tool，將 `task` 字串傳送給 ACP Agent，並傳回 `output` 字串。
- [`AcpAgent`](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)：將 ACP Agent 包裝成支援 `generate()` 與 `stream()` 的 Mastra 子 Agent。

## 將 ACP 用作子 Agent

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

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

## 將 ACP 用作 Tool

當父 Mastra Agent 應自行決定何時將 ACP Agent 作為 Tool 呼叫時，請使用 `createACPTool()`。

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

如需所有選項與設定，請參閱 [createACPTool() 參考文件](https://mastra.zisheng.pro/zh-TW/reference/acp/create-acp-tool)。

## 選擇模型

ACP Agent 可能會公開可選模型。在 ACP 設定中傳入 `model`，可在建立工作階段後選擇模型；也可使用 `AcpAgent.getAvailableModels()` 與 `AcpAgent.setModel()`，在執行階段管理模型。

如需範例，請參閱 [AcpAgent 模型管理方法](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)。

## 工作階段生命週期

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

如需詳細資訊，請參閱 [AcpAgent 工作階段生命週期](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)章節。

## 權限處理

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

如需完整範例，請參閱 [createACPTool() 權限處理](https://mastra.zisheng.pro/zh-TW/reference/acp/create-acp-tool)章節。

## Workspace 整合

ACP 檔案操作會經過 Mastra 的 Workspace 抽象層。`AcpAgent` 可使用 `workspace` 選項；若 Tool 執行情境中有目前的 Mastra Workspace，`createACPTool()` 則會使用該 Workspace。若沒有 Workspace，`@mastra/acp` 會改用以 `cwd` 或 `process.cwd()` 位置之 `LocalFilesystem` 為基礎的 `Workspace`。

如需自訂 Workspace 範例，請參閱 [AcpAgent Workspace 整合](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)章節。

## 相關內容

- [AcpAgent 參考文件](https://mastra.zisheng.pro/zh-TW/reference/acp/acp-agent)
- [createACPTool() 參考文件](https://mastra.zisheng.pro/zh-TW/reference/acp/create-acp-tool)
- [Agent 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/agent)
- [子 Agent](https://mastra.zisheng.pro/zh-TW/docs/capabilities/subagents)
- [Agent Client Protocol 簡介](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol 結構描述](https://agentclientprotocol.com/protocol/schema)