Agent Client Protocol

Mastra 支持 Agent Client Protocol (ACP)，可从 Mastra agent 运行兼容 ACP 的 coding agents。使用 @mastra/acp 将 coding agent 进程包装为 Mastra tool 或 subagent。

ACP 适用于 Claude Code、Cline、OpenCode、Amp、Codex 等 coding agents，或任何通过标准输入输出实现 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 客户端还会处理权限请求和文件操作。agent 通过协议请求的文件读取和写入会经过 Mastra 的 Workspace。Workspace 仅覆盖这些请求：agent 进程使用配置的 cwd 运行，不会被沙箱化或隔离，并且仍可通过自己的 tools 和 shell 命令访问文件。

兼容的 agents

任何通过标准输入输出实现 ACP 的可执行文件都可以与 @mastra/acp 配合使用。你不需要为每个 agent 使用专门的 Mastra 包。安装 agent，然后通过 command 和 args 传入其启动命令。

Agent	command	args
Cline	cline	['--acp']
OpenCode	opencode	['acp']
Gemini CLI	gemini	['--acp']

每个 agent 都记录了自己的 ACP 模式，并且启动标志会在版本之间变化。查看 agent 的文档以获取当前命令，例如 Cline ACP 或 OpenCode ACP。

开始使用

在已经使用 @mastra/core 的项目中安装 @mastra/acp。该包要求 @mastra/core 版本为 1.34.0 或更高。

npm

npm install @mastra/acp

pnpm

pnpm add @mastra/acp

Yarn

yarn add @mastra/acp

Bun

bun add @mastra/acp

@mastra/acp 导出两个 API：

• createACPTool()：创建一个 Mastra tool，向 ACP agent 发送 task 字符串并返回 output 字符串。
• AcpAgent：将 ACP agent 包装为支持 generate() 和 stream() 的 Mastra subagent。

将 ACP 用作 subagent

当父 Mastra agent 应直接委派给兼容 ACP 的 coding agent 作为 subagent 时，使用 AcpAgent。

src/mastra/agents/code-supervisor.ts

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: 'opencode',
  args: ['acp'],
  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 参考。

将 ACP 用作 tool

当父 Mastra agent 应决定何时将 ACP agent 作为 tool 调用时，使用 createACPTool()。

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: 'opencode',
  args: ['acp'],
  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() 参考。

模型选择

ACP agents 可能会暴露可选择的模型。在 ACP 配置中传入 model，以便在创建会话后选择模型，或使用 AcpAgent.getAvailableModels() 和 AcpAgent.setModel() 在运行时管理模型。

示例参见 AcpAgent 模型管理方法。

会话生命周期

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

详情参见 AcpAgent 会话生命周期部分。

权限处理

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

完整示例参见 createACPTool() 权限处理部分。

Workspace 集成

ACP 文件请求会经过 Mastra 的 workspace 抽象。AcpAgent 可以使用 workspace 选项，而 createACPTool() 在有可用 workspace 时会使用 tool 执行上下文中的当前 Mastra workspace。没有 workspace 时，@mastra/acp 会回退到由 cwd 或 process.cwd() 处 LocalFilesystem 支持的 Workspace。

自定义 workspace 示例参见 AcpAgent workspace 集成部分。

相关内容

• AcpAgent 参考
• createACPTool() 参考
• Agent 参考
• Subagents
• Agent Client Protocol 介绍
• Agent Client Protocol schema