createACPTool()
createACPTool() 函数会创建一个 Mastra Tool，将 task 字符串发送给兼容 Agent Client Protocol（ACP）的编码 Agent，并将最终 ACP 响应作为 output 返回。当父级 Agent 应自行决定何时将 ACP Agent 作为 Tool 调用时，可以使用此函数。
如果希望改为将 ACP Agent 注册为 Mastra 子 Agent，请使用 AcpAgent 类。
使用示例使用示例的直接链接
创建代码编辑 Tool，并将其注册到父级 Agent：
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,
},
})
参数参数的直接链接
id:
description:
command:
args?:
env?:
cwd?:
session?:
cwd 或 process.cwd()，MCP server 列表默认为空。initialize?:
authMethodId?:
persistSession?:
false 可在每次提示词处理完成后停止进程。onPermissionRequest?:
createClient?:
extMethod 和 extNotification handler。workspace?:
createACPTool() 会将其传入；否则 ACP connection 会回退到本地文件系统 Workspace。如果需要提供显式 Workspace 实例，请使用 AcpAgent。model?:
session/set_model 方法选择的模型 ID。输入 schema输入 schema的直接链接
task:
输出 schema输出 schema的直接链接
output:
暂停和恢复 schema暂停和恢复 schema的直接链接
createACPTool() 为权限请求 payload 定义了暂停和恢复 schema。权限决策通过 onPermissionRequest 返回；默认情况下，@mastra/acp 会选择 ACP Agent 返回的第一个选项，如果没有可用选项则取消。
暂停 payload暂停 payload的直接链接
permissionRequest:
恢复 payload恢复 payload的直接链接
optionId?:
outcome: "selected" 恢复时要选择的权限选项 ID。outcome?:
Session 生命周期Session 生命周期的直接链接
每次执行 Tool 都会创建 ACP connection 并启动已配置的 command。它会初始化 ACP Client 并创建 ACP Session，然后使用 ACP session/prompt 发送 task。
默认情况下，执行 Tool 期间创建的 ACP connection 将 persistSession 设为 true。如果 ACP 进程应在该提示词处理完成后立即停止，请设置 persistSession: false。
如果需要一个可跨调用复用并可显式控制 Session 生命周期的 ACP 子 Agent 实例，请使用 AcpAgent。
权限处理权限处理的直接链接
ACP Agent 可能会要求 Client 选择一个权限选项，然后才能继续。默认情况下，@mastra/acp 会选择 ACP Agent 返回的第一个选项；如果没有可用选项，则取消。
传入 onPermissionRequest 可检查请求并返回自己的权限响应：
import { createACPTool } from '@mastra/acp'
export const codeAgentTool = createACPTool({
id: 'code-agent',
description: 'Use an ACP-compatible coding agent',
command: 'acp-agent',
args: ['--stdio'],
async onPermissionRequest(request) {
const allowOption = request.options.find(option => option.name === 'Allow')
if (!allowOption) {
return { outcome: { outcome: 'cancelled' } }
}
return {
outcome: {
outcome: 'selected',
optionId: allowOption.optionId,
},
}
},
})
可使用此回调强制执行本地策略或检查权限标题。它也可以将决策转交给你自己的审批流程。
扩展方法扩展方法的直接链接
某些 ACP Agent 会在标准 ACP 请求集之外，调用 Client 上的自定义扩展方法。默认 Client 会拒绝未知方法并返回 “Method not found” 错误，这可能会中止 Agent 的当前轮次。
传入 createClient 可扩展或替换默认 Client。此回调接收默认 Client，并返回用于 connection 的 Client：
import { createACPTool } from '@mastra/acp'
export const codeAgentTool = createACPTool({
id: 'code-agent',
description: 'Use an ACP-compatible coding agent',
command: 'acp-agent',
args: ['--stdio'],
createClient: defaultClient =>
Object.assign(defaultClient, {
async extMethod(method: string, params: Record<string, unknown>) {
return {}
},
async extNotification(method: string, params: Record<string, unknown>) {},
}),
})
如果还需要更改标准 handler，请返回完全自定义的 Client 实现。Client 类型从 @mastra/acp 重新导出。