deepagents-acp 版本演进深度解析从 0.0.6 到 0.0.11 的 ACP 集成能力进阶【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本文以libs/acp/目录下的 CHANGELOG.md 为主线结合 README.md、server.py 及测试源码逐条拆解deepagents-acp从 0.0.6 到 0.0.11 的每一次功能新增与修复。读者将理解可见推理流、持久化会话加载、中断状态读取时序修复等关键能力的底层实现并掌握如何通过升级该包获得最新的 ACPAgent Client Protocol集成体验。背景deepagents-acp 是什么deepagents-acp是 Deep Agents 项目的 Agent Client Protocol 连接器核心使命是把 Python 编写的 Deep Agent 接入支持 ACP 的编辑器如 Zed。其核心桥接类AgentServerACP位于 server.py实现了 ACP 规范定义的initialize、new_session、load_session、prompt、cancel、set_config_option等协议方法将 LangGraph 编译图与 ACP 客户端连接起来。当前 pyproject.toml 中版本号为0.0.11requires-python 3.11核心依赖为deepagents与agent-client-protocol0.10.1。以下逐一解读 changelog 中每个版本的核心变更。0.0.6Demo Agent 模型扩充与 v0.9 Schema 适配该版本包含两项变更为 demo agent 加入 Opus 4.7 与 Baseten这是对示例编码 Agent 的模型扩充。从源码可以印证Baseten 已成为官方示例依赖——pyproject.toml 的examples依赖组中声明了langchain-baseten0.2.4demo_agent.py 中models列表按供应商分组定义了baseten:*、anthropic:*、openai:*三组可切换模型当前仓库示例已演进为 Kimi-K2.7-Code、GLM-5.2、Claude Opus 5 等说明该模块持续在 demo 中验证多供应商模型接入。在 acp v0.9 schema 变更后恢复测试通过ACP 协议的agent-client-protocol库在 v0.9 中重构了部分 schema 结构适配工作贯穿了后续多个版本见 0.0.8 与 0.0.11 的兼容性处理这也是本包需要持续跟进上游协议版本的原因。0.0.7依赖升级该版本仅记录了Bumping dependencies依赖升级。从演进脉络看它通常与上游agent-client-protocol、deepagents的发布节奏绑定为后续的协议能力如会话加载、推理流铺路。此类维护性版本虽然没有功能变更但在版本号语义上标记了依赖基线的一次整体前移。0.0.8协议版本下限收紧至 agent-client-protocol0.9.0该版本将agent-client-protocol的下限提升到0.9.0。当前仓库 pyproject.toml 已进一步演进为agent-client-protocol0.10.1说明协议依赖在持续跟随上游升级。值得注意的是虽然版本下限收紧但代码层面保留了跨版本兼容能力。server.py 中有一段明确的兼容处理agent-client-protocolv0.9.0 移除了SessionConfigOption包装类配置选项变为裸的SessionConfigOptionSelect实例代码通过getattr(_acp_schema, SessionConfigOption, None)动态解析使模块在 v0.8.x 与 v0.9 下都能干净导入。测试文件 test_model_switching.py 中的_select辅助函数同样处理了root属性差异——从 v0.8 的包装形态解包到 v0.9 的直接实例并断言解包结果必须是SessionConfigOptionSelect防止未来包装形态悄悄回归。0.0.9延迟中断状态读取修复这是 0.0.9 的唯一修复项defer interrupt state reads until stream closes将中断状态读取推迟到流关闭之后。要理解它需要看 server.py 中prompt方法的流式处理循环在流式处理过程中当 agent 遇到 LangGraphinterrupt()时updates流中会出现__interrupt__键。代码将中断对象暂存到pending_interrupts变量中并continue跳过而不是立即读取状态。源码中的注释解释了原因server.pyThe checkpoint backing this update may not be visible until the stream iterator has closed. Defer reading state until after leaving the async iterator so persistent checkpointers do not return a stale, pre-interrupt snapshot.即异步迭代器关闭前持久化 checkpoint 可能尚未完成写入。如果流还在进行时就调用agent.aget_state()读取状态持久化 checkpointer 可能返回中断前的过期快照导致中断处理拿到错误数据。修复方案是把状态读取放到循环退出之后current_state await agent.aget_state(config)server.py。测试侧提供了对应的验证工具test_agent.py中的DelayedMemorySavertest_agent.py通过await asyncio.sleep(0.05)模拟持久化 checkpoint 的异步写入延迟专门用于暴露这类时序问题。这也提示用户agent-client-protocol集成对 checkpoint 写入时机的敏感性是使用异步持久化存储如数据库型 checkpointer时必须注意的细节。0.0.10持久化 ACP 会话加载session/load0.0.10 是功能里程碑AgentServerACP现在可以宣告并实现 ACP 的session/load能力将跨进程重启的会话恢复带到了协议层。README 的 Persist and load sessions 一节给出了启用方式server AgentServerACP(agent, load_sessionsTrue)前置条件持久化 checkpointerREADME 明确说明checkpointer 必须在 agent 进程重启后仍然可用。内存型MemorySaver适合测试但不能提供重启持久化。也就是说生产环境要配合数据库等持久化 checkpointer 使用。底层实现链路session/load的实现横跨多个方法server.py能力宣告initialize返回的AgentCapabilities(load_sessionself._load_sessions)server.py告知客户端本服务支持会话加载未启用时调用load_session会抛出RequestError.method_not_found。会话持久化new_session和set_config_option在_load_sessions开启时调用_persist_sessionserver.py通过agent.aupdate_state(..., as_node__start__)把 ACP 会话元数据写入 checkpoint 线程。身份与工作目录校验load_session恢复后先检查线程元数据中_ACP_SESSION_METADATA_KEY标记是否为真防止加载本服务未创建的会话否则返回resource_not_found再校验持久化的cwd与客户端传入的工作目录一致不一致返回invalid_paramsserver.py。历史重放_replay_sessionserver.py通过aget_state_history遍历所有快照去重合并消息按 message id 覆盖正确处理 compact 后删除的消息然后按顺序重放用户消息 →UserMessageChunk、助手消息与可见推理 →AgentMessageChunk/AgentThoughtChunk、工具调用 →tool_call开始与完成。_content_updates的注释强调实时流与会话重放都经由该函数投影因此块顺序与块类型支持不会漂移server.py——这是保证恢复的对话与真实发生时视觉一致的关键设计。测试覆盖test_agent.py 提供了完整的行为验证矩阵test_acp_agent_load_session_replays_persisted_historyL401验证重启后用户消息与助手回复被正确重放test_acp_agent_load_session_replays_tool_callsL468验证工具调用的开始与完成状态被重放test_acp_agent_load_session_replays_compacted_messagesL514验证会话被 compact 后旧消息仍能按RemoveMessage语义正确呈现test_acp_agent_load_session_restores_config_optionsL557验证重启后 mode 与 model 选择被还原且 agent 工厂收到正确的AgentSessionContext(cwd..., mode..., model...)test_acp_agent_load_session_rejects_sessions_it_did_not_createL619与test_acp_agent_load_session_rejects_different_cwdL634验证身份校验与工作目录校验。0.0.11将可见推理流作为 Thought Chunk 输出0.0.11 是 0.0.10 之后的最新功能版本核心能力是将模型产出的可见推理visible reasoning以agent_thought_chunk形式流式输出到 ACP 客户端。在此之前推理内容只能隐藏或被丢弃编辑器用户无法看到 Agent 的思考过程。实现要点核心逻辑在_visible_reasoningserver.py与_content_updatesserver.py只有当内容块类型为reasoning且reasoning字段是非空字符串时才判定为可见推理并输出AgentThoughtChunk红acted脱敏或加密的推理以non_standard块到达不含reasoning字符串因此永远不会被误输出——这是对模型隐私保护的刻意取舍空白保留推理是按增量delta逐条流的一个只含空格或换行的增量承载着单词边界与段落换行因此代码原样保留空白return reasoning or None而非 strip避免推理文本被错误拼接。测试佐证test_acp_agent_prompt_streams_visible_reasoning_in_block_ordertest_agent.py构造text → reasoning → text → 空 reasoning → 非字符串 reasoning → redacted_thinking的混合块序列断言客户端收到的更新序列严格为agent_message_chunk → agent_thought_chunk → agent_message_chunk且内容为Before、Considering options、After同时确认推理块类型为AgentThoughtChunktest_acp_agent_prompt_keeps_whitespace_between_reasoning_deltasL223-L243逐增量流[Considering, , options., \n\n, Now deciding.]断言拼接结果为Considering options.\n\nNow deciding.直接验证空白保留逻辑test_acp_agent_load_session_replays_visible_reasoning_in_orderL427-L465验证 0.0.11 的新能力与 0.0.10 的会话重放无缝协作——持久化会话中的推理块在重放时同样以AgentThoughtChunk呈现且携带原始message_id。横跨版本的能力会话内动态模型切换虽然模型切换未在 changelog 中单独列为条目但它贯穿了本模块的持续演进且与 0.0.8 的 schema 适配、0.0.10 的会话持久化深度耦合。README 的 Model Switching 一节与 test_model_switching.py 共同说明了这套能力声明模型清单通过AgentServerACP(agentbuild_agent, models[...])传入{value, name, description}列表服务会在new_session响应中暴露config_optionscategorymodel的下拉选择器客户端即可在会话内切换模型工厂函数模式agent传工厂函数接收AgentSessionContext内含cwd、mode、model时模型切换会触发_reset_agentserver.py用新的context.model重建 agent从而在不丢失会话历史的前提下换模型校验与持久化set_config_option会拒绝不在清单中的模型Invalid model错误并在load_sessionsTrue时把当前选择写入 checkpoint 元数据重启后通过_restore_session_optionsserver.py还原测试矩阵test_new_session_returns_config_options、test_set_config_option_switches_model、test_set_config_option_invalid_model_raises_error、test_config_options_with_modes_and_models、test_default_model_when_none_configured等用例覆盖了声明、切换、校验与缺省行为。升级建议与注意事项综合以上演进脉络用户在使用或升级deepagents-acp时应注意协议依赖基线0.0.8 起要求agent-client-protocol0.9.0当前仓库使用0.10.1。由于上游 schema 存在结构性变化如SessionConfigOption包装类的移除建议跟随本包的版本约束不要混用旧版协议库会话持久化依赖存储后端启用load_sessionsTrue前务必确认 agent 的 checkpointer 在进程重启后仍然可访问同时注意 0.0.9 揭示的时序问题——在流关闭前读取中断状态在持久化后端下可能拿到过期快照推理可见性与隐私0.0.11 起可见推理会以 thought chunk 呈现给编辑器用户但脱敏/加密推理non_standard块不会被输出因此模型的 reasoning 策略直接决定用户能看到多少思考过程本地开发与验证可参照 test_agent.py 与 test_model_switching.py 的测试模式用DelayedMemorySaver或 fake client 模拟客户端快速验证流式输出、中断处理与会话重放行为。结语从 0.0.6 的 demo 扩充与 schema 适配到 0.0.9 的中断时序修复、0.0.10 的持久化会话加载再到 0.0.11 的可见推理流deepagents-acp的每一次发布都沿着协议能力对齐 可靠性修复 用户体验增强三条主线推进。理解这份 changelog等于同时理解了 ACP 协议在真实 Agent 服务端落地的关键设计取舍——包括跨版本兼容、checkpoint 时序、会话重放一致性与推理隐私边界这些经验对任何基于 LangGraph 构建 ACP 服务的开发者都有直接参考价值。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考