跳到主要内容

Agent Client Protocol

Mastra 支持 Agent Client Protocol (ACP)，可通过 Mastra Agent 运行兼容 ACP 的 coding agent。使用 @mastra/acp 可将 coding agent 进程封装为 Mastra Tool 或子 Agent。

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

何时使用 ACP
何时使用 ACP的直接链接

  • Mastra Agent 需要将代码检查、编辑或仓库任务委派给外部 coding agent。
  • 兼容 ACP 的 Agent 进程应在多次调用之间保持运行，以保留会话上下文。
  • 父 Agent 需要在任务运行期间获取 coding agent 的实时输出。
  • 兼容 ACP 的 Agent 在读取或写入文件，或执行其他操作前，需要提示用户授予权限。
  • 文件访问应通过 Mastra 的 Workspace 抽象完成，而不是仅由进程直接访问。

ACP 的工作原理
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 install @mastra/acp

@mastra/acp 导出两个 API：

  • createACPTool()：创建一个 Mastra Tool，将 task 字符串发送给 ACP Agent 并返回 output 字符串。
  • AcpAgent：将 ACP Agent 封装为支持 generate() 和 stream() 的 Mastra 子 Agent。

将 ACP 作为子 Agent 使用
将 ACP 作为子 Agent 使用的直接链接

当父 Mastra Agent 需要直接将工作委派给兼容 ACP 的 coding agent 时，请使用 AcpAgent 将其作为子 Agent。

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: '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。

将 ACP 作为 Tool 使用
将 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: '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。

模型选择
模型选择的直接链接

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

示例请参阅 AcpAgent 模型管理方法。

会话生命周期
会话生命周期的直接链接

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

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

权限处理
权限处理的直接链接

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

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

Workspace 集成
Workspace 集成的直接链接

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

自定义 Workspace 示例请参阅 AcpAgent Workspace 集成部分。

On this page