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

# Agent Client Protocol

Mastra 支援 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction)，讓你從 Mastra Agent 執行兼容 ACP 的編程助手。你可以使用 `@mastra/acp`，將編程助手進程封裝為 Mastra Tool 或子 Agent。

ACP 適用於 Claude Code、Amp、Codex 等編程助手，以及任何透過標準輸入和輸出實作 ACP 的可執行檔案。

## 適合使用 ACP 的情況

- Mastra Agent 應將程式碼檢查、編輯或程式碼庫任務委派給外部編程助手。
- 兼容 ACP 的 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/acp` 安裝到已使用 `@mastra/core` 的項目中。此依賴套件需要 `@mastra/core` 的 `1.34.0` 或以上版本。

**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-HK/reference/acp/create-acp-tool)：建立 Mastra Tool，將 `task` 字串傳送給 ACP Agent，並傳回 `output` 字串。
- [`AcpAgent`](https://mastra.zisheng.pro/zh-HK/reference/acp/acp-agent)：將 ACP Agent 封裝為 Mastra 子 Agent，並支援 `generate()` 和 `stream()`。

## 將 ACP 用作子 Agent

當父 Mastra Agent 應以子 Agent 形式直接將任務委派給兼容 ACP 的編程助手時，請使用 `AcpAgent`。

```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-HK/reference/acp/acp-agent)。

## 將 ACP 用作 Tool

當父 Mastra Agent 應自行決定何時以 Tool 形式呼叫 ACP Agent 時，請使用 `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-HK/reference/acp/create-acp-tool)。

## 選擇模型

ACP Agent 可能會提供可選模型。在 ACP 配置中傳入 `model`，即可在建立工作階段後選擇模型；你亦可使用 `AcpAgent.getAvailableModels()` 和 `AcpAgent.setModel()`，在執行階段管理模型。

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

## 工作階段生命週期

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

詳情請參閱 [AcpAgent 工作階段生命週期](https://mastra.zisheng.pro/zh-HK/reference/acp/acp-agent)章節。

## 權限處理

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

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

## Workspace 整合

ACP 檔案操作會透過 Mastra 的 Workspace 抽象層進行。`AcpAgent` 可使用 `workspace` 選項，而在 Workspace 可用時，`createACPTool()` 會使用 Tool 執行上下文中的目前 Mastra Workspace。如果沒有 Workspace，`@mastra/acp` 會改用 `Workspace`，其後端為 `LocalFilesystem`，位置則為 `cwd` 或 `process.cwd()`。

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

## 相關內容

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