ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

ACP 模式实战指南:Prime Agent 如何通过 Agent Client Protocol 被任意客户端驱动

ACP 模式实战指南:Prime Agent 如何通过 Agent Client Protocol 被任意客户端驱动 ACP 模式实战指南Prime Agent 如何通过 Agent Client Protocol 被任意客户端驱动【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent本指南围绕 Prime Agent 的 ACPAgent Client Protocol模式展开说明如何用一行命令把 Prime Agent 变成任何 ACP 客户端——如 Zed、VS Code 或评测 harness——都能直接驱动的标准 Agent客户端通过 JSON-RPC 2.0 新行分隔协议在 stdin/stdout 上发起提示prompt、流式观察工具调用、取消回合全程无需了解任何 Prime Agent 特有细节。读完本文你将掌握 ACP 模式的启动方式、传输约定、五种会话方法的使用要点、MCP 服务器接入规则、事件流式映射表、_meta扩展机制与停止原因stop reason语义并能对照仓库源码理解每一步背后的实现原理。什么时候该用 ACP 模式ACP 模式解决的是外部程序需要交互式地驱动一次会话的场景发起 prompt、实时观看工具调用流、随时取消当前回合。启动方式非常直接prime-agent --mode acp从 命令行参数解析 可以看出--mode支持text、json、rpc、acp、daemon五种取值ACP 模式在命令注册表中对应说明为 Select the output mode (default: text)见 command-registry.ts。选型对比出自 acp.mdACP 模式适合需要外部程序交互式驱动会话的场景——发 prompt、观察工具调用流、取消回合。JSON 事件流模式适合批量运行需要把所有事件倾倒出来并拿到退出码。RPC 模式依然可用且暴露 Prime Agent 自身更丰富的命令面。传输约定stdout 属于协议其他一切走 stderrACP 模式的传输层遵循三条硬性约定stdout 上每行一条 JSON-RPC 消息NDJSON请求从 stdin 读取stdin 在整个连接生命周期内保持打开Agent 在它关闭时退出诊断信息一律写入 stderr绝不向 stdout 写入协议之外的任何内容。这三条约定的背后有源码级的双重保障。在 acp-mode.ts 中ACP 模式启动时调用takeOverStdout()所有非交互模式都会把process.stdout.write重定向到 stderr防止任何零散日志污染机器可读流。随后协议帧通过 guard 暴露的裸写入通道writeRawStdout见rawStdoutSink实现 acp-mode.ts真正落到 stdout。连接关闭后的退出行为也有明确处理客户端断开stdin EOF 或传输关闭后模式会清理会话、释放 MCP 服务器配置并退出进程避免每次运行都留下孤儿 Agent 进程见 acp-mode.ts。五种会话方法单连接单会话的刻意设计方法说明initialize返回协议版本、能力capabilities和 Agent 信息。session/new创建会话。一个连接只有一个会话。session/prompt运行一个回合并以停止原因stop reason解析。session/cancel通知notification中止目标会话的当前回合。session/close释放会话让连接可以被新会话复用。单连接单会话是刻意为之的约束Prime Agent 的底层会话在进程启动时就固定了如果允许第二个并发会话它只会静默共享会话的对话历史、工作目录和模型。因此第二个session/new会被明确拒绝而不是假装隔离——文档明确建议需要第二个会话就再启动一个进程。这个拒绝而非伪装隔离的策略在源码中体现为对单会话槽位的严格保护session/new处理函数在第一次 await 之前就检查并占住槽位避免两个并发请求同时在飞行途中通过空槽检查后互相覆盖见 acp-mode.ts。同样地session/prompt在已有回合运行时拒绝并发回合工作目录在启动后不可更改——客户端提供的cwd若与 Agent 真实目录不一致会通过_meta报告回来而不是静默忽略。源码中这是通过sameCwd()进行规范性比较realpath dev/inoWindows 下还做盘符小写归一化实现的不一致时在session/new响应中携带_meta.cwd { requested, actual }见 acp-mode.ts 与 acp-meta.ts。initialize响应中还值得注意两点能力声明promptCapabilities: { image: true, embeddedContext: true }表示支持图像与内嵌文本资源而sessionCapabilities: { close: {} }让客户端知道可以用session/close释放单会话槽位而不是直接断开连接见 acp-mode.ts。既然initialize声明了图像与内嵌资源支持它们就必须真正送达模型——promptContent()会把文本块、图像块、内嵌文本资源、资源链接分别解析为文本与图像内容绝不静默丢弃见 acp-mode.ts。MCP 服务器stdio 与 HTTP 的接入规则与安全边界Prime Agent 接受session/new.mcpServers中标准的 stdio 与 HTTP 服务器声明这些服务器通过该 ACP 会话预导入的mcpPython 程序可用tools await mcp.list_tools(task-tools) result await mcp.call_tool(task-tools, lookup, {query: example})接入规则的细节如下HTTP 服务器只使用 ACP 客户端提供的 URL 与请求头。它们不会读取auth.json、不会启动或刷新 Prime Agent OAuth、不会修改持久化的 MCP 设置。stdio 服务器以 Agent 的真实会话 cwd、客户端提供的命令与参数、一个被清洗scrubbed的基础环境以及客户端提供的精确环境变量值运行。配置在ACP 会话关闭或客户端断开时被移除。因此一个同名持久化 MCP 服务器可以在 ACP 会话期间被遮蔽shadowed而不会把其存储的 OAuth 凭据发送到客户端提供的 HTTP 端点。守护进程daemon托管的配置绑定到安装它的 ACP 连接另一个附加的客户端无法替换或清除它。源码中的resolveAcpMcpServers()见 acp-mcp.ts对这些声明做了严格校验服务器名必须匹配^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$且不可重名stdio 服务器必须提供 command 且不允许出现 NUL 字符HTTP 服务器必须是合法 URL、协议限于 http/https 且不允许内嵌用户名密码header 会经过 Node 的validateHeaderName/validateHeaderValue校验重复 header 与环境变量名都会被拒绝。安全上要特别强调ACP stdio 是可信代码边界trusted-code boundary不是沙箱。请求的命令以 Prime Agent 用户身份运行可以访问该用户能访问的一切文件包括凭据存储。因此文档的建议是只接受来自可信 ACP 客户端的 stdio 服务器或者在适当的沙箱内运行 Prime Agent。流式更新会话活动如何映射为 session/update会话活动以session/update通知的形式到达客户端。事件映射定义于 acp-events.ts如下Prime Agent 活动ACP 更新助手文本agent_message_chunk推理内容agent_thought_chunk工具开始tool_callin_progress工具结束tool_call_updatecompleted/failedshell 输出tool_call加增量的tool_call_update几个实现细节值得注意Python REPL 是 Prime Agent 面向模型的主要工具因此一个单元格cell就是 kind 为execute的tool_call其rawInput携带单元格源码。在 acp-events.ts 中ipython工具被专门映射为标题 Python cell、rawInput: { code: cell }。推理与正文分流thinking_delta事件映射为agent_thought_chunktext_delta事件映射为agent_message_chunk客户端可以分别渲染或隐藏见 acp-events.ts。bash 运行在工具调用生命周期之外所以按 run id 生成一个合成的 tool call id前缀prime-agent-bash-让增量输出可寻址见 acp-events.ts。富内核输出ipython 工具把媒体与 diff 信息放在details下映射时以_meta.ipython携带附件的 mimeType、path、解码字节数以及 diffCount图像本身仍作为 ACP 图像内容块传输避免重复内联见 acp-events.ts。Prime Agent 扩展_meta反向域名信封ACP 协议没有字段来表达 Prime Agent 的能力子代理subagents、自治质量门autonomous quality gates、目标goals、心跳heartbeats、持续 harness 精炼continual-harness refinement、压缩compaction和富内核输出。这些内容通过反向域名_meta信封传输{ sessionUpdate: session_info_update, _meta: { ai.primeintellect.prime-agent: { subagents: [{ id: sub-1, sessionName: reviewer, status: running }] } } }命名空间常量定义于 acp-meta.tsai.primeintellect.prime-agent。设计原则是标准 ACP 客户端完全忽略_meta依然正常工作感知 Prime Agent 的客户端或关心子代理树与质量门尝试次数的 harness会读取它绝不向 ACP 对象根节点添加任何非标准字段——协议把对象根保留给未来的协议字段。从源码看这个信封里的字段相当丰富见 acp-meta.ts 的PrimeAgentSessionMetapromptTurnId因果回合编号在 ACP 接受 prompt 时分配、eventSequence连接级严格递增序号、phaseevent/responseBoundary/terminalQuiescence三种阶段、outcome仅result/error两种因果结论故意与传输层的end_turn等停止原因解耦、子代理、自治状态autonomouscontinuationsUsed / turnsUsed / tokensUsed / gateAttempt / gateFailure、目标、精炼、压缩、心跳变化、RLM 深度等。事件到_meta的映射同样全面compaction 结束、子代理状态更新、goal 更新、refine 完成/失败、ipython发送的 agent-to-agent 消息都会以命名空间元数据形式浮出见 acp-events.ts而不是被丢弃或扭曲成标准更新。停止原因质量门是回合内延续不是停止原因session/prompt最终以 ACP 停止原因之一解析end_turn—— 回合正常结束。cancelled——session/cancel中止了它。max_tokens—— 自治 token 预算耗尽。max_turn_requests—— 自治回合、延续或墙钟时间限制停止了运行。映射逻辑见 acp-stop-reason.tscancelled优先非自治回合返回end_turn自治状态下maxTokens是 ACP 原生表达的唯一限制所以映射为max_tokens回合/延续/墙钟限制都意味着 Agent 在完成前被停止统一映射为max_turn_requests——它们绝不能报成干净的end_turn。一个关键语义自治质量门运行在单个 prompt 回合内部。失败的质量门是一次延续continuation而不是停止原因因此回合只有在质量门循环安定settles之后才解析。质量门尝试在发生期间对_meta可见。这一点在 acp-mode.ts 的finalizePendingTerminal中有完整实现prompt 响应发出后会继续等待 headless 完成与 RLM 子代理静默quiescence直到子代理全部终止、自治延续耗尽才发布带terminalQuiescence阶段的终局_meta信封。深入源码更新生产者的因果性与顺序保证ACP 通知是异步的每个调用点各分配一个 id 并不够脱离上下文的调用可能被乱序观察到。为此 acp-mode.ts 实现了一个AcpUpdateProducer类作为单一生产者核心设计包括序列化发布并加盖交付序号所有通知串行进入一个 promise 尾链tail chaineventSequence严格递增保证客户端看到因果一致、顺序确定的更新流。admission 门控订阅在session/new响应发出前就已建立但通过 admission 门延迟放行避免会话绑定更新抢在session/new回复之前发布响应写出的那一刻才放开门见 acp-mode.ts 与流包装器 acp-mode.ts。回合因果归属promptTurnId在 ACP 接受 prompt 时第一次 await 之前就分配而不是在更新送达时按当前运行中的 prompt推断防止迟到的生产者事件变成下一个回合的产物。子代理更新会记住其初始来源回合即使之后有新的 prompt 也不会被重新标记见 acp-mode.ts。回合边界判定TurnBoundary用消息对象身份WeakSet加内容键role/timestamp/stopReason/errorMessage双轨记录回合前的转录本以对抗回合内自动压缩重建消息数组的情况见 acp-mode.tsturnFailure只扫描本回合新增的 assistant 消息来判定失败避免把更早回合的陈旧错误算到当前回合头上见 acp-mode.ts。测试佐证协议行为有端到端验证ACP 模式的协议行为在仓库测试中有充分覆盖可作为自行扩展客户端的参考acp-cold-cli.test.ts通过真实--mode acp子进程发起session/new与session/prompt请求验证冷启动路径上的响应与更新文件头部注释明确指出某些失败模式只在真实--mode acp进程出现时才暴露。acp-mcp.test.ts验证session/new中的 MCP 服务器声明及其替换行为。acp-rlm-subagents.test.ts验证 RLM 子代理在 ACP 会话中的流式报告与终局行为。小结让任意 ACP 客户端驱动 Prime Agent 的完整画面ACP 模式把 Prime Agent 的完整能力Python REPL 工具、bash 逃生舱、RLM 子代理、自治质量门、目标与心跳、压缩与精炼折叠进一个标准协议传输层独占 stdout、五种会话方法、严格校验的 MCP 接入、流式session/update事件映射、反向域名_meta扩展与四种停止原因。对标准客户端它是无感知兼容的 Agent对 Prime Agent 感知客户端或评测 harness它是携带完整因果信息promptTurnId、eventSequence、phase、outcome的观测源。启动一个可被外部驱动的会话只需要一行命令prime-agent --mode acp【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表