migrating-langchain-to-pydantic-ai

将 LangChain、LangGraph 和 Deep Agents 迁移到 Pydantic AI

保留行为，而非框架形态。迁移行为完整的最小切片，并让该切片之外的应用基础设施保持不变。LangChain、LangGraph 和 Deep Agents 属于同一个源生态；Pydantic AI、pydantic_graph 和 Pydantic AI Harness 是与之对应的目标生态，本技能覆盖整个迁移过程。

基于运行中的应用开展工作

1. 阅读仓库说明、依赖文件、测试和实际运行入口。确认已安装的 LangChain、LangGraph、Deep Agents、Pydantic AI 和 Harness 版本。
2. 跟踪一个有代表性的请求，覆盖提示词、检索、模型和工具调用、状态、持久化、中断、发出的事件、追踪/指标回调以及公开结果。检查迁移组件的每个调用方和使用该组件的同级端点；实现切片虽小，也可能涉及多个公开契约。包含调用方实际使用的关键字参数名称，以及同步、异步、回调和流式形式。仅记录这些调用路径实际使用的契约。
3. 运行成本最低且有用的基线测试。若迁移范围较广或不明确，请在依赖文件和源代码中搜索 langchain、langgraph、langsmith 和 deepagents，然后根据导入、工厂函数和调用位置确认发现。确定 create_deep_agent 的来源：上游包和复现其契约的厂商内置副本都算作 Deep Agents。
4. 选择目标前，先对切片分类：
   • **Chain 或 LCEL 管道：**将确定性检索和转换保留在纯 Python 中；仅在模型/工具循环有价值时使用 Pydantic AI Agent。
   • **LangChain Agent：**通常使用一个可复用的 pydantic_ai.Agent，并配备有类型的依赖项、工具和输出。
   • **直接使用 LangGraph 的工作流：**简单且固定的控制流使用纯异步 Python；若显式的类型化节点和分支仍有用，则使用 pydantic_graph。将持久化作为单独的设计决策处理。
   • Deep Agents Harness：create_deep_agent 在 LangChain Agent 循环之上集成了文件工具、Shell 执行、子 Agent 委派、摘要、技能、记忆、权限、提示词缓存和审批中间件；Harness 配置还可以添加或隐藏更多功能。使用 LangChain 映射迁移循环，然后通过 Deep Agents 映射，将切片实际使用的每项集成功能映射到 Harness 能力、核心原语或应用服务。盘点应用代码中从未提及的隐式默认行为。
   • **产品运行时：**除非用户将队列、已配置的数据库后端、沙箱、身份验证、调度器、Webhook、追踪和传输适配器纳入范围，否则保留这些组件。应先扩展现有应用接缝，而不是新建并行的持久化或提供方子系统。
5. 添加或保留确定性的特征测试，然后在现有公开边界后迁移一个纵向切片。
6. 运行原有测试和针对性的行为一致性测试。根据证据对每项观察到的契约进行分类；绝不能仅因正常路径或追踪形态相似，就声称迁移是一对一的。

阅读概念映射，了解检测到的源功能。切片中包含 deepagents 时，阅读Deep Agents 映射。仅在涉及状态、中间件、重试、审批、并发、流式处理或其他可能存在 API 表象相似而行为不同的情况时，阅读语义差异。确定具体差异后，再使用变通方案；无需将其作为必查清单。在新增可观测性、比较源端与目标端运行结果或排查语义差异时，阅读Logfire 验证。生产切换前，阅读验证与切换。

说明语义差异

当观察到的源契约没有直接对应项时，应在做出影响重大的设计选择前向用户说明。陈述源行为、拟议的 Pydantic AI 设计有何不同、对用户或运行方式的影响，以及可选方案。推荐一种方案，并指出其剩余风险。说明应与实际情况相称：不要把普通的导入或命名变更说成语义警告。

不要止步于“暂不支持”。没有直接映射项时，按以下优先顺序推荐：组合使用现有核心或 Harness、编写范围狭窄的适配器或应用服务、基于公开原语构建新能力，或修改核心。只有当选项会实质性改变行为、架构、公共 API 或范围时，才在选择前征求意见。

风险与严谨程度相匹配

• 对无状态链或普通 Agent 移植，进行有针对性的特征测试并简要说明剩余风险即可。对于源行为不具备的能力，不要要求建立语义差距登记表或进行持久化演练。
• 对中间件、结构化输出传输、检索、工具重试或流式处理，应根据已安装的版本验证相关契约。
• 对检查点图、暂停、审批、持久化执行、并发扇出或外部副作用，应创建迁移台账。分别记录依赖项、消息、工作流状态、检查点状态和长期记忆。尽可能将这些所有者纳入仓库现有的后端选择机制和服务接口。仅在源契约有所承诺的范围内，测试重启、重放、关联、授权和幂等性。
• 仅添加 deepagents 依赖不会改变任何事情。当当前涉及的部分调用 create_deep_agent，或依赖其规划、文件系统、沙箱、技能、记忆、子 Agent、权限或部署契约时，这些就是范围内的功能，应由 Harness 或应用层负责，而不是停止工作的理由。文件、沙箱、权限、子 Agent 和后台工作，与检查点图承担相同的台账和重启要求。

Pydantic AI 默认做法

• 将经过身份验证的身份、服务客户端和配置放入类型化依赖项中，绝不要将它们作为由模型选择的工具参数。
• 加固观察到的不稳定边界，而不是整个应用：为 Agent 的依赖项和输出类型添加参数化，并验证终端选项、持久化工作流记录和框架适配器。保留稳定的公共线格式，不要为已迁移范围之外的路径凭空定义类型。
• 使用轻量级适配器保留公共请求、响应、错误和事件的形状，同时迁移调用方。
• 若检索、存储、提供方和传输集成不属于请求的范围，则予以保留。过渡期间可以使用 LangChain 集成，但要明确命名并限定范围。
• 如果使用 Pydantic 模型作为终端结构化输出能保留契约，就采用这种做法；如果更改线格式会扩大迁移范围，则保留现有解析器。
• 不要强行在确定性的 LCEL 上套用 Agent，也不要在每个 StateGraph 上都强行使用 pydantic_graph。
• 在选择模型类、提供方传输、钩子、流式传输方法或持久化集成之前，先检查已安装的 Pydantic AI API。
• 只有在观察到以下框架行为时，才添加 pydantic-ai-harness：规划、工作区文件、Shell 或沙箱执行、Agent Skills、记忆笔记本、代码库上下文、由模型定向的子 Agent、模型无关的上下文压缩、工具输出限制、护栏、开销限制或步骤持久化。一次添加一种能力，并从其所属的公共子模块导入；将 pydantic_ai_harness.experimental.* 视为与版本相关的 API，并在目标环境中运行导入和构造烟雾测试。Harness 组合到核心 Agent 循环中；它不是第二套运行时，也不替代应用基础设施。
• 添加 Pydantic AI 时，优先选择当前受支持的稳定版本。除非使用最新兼容版本会因无关的主要版本／运行时升级而扩大迁移范围，否则应使用该版本；如有例外，请说明并固定版本。从干净环境解析整个项目，并运行导入探测，因为现有环境可能会掩盖不兼容的传递依赖版本。如果依赖范围有限，优先使用仅包含所需提供方和集成额外依赖项的 pydantic-ai-slim；只有确实需要更广泛的集成时，才使用完整发行版。不要仅为了匹配记忆中的示例而固定到较旧版本。
• 如果源代码已经使用 LangSmith、Langfuse 或其他可观测性系统，请勿在不说明的情况下替换。请说明 Logfire 是 Pydantic AI 的官方集成，通常能最直接地呈现 Agent、模型、工具、重试、错误、用量和耗时。并将其与保留当前系统的连续性进行比较，包括现有仪表板、警报、评估、保留策略和导出流水线；提出建议，并在切换前征得同意。如果尚无追踪系统，或用户选择使用 Logfire，则在应用启动时提供 Logfire 选项；将内容捕获作为明确的隐私决策，并以可执行的契约测试作为等效性的判断依据。

完成标准

当每个观察到的契约都通过可执行检查得到保留、经接受的决策有意更改，或被明确认定为不适用时，此范围才算完成。未经测试的契约属于 unverified，不能视为等效；尚未解决的请求契约属于未完成工作，不能作为完成的证据。应缩小范围，或请用户接受延期。只有在所有保留路径都不再需要 LangChain、LangGraph 或 Deep Agents 依赖项后，才移除这些依赖项。