migrating-deep-agents-to-pydantic-ai-harness

将 Deep Agents 迁移到 Pydantic AI Harness

保留应用已观察到的契约，而不是照搬 create_deep_agent 的形式。组合 Pydantic AI 原语与 Harness 功能；基础设施应由原本负责它的应用管理。

明确源契约

1. 应用以下映射前，先确认 deepagents 的导入来源。只有当本地模块或项目自有的 create_deep_agent 实现遵循普通 LangChain 或 LangGraph 语义时，才将其归入常规 LangChain 迁移；复现 Deep Agents 契约的供应商实现仍在范围内。阅读仓库说明、清单、锁文件、测试、运行时入口和已解析的源代码。记录 Deep Agents、LangChain、LangGraph、Pydantic AI 和 Harness 的确切版本。 如果无法获取锁定的源代码，就在不更改目标锁文件的前提下复现其环境。如果无法做到，则将受影响的行为标记为未经验证，不得声称实现了功能对等。
2. 沿着提示词和模型配置、工具与集成、中间件与权限、后端与执行、技能与记忆、委派、状态、检查点与审批、重试与限制、事件、副作用以及公共边界，追踪一个有代表性的请求。检查该边界的每个调用方。
3. 运行成本最低的确定性基线。将证据与结果分开记录：source-inspected、probe-observed 或 regression-tested。
4. 仅加载与检测到的源功能相关的映射：
   • 如果涉及构造、模型与配置、提示词、工具和 MCP、中间件、状态、输出、缓存或追踪，请参阅 核心迁移。
   • 如果涉及编码 Agent 默认行为、规划、文件、权限、后端、沙箱、解释器、多媒体、技能、记忆、检索或上下文限制，请参阅 上下文与执行。
   • 如果涉及同步、动态或后台子 Agent、评分循环、审批、检查点、容错、持久化执行或流式传输，请参阅 编排与恢复。
   • 仅当迁移 Deep Agents Code、前端、ACP、A2A 或部署边界时，才参阅 宿主与协议。

构建 Pydantic AI 目标方案

• 从一个可复用的 Agent 开始。Pydantic AI 负责模型／提供方边界、规范化消息、Agent 循环、类型化依赖项和输出、工具与工具集、运行 API、用量限制以及通用钩子。
• 将经过身份验证的身份、服务客户端和配置放入 deps_type 和 RunContext；只通过类型化工具公开由模型选择的输入。根据所需的历史记录行为，在 instructions 和 system_prompt 之间作出选择，并使用 result.output，不要让框架消息泄漏到应用边界之外。
• 针对已观察到的可选行为，逐项添加 Harness 功能。某项功能会将指令、工具集、钩子和模型设置组合到 Agent 上；它不会取代应用基础设施或 Pydantic AI 的运行时语义。
• 根据调用方的实际生命周期选择 run_sync、run、run_stream、run_stream_events、iter、延迟结果和消息历史。迁移调用方期间，通过边界适配器保留原有线上的数据结构。
• 编写代码前，检查锁定版本中 pydantic_ai 和 pydantic_ai_harness 的公共导出、文档以及所选提供方、Agent、工具／工具集、功能、运行与延迟 API、持久化集成的源代码签名。从其所属的公共子模块导入功能，拒绝弃用警告，并在确切的目标环境中运行导入与构造冒烟测试。记录解释器以及解析出的 pydantic_ai 和 pydantic_ai_harness 模块路径，并附上测试结果。只添加必需的额外依赖；不要传递 LangChain 对象，也不要照搬凭记忆写出的示例。
• 将队列、租户管理、制品存储、远程沙箱生命周期、持久化领域状态、部署和外部副作用恢复保留在应用服务中。
• 选择 SubAgents 或 DynamicWorkflow 之前，先将编排归类为模型控制的委派、固定的应用工作流或后台工作进程；固定顺序和工作进程队列应保留在应用代码中。
• 如果公共 Pydantic AI 基元无法正确实现所需的通用运行时语义，应提出核心基元方案，而不是在 Harness 中重建运行时。

如果没有直接对应项，不要只说“暂不支持”。说明源契约及其影响，然后建议采用现有组合、精简适配器或应用服务、基于公共基元构建的新 Harness 功能，或 Pydantic AI 核心变更。推荐一个方案并指出其剩余风险；如果不同选项会实质性改变行为、架构、公共 API 或范围，请先询问再作选择。

迁移与验证

1. 在现有应用边界后移植一个纵向切片：类型化依赖项、一组工具、输出和一个有代表性的请求。
2. 迁移调用方期间，通过一个小型适配器保留源请求、结果、错误、事件和续接的数据结构。
3. 扩展到下一个功能之前，将原有测试套件与聚焦的特征描述、对等性及评估检查一并运行。在目标将使用的同一解释器和已安装检出版本中测试受支持的 Agent 边界；不得接受来自其他环境的结果。仅当本地编码 Agent 组合有用时，才阅读 已测试的组合。
4. 发布示例或宣称完成切换前，阅读 验证与切换；对于简单切片，只执行适用的检查。
5. 只有当每项范围内契约都经过回归测试、已协商同意作出变更，或明确标记为不适用时，才能切换。其他情况一律报告为未经验证。

根据已观察到的契约匹配验证方式。对于无状态切片，聚焦的特征描述和对等性测试已足够；持久化、审批、并发、流式处理和外部副作用则需要账本，以及适用的重启和幂等性检查。