Mastra 集成 ACP 编码智能体使用 createACPTool 将 Claude Code 等 ACP 进程封装为 Mastra 工具【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/acp是 Mastra 框架中专门用于对接 Agent Client ProtocolACP编码智能体的包。本文将基于该包在仓库中的开发文档 agent-sdks/acp/AGENTS.md 与完整源码讲解如何用createACPTool将一个 ACP 兼容的编码智能体进程封装为 Mastra 工具、ACPConnection如何管理进程生命周期以及如何把 ACP 编码智能体作为 Mastra 子代理SubAgent使用。读完本文你将掌握在 Mastra 应用中拉起并驱动 Claude Code、Grok 等 ACP 编码智能体的完整方案并理解其底层进程通信、会话复用与权限处理机制。背景Mastra 与 ACP 的桥接ACPAgent Client Protocol是让智能体客户端与编码智能体进程之间通过标准协议交互的规范。Mastra 本身提供 Agent、Workflow、工具Tool等抽象而mastra/acp的作用是把一个实现了 ACP 的编码智能体进程例如以--acp模式启动的 Claude Code当作一等公民接入 Mastra 生态——既可以作为可被任意 Agent 调用的工具也可以作为被其他 Agent 委托的子代理。该包对外暴露两个核心入口见 src/index.tscreateACPTool将一个 ACP 智能体进程包装成一个 Mastra 工具AcpAgent将同一个 ACP 连接实现为SubAgent接口可挂载到其他 Agent 的agents字段中供其委托调用。两者共享同一套配置类型CreateACPToolOptions定义于 src/types.ts因此在两种用法之间切换的成本很低。构建与测试命令仓库采用 pnpm Turbo 管理开发时可以从仓库根目录对mastra/acp单独构建与测试# 从仓库根目录构建 pnpm --filter ./agent-sdks/acp build:lib # 从仓库根目录运行测试 pnpm --filter ./agent-sdks/acp test对应的脚本定义在 agent-sdks/acp/package.jsonbuild:lib使用tsdown --silent --config tsdown.config.ts打包产物为dist/index.jsESM与dist/index.cjsCJStest使用vitest run --passWithNoTests。该包要求 Node.js22.13.0以agentclientprotocol/sdk^0.21.0为运行时依赖并以mastra/core1.34.0-0 2.0.0-0为 peer 依赖。用 createACPTool 包装 ACP 编码智能体createACPTool的职责非常纯粹把一个 ACP 兼容的编码智能体进程包装成一个标准 Mastra 工具让任意 Mastra Agent 都能像调用普通工具一样给它下发任务。开发文档 agent-sdks/acp/AGENTS.md 给出了最小示例import { createACPTool } from mastra/acp; const claudeTool createACPTool({ id: claude-code, description: Build anything with Claude Code, command: claude, args: [--acp], });工具输入输出契约从实现看src/tool.ts该工具使用 zod 定义了严格的三层 schema输入单个字段task: string即发送给 ACP 智能体的任务文本输出单个字段output: string即智能体最终返回的文本挂起/恢复suspendSchema描述了权限请求permissionRequest含title与可选项optionsresumeSchema允许工具执行者选择optionIdoutcome 为selected或直接cancelled。这为处理编码智能体在运行中提出的权限确认提供了标准化通道。execute内部先从运行时上下文取得 MastraWorkspace再通过会话拿到ACPConnection调用connection.prompt(task, context?.abortSignal)完成一次任务并返回{ output }。也就是说工具层不关心进程管理只做Mastra 输入/输出 ↔ACPConnection.prompt()的适配。CreateACPToolOptions 完整配置项开发文档要求createACPTool保持轻量真正的复杂度收敛在ACPConnection中。所有配置项定义于 src/types.ts以下是完整清单与说明配置项类型说明idstringMastra 工具的唯一标识必填。descriptionstring展示给模型、供其决定是否调用该工具的描述必填。commandstring要启动的 ACP 智能体可执行文件必填。argsstring[]传给该可执行文件的参数例如[--acp]。envRecordstring, string与当前进程环境合并后传给子进程的环境变量。cwdstringACP 进程与 ACP 会话的工作目录默认取process.cwd()。sessionPartialNewSessionRequest创建 ACP 会话的附加选项默认cwd为当前目录且mcpServers: []。initializePartialInitializeRequestACP 初始化附加选项默认携带 Mastra 客户端信息与协议版本。authMethodIdstring初始化后调用的 ACP 认证方法 ID如需要登录态时使用。persistSessionboolean工具执行后是否保持 ACP 进程存活默认true。onPermissionRequest(request) Promiseresponse智能体请求权限时的回调默认自动选择第一个权限选项。createClient(defaultClient) Client自定义 ACP 客户端可包装默认客户端以支持extMethod/extNotification扩展。workspaceWorkspaceACP 进程与会话使用的 Workspace文件系统沙箱。modelModelId会话创建后通过 ACPsession/set_model选择模型 ID。ACPConnection进程生命周期与协议通信的实现核心开发文档明确指出架构分层ACPConnection拥有进程生命周期、惰性 ACP 初始化、提示执行、取消与清理。实现位于 src/connection.ts以下逐一展开其关键机制。惰性初始化与握手ACPConnection在首次prompt/promptStream时才通过ensureConnected()触发初始化测试用例 lazy initializes the ACP process on first prompt 验证了spawn在构造时不会被调用。初始化流程initialize()依次完成用node:child_process的spawn启动command合并env与cwdstdio全管道将子进程的 stdin/stdout 包装为 Web Stream交给ndJsonStream建立基于 NDJSON 的协议流构建ClientSideConnection来自agentclientprotocol/sdkinitializeSession()依次执行协议initialize→可选authenticate→newSession→可选unstable_setSessionModel。初始化请求默认声明客户端为mastra/acp0.1.0并声明fs能力readTextFile/writeTextFile会话请求默认cwd为配置目录、mcpServers为空数组两者都可被initialize/session配置覆盖。prompt 与 promptStreamprompt(task, signal)是对promptStream的简单聚合遍历所有事件拼接text类型事件得到最终字符串。而promptStream是真正的核心通过一个内部实现的异步队列createAsyncQueue把 ACP 推送的sessionUpdate通知如agent_message_chunk的文本增量转换为可异步迭代的事件流事件类型为{ type: text; text }或{ type: session-update; update }发起connection.prompt({ sessionId, prompt: [{ type: text, text: task }] })当响应stopReason ! end_turn时抛出prompt stopped before completing错误支持AbortSignal信号触发时先调用cancel()通知 ACP 侧取消再向队列抛出异常。取消、断开与错误诊断cancel()向 ACP 发送cancel请求测试用例验证 abort 后会调用cancel({ sessionId })disconnect()清空连接与会话状态并kill()存活中的子进程若persistSession false每次promptStream结束finally 块都会断开连接保证进程不被复用错误处理非常细致子进程 stderr 会被持续收集任何初始化或执行错误都会通过withStderr把 stderr 内容附加到错误信息中方便排查如ENOENT启动失败、初始化期间进程退出等场景都有对应测试覆盖。权限请求的默认行为ACPClient.requestPermission的逻辑是如果配置了onPermissionRequest回调则交给用户否则自动选择第一个权限选项若无任何选项则返回cancelled。在完全自动化的 Agent 流程里这通常意味着编码智能体的文件写权限请求会被默认放行若需要更严格的策略请务必提供自己的回调。文件系统能力与路径越界防护ACP 智能体可通过协议请求读写文件默认由ACPClient.readTextFile/writeTextFile落到运行时Workspace的filesystem工具执行时会优先取context.mastra.getWorkspace()测试用例验证了这一点。Workspace的文件系统会执行路径作用域校验解析后的路径必须位于 workspace 根目录内否则拒绝访问——测试 src/tests/file-access.test.ts 明确覆盖了拒绝越界读写../、/etc/passwd等场景。同时readTextFile还支持line/limit参数做分段读取。模型选择与运行时切换ACPConnection提供两个与模型相关的 APIgetAvailableModels()返回会话响应中声明的availableModelsModelInfo[]setModel(modelId)调用unstable_setSessionModel切换模型且会在会话暴露可用模型列表时先做校验模型不在列表中则抛出带可用列表的错误。同样的校验也发生在initializeSession处理options.model时。测试中还验证了边界情况会话未暴露availableModels时跳过校验直接设置可用模型为空数组时设置会报错。这说明模型 ID 的合法性完全由 ACP 智能体自身声明Mastra 侧只做一致性检查。作为子代理AcpAgent除了工具形态mastra/acp还导出了AcpAgentsrc/agent.ts它实现SubAgent接口可被挂载到其他 Agent 的agents字段实现监督者委托编码智能体的编排模式import { AcpAgent } from mastra/acp; import { Agent } from mastra/core/agent; const codeAgent new AcpAgent({ id: code-agent, description: An ACP-compatible coding agent, command: claude, args: [--acp], model: claude-sonnet-4-6, }); const supervisor new Agent({ id: supervisor, instructions: Delegate coding work., model: yourLanguageModel, agents: { codeAgent }, });AcpAgent.generate会把传入的MessageListInput抽取为文本支持字符串、字符串数组与消息列表并在存在instructions时以instructions \n\n prompt拼接后交给 ACPstream则将 ACP 的流式输出映射为 Mastra 标准 chunktext-start/text-delta/text-end/step-finish/finish同时把 ACP 的tool_call/tool_call_update会话更新转换为 Mastra 的tool-call/tool-call-delta/tool-resultchunk使编码智能体内部调用工具的过程对上层监督 Agent 透明可见测试用例 emits tool call session updates as Mastra tool chunks 验证了这一点。AcpAgent不维护自身记忆hasOwnMemory()返回false也不支持恢复挂起的调用。由于AcpAgent需要实现SubAgent的模型接口其内部使用了一个占位MastraLanguageModelmodelId: acp-agentprovider 为mastra/acpdoGenerate/doStream返回空流——真正的文本生成全部由 ACP 进程完成这个占位模型仅用于满足框架的类型契约。测试布局与开发约定开发文档约定测试与源码同目录存放位于src/**/__tests__或src/**/*.test.ts。当前包内的测试包括src/tests/tool.test.tsmock 掉spawn与agentclientprotocol/sdk后验证工具 schema 生成、任务下发、默认会话复用、persistSession: false时每次新建并断开连接、运行时 Workspace 文件访问、惰性初始化、流式输出、abort 取消、权限默认选择与回调委托、模型设置校验、以及监督 Agent 委托AcpAgent的完整链路src/tests/file-access.test.ts验证 workspace 路径作用域允许根目录内访问、拒绝越界与分段读取、嵌套目录写入。这些测试本身就是理解createACPTool/ACPConnection/AcpAgent行为契约的最佳范例——例如默认跨多次执行复用同一个 ACP 会话只 spawn 一次进程、只创建一次 session、persistSession: false时每次执行 spawn 新进程并在结束后 kill这两个关键行为都直接由测试锁定。小结mastra/acp在架构上做了一个清晰的职责切分createACPTool只做 Mastra 工具输入输出与ACPConnection.prompt()之间的薄适配ACPConnection承担进程 spawn、ACP 协议握手、会话管理、流式输出、取消清理与错误诊断等全部脏活AcpAgent再把同一连接适配为可委托的子代理。无论你是想给现有 Agent 加一个会写代码的工具还是想搭一个监督者 Claude Code的分层智能体系统都可以直接基于 agent-sdks/acp/AGENTS.md 与 agent-sdks/acp/README.md 中的用法配合 src/connection.ts 与 src/tool.ts 的源码细节快速上手。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 集成 ACP 编码智能体：使用 createACPTool 将 Claude Code 等 ACP 进程封装为 Mastra 工具
Mastra 集成 ACP 编码智能体使用 createACPTool 将 Claude Code 等 ACP 进程封装为 Mastra 工具【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/acp是 Mastra 框架中专门用于对接 Agent Client ProtocolACP编码智能体的包。本文将基于该包在仓库中的开发文档 agent-sdks/acp/AGENTS.md 与完整源码讲解如何用createACPTool将一个 ACP 兼容的编码智能体进程封装为 Mastra 工具、ACPConnection如何管理进程生命周期以及如何把 ACP 编码智能体作为 Mastra 子代理SubAgent使用。读完本文你将掌握在 Mastra 应用中拉起并驱动 Claude Code、Grok 等 ACP 编码智能体的完整方案并理解其底层进程通信、会话复用与权限处理机制。背景Mastra 与 ACP 的桥接ACPAgent Client Protocol是让智能体客户端与编码智能体进程之间通过标准协议交互的规范。Mastra 本身提供 Agent、Workflow、工具Tool等抽象而mastra/acp的作用是把一个实现了 ACP 的编码智能体进程例如以--acp模式启动的 Claude Code当作一等公民接入 Mastra 生态——既可以作为可被任意 Agent 调用的工具也可以作为被其他 Agent 委托的子代理。该包对外暴露两个核心入口见 src/index.tscreateACPTool将一个 ACP 智能体进程包装成一个 Mastra 工具AcpAgent将同一个 ACP 连接实现为SubAgent接口可挂载到其他 Agent 的agents字段中供其委托调用。两者共享同一套配置类型CreateACPToolOptions定义于 src/types.ts因此在两种用法之间切换的成本很低。构建与测试命令仓库采用 pnpm Turbo 管理开发时可以从仓库根目录对mastra/acp单独构建与测试# 从仓库根目录构建 pnpm --filter ./agent-sdks/acp build:lib # 从仓库根目录运行测试 pnpm --filter ./agent-sdks/acp test对应的脚本定义在 agent-sdks/acp/package.jsonbuild:lib使用tsdown --silent --config tsdown.config.ts打包产物为dist/index.jsESM与dist/index.cjsCJStest使用vitest run --passWithNoTests。该包要求 Node.js22.13.0以agentclientprotocol/sdk^0.21.0为运行时依赖并以mastra/core1.34.0-0 2.0.0-0为 peer 依赖。用 createACPTool 包装 ACP 编码智能体createACPTool的职责非常纯粹把一个 ACP 兼容的编码智能体进程包装成一个标准 Mastra 工具让任意 Mastra Agent 都能像调用普通工具一样给它下发任务。开发文档 agent-sdks/acp/AGENTS.md 给出了最小示例import { createACPTool } from mastra/acp; const claudeTool createACPTool({ id: claude-code, description: Build anything with Claude Code, command: claude, args: [--acp], });工具输入输出契约从实现看src/tool.ts该工具使用 zod 定义了严格的三层 schema输入单个字段task: string即发送给 ACP 智能体的任务文本输出单个字段output: string即智能体最终返回的文本挂起/恢复suspendSchema描述了权限请求permissionRequest含title与可选项optionsresumeSchema允许工具执行者选择optionIdoutcome 为selected或直接cancelled。这为处理编码智能体在运行中提出的权限确认提供了标准化通道。execute内部先从运行时上下文取得 MastraWorkspace再通过会话拿到ACPConnection调用connection.prompt(task, context?.abortSignal)完成一次任务并返回{ output }。也就是说工具层不关心进程管理只做Mastra 输入/输出 ↔ACPConnection.prompt()的适配。CreateACPToolOptions 完整配置项开发文档要求createACPTool保持轻量真正的复杂度收敛在ACPConnection中。所有配置项定义于 src/types.ts以下是完整清单与说明配置项类型说明idstringMastra 工具的唯一标识必填。descriptionstring展示给模型、供其决定是否调用该工具的描述必填。commandstring要启动的 ACP 智能体可执行文件必填。argsstring[]传给该可执行文件的参数例如[--acp]。envRecordstring, string与当前进程环境合并后传给子进程的环境变量。cwdstringACP 进程与 ACP 会话的工作目录默认取process.cwd()。sessionPartialNewSessionRequest创建 ACP 会话的附加选项默认cwd为当前目录且mcpServers: []。initializePartialInitializeRequestACP 初始化附加选项默认携带 Mastra 客户端信息与协议版本。authMethodIdstring初始化后调用的 ACP 认证方法 ID如需要登录态时使用。persistSessionboolean工具执行后是否保持 ACP 进程存活默认true。onPermissionRequest(request) Promiseresponse智能体请求权限时的回调默认自动选择第一个权限选项。createClient(defaultClient) Client自定义 ACP 客户端可包装默认客户端以支持extMethod/extNotification扩展。workspaceWorkspaceACP 进程与会话使用的 Workspace文件系统沙箱。modelModelId会话创建后通过 ACPsession/set_model选择模型 ID。ACPConnection进程生命周期与协议通信的实现核心开发文档明确指出架构分层ACPConnection拥有进程生命周期、惰性 ACP 初始化、提示执行、取消与清理。实现位于 src/connection.ts以下逐一展开其关键机制。惰性初始化与握手ACPConnection在首次prompt/promptStream时才通过ensureConnected()触发初始化测试用例 lazy initializes the ACP process on first prompt 验证了spawn在构造时不会被调用。初始化流程initialize()依次完成用node:child_process的spawn启动command合并env与cwdstdio全管道将子进程的 stdin/stdout 包装为 Web Stream交给ndJsonStream建立基于 NDJSON 的协议流构建ClientSideConnection来自agentclientprotocol/sdkinitializeSession()依次执行协议initialize→可选authenticate→newSession→可选unstable_setSessionModel。初始化请求默认声明客户端为mastra/acp0.1.0并声明fs能力readTextFile/writeTextFile会话请求默认cwd为配置目录、mcpServers为空数组两者都可被initialize/session配置覆盖。prompt 与 promptStreamprompt(task, signal)是对promptStream的简单聚合遍历所有事件拼接text类型事件得到最终字符串。而promptStream是真正的核心通过一个内部实现的异步队列createAsyncQueue把 ACP 推送的sessionUpdate通知如agent_message_chunk的文本增量转换为可异步迭代的事件流事件类型为{ type: text; text }或{ type: session-update; update }发起connection.prompt({ sessionId, prompt: [{ type: text, text: task }] })当响应stopReason ! end_turn时抛出prompt stopped before completing错误支持AbortSignal信号触发时先调用cancel()通知 ACP 侧取消再向队列抛出异常。取消、断开与错误诊断cancel()向 ACP 发送cancel请求测试用例验证 abort 后会调用cancel({ sessionId })disconnect()清空连接与会话状态并kill()存活中的子进程若persistSession false每次promptStream结束finally 块都会断开连接保证进程不被复用错误处理非常细致子进程 stderr 会被持续收集任何初始化或执行错误都会通过withStderr把 stderr 内容附加到错误信息中方便排查如ENOENT启动失败、初始化期间进程退出等场景都有对应测试覆盖。权限请求的默认行为ACPClient.requestPermission的逻辑是如果配置了onPermissionRequest回调则交给用户否则自动选择第一个权限选项若无任何选项则返回cancelled。在完全自动化的 Agent 流程里这通常意味着编码智能体的文件写权限请求会被默认放行若需要更严格的策略请务必提供自己的回调。文件系统能力与路径越界防护ACP 智能体可通过协议请求读写文件默认由ACPClient.readTextFile/writeTextFile落到运行时Workspace的filesystem工具执行时会优先取context.mastra.getWorkspace()测试用例验证了这一点。Workspace的文件系统会执行路径作用域校验解析后的路径必须位于 workspace 根目录内否则拒绝访问——测试 src/tests/file-access.test.ts 明确覆盖了拒绝越界读写../、/etc/passwd等场景。同时readTextFile还支持line/limit参数做分段读取。模型选择与运行时切换ACPConnection提供两个与模型相关的 APIgetAvailableModels()返回会话响应中声明的availableModelsModelInfo[]setModel(modelId)调用unstable_setSessionModel切换模型且会在会话暴露可用模型列表时先做校验模型不在列表中则抛出带可用列表的错误。同样的校验也发生在initializeSession处理options.model时。测试中还验证了边界情况会话未暴露availableModels时跳过校验直接设置可用模型为空数组时设置会报错。这说明模型 ID 的合法性完全由 ACP 智能体自身声明Mastra 侧只做一致性检查。作为子代理AcpAgent除了工具形态mastra/acp还导出了AcpAgentsrc/agent.ts它实现SubAgent接口可被挂载到其他 Agent 的agents字段实现监督者委托编码智能体的编排模式import { AcpAgent } from mastra/acp; import { Agent } from mastra/core/agent; const codeAgent new AcpAgent({ id: code-agent, description: An ACP-compatible coding agent, command: claude, args: [--acp], model: claude-sonnet-4-6, }); const supervisor new Agent({ id: supervisor, instructions: Delegate coding work., model: yourLanguageModel, agents: { codeAgent }, });AcpAgent.generate会把传入的MessageListInput抽取为文本支持字符串、字符串数组与消息列表并在存在instructions时以instructions \n\n prompt拼接后交给 ACPstream则将 ACP 的流式输出映射为 Mastra 标准 chunktext-start/text-delta/text-end/step-finish/finish同时把 ACP 的tool_call/tool_call_update会话更新转换为 Mastra 的tool-call/tool-call-delta/tool-resultchunk使编码智能体内部调用工具的过程对上层监督 Agent 透明可见测试用例 emits tool call session updates as Mastra tool chunks 验证了这一点。AcpAgent不维护自身记忆hasOwnMemory()返回false也不支持恢复挂起的调用。由于AcpAgent需要实现SubAgent的模型接口其内部使用了一个占位MastraLanguageModelmodelId: acp-agentprovider 为mastra/acpdoGenerate/doStream返回空流——真正的文本生成全部由 ACP 进程完成这个占位模型仅用于满足框架的类型契约。测试布局与开发约定开发文档约定测试与源码同目录存放位于src/**/__tests__或src/**/*.test.ts。当前包内的测试包括src/tests/tool.test.tsmock 掉spawn与agentclientprotocol/sdk后验证工具 schema 生成、任务下发、默认会话复用、persistSession: false时每次新建并断开连接、运行时 Workspace 文件访问、惰性初始化、流式输出、abort 取消、权限默认选择与回调委托、模型设置校验、以及监督 Agent 委托AcpAgent的完整链路src/tests/file-access.test.ts验证 workspace 路径作用域允许根目录内访问、拒绝越界与分段读取、嵌套目录写入。这些测试本身就是理解createACPTool/ACPConnection/AcpAgent行为契约的最佳范例——例如默认跨多次执行复用同一个 ACP 会话只 spawn 一次进程、只创建一次 session、persistSession: false时每次执行 spawn 新进程并在结束后 kill这两个关键行为都直接由测试锁定。小结mastra/acp在架构上做了一个清晰的职责切分createACPTool只做 Mastra 工具输入输出与ACPConnection.prompt()之间的薄适配ACPConnection承担进程 spawn、ACP 协议握手、会话管理、流式输出、取消清理与错误诊断等全部脏活AcpAgent再把同一连接适配为可委托的子代理。无论你是想给现有 Agent 加一个会写代码的工具还是想搭一个监督者 Claude Code的分层智能体系统都可以直接基于 agent-sdks/acp/AGENTS.md 与 agent-sdks/acp/README.md 中的用法配合 src/connection.ts 与 src/tool.ts 的源码细节快速上手。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考