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

# Agent Client Protocol

Mastra 支持 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction)，可通过 Mastra Agent 运行兼容 ACP 的 coding agent。使用 `@mastra/acp` 可将 coding agent 进程封装为 Mastra Tool 或子 Agent。

ACP 适用于 Claude Code、Amp、Codex 等 coding agent，也适用于其他任何通过标准输入和输出实现 ACP 的可执行程序。

## 何时使用 ACP

- Mastra Agent 需要将代码检查、编辑或仓库任务委派给外部 coding agent。
- 兼容 ACP 的 Agent 进程应在多次调用之间保持运行，以保留会话上下文。
- 父 Agent 需要在任务运行期间获取 coding 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/reference/acp/create-acp-tool)：创建一个 Mastra Tool，将 `task` 字符串发送给 ACP Agent 并返回 `output` 字符串。
- [`AcpAgent`](https://mastra.zisheng.pro/reference/acp/acp-agent)：将 ACP Agent 封装为支持 `generate()` 和 `stream()` 的 Mastra 子 Agent。

## 将 ACP 作为子 Agent 使用

当父 Mastra Agent 需要直接将工作委派给兼容 ACP 的 coding 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 Reference](https://mastra.zisheng.pro/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() Reference](https://mastra.zisheng.pro/reference/acp/create-acp-tool)。

## 模型选择

ACP Agent 可能会公开可选模型。在 ACP 配置中传入 `model` 可在创建会话后选择模型，也可以使用 `AcpAgent.getAvailableModels()` 和 `AcpAgent.setModel()` 在运行时管理模型。

示例请参阅 [AcpAgent 模型管理方法](https://mastra.zisheng.pro/reference/acp/acp-agent)。

## 会话生命周期

`AcpAgent` 会在首次使用时启动配置的命令并创建 ACP 会话。`persistSession` 默认为 `true`，因此子进程会在多次调用之间保持运行。当每个提示都应在隔离的进程中运行时，请设置 `persistSession: false`。

详情请参阅 [AcpAgent 会话生命周期](https://mastra.zisheng.pro/reference/acp/acp-agent)部分。

## 权限处理

ACP Agent 可能会在继续执行前要求客户端选择权限选项。默认情况下，`@mastra/acp` 会选择 ACP Agent 返回的第一个选项。如需自定义权限行为，请传入 `onPermissionRequest`。

完整示例请参阅 [createACPTool() 权限处理](https://mastra.zisheng.pro/reference/acp/create-acp-tool)部分。

## Workspace 集成

ACP 文件操作通过 Mastra 的 Workspace 抽象完成。`AcpAgent` 可以使用 `workspace` 选项，而 `createACPTool()` 会在可用时使用 Tool 执行上下文中的当前 Mastra Workspace。如果没有 Workspace，`@mastra/acp` 会回退到一个 `Workspace`，它由 `LocalFilesystem` 支持，位置为 `cwd` 或 `process.cwd()`。

自定义 Workspace 示例请参阅 [AcpAgent Workspace 集成](https://mastra.zisheng.pro/reference/acp/acp-agent)部分。

## 相关内容

- [AcpAgent Reference](https://mastra.zisheng.pro/reference/acp/acp-agent)
- [createACPTool() Reference](https://mastra.zisheng.pro/reference/acp/create-acp-tool)
- [Agent Reference](https://mastra.zisheng.pro/reference/agents/agent)
- [子 Agent](https://mastra.zisheng.pro/docs/capabilities/subagents)
- [Agent Client Protocol 简介](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol Schema](https://agentclientprotocol.com/protocol/schema)