migrating-claude-agent-sdk-to-pydantic-ai

将 Claude Agent SDK 迁移到 Pydantic AI

保留可观察到的行为，而非 Claude Code 进程或 API 形态。迁移最小的完整调用路径，并保留现有应用基础设施。

先追踪源端，再选择目标

1. 阅读仓库说明、依赖项、测试和运行时入口。记录已安装的 Claude Agent SDK、捆绑的 Claude Code CLI、Pydantic AI 和 Harness 版本。
2. 从 query() 或 ClaudeSDKClient 开始，追踪一个真实请求经过提示词、工具、事件、结果、状态、持久化、审批及调用方使用的副作用。建立有针对性的基线或特征测试。
3. 如存在以下源端契约，请分别区分：
   • 全新的 query() 调用、实时 ClaudeSDKClient 续接、从磁盘／外部存储恢复、对话记录分叉，以及文件回退；
   • 工具可用性、自动审批、策略回调，以及操作系统／容器隔离；
   • 已完成的消息、原始令牌增量、生命周期事件，以及终结结果；
   • 对话历史、工作流检查点、模型管理的计划、长期记忆，以及工作区状态；
   • 模型指派的子 Agent，与应用管理的循环、队列、重试及调度器。
4. 记录每项观察到的契约、其所属方、语义差异，以及可执行的证明。未观察到的 Claude Code 功能不属于迁移范围。

阅读研究与概念映射，了解检测到的源端功能。实施前阅读验证与切换。

选择最小的目标

• 核心： 使用 pydantic_ai.Agent 处理模型调用、Agent 循环、类型化依赖、工具、输出、规范化消息、通用钩子、流式处理、MCP、审批、使用量限制、插桩和持久运行时集成。
• Harness： 仅在观察到可复用的策略时添加 pydantic-ai-harness，例如编码用的文件系统／Shell 工具、仓库上下文、规划、记忆、模型指派的子 Agent、与模型无关的上下文管理，或 Agent Skills。Harness 功能通过核心 Agent 循环组合使用；Harness 不是第二套运行时。
• 应用： 保留身份验证、服务客户端、数据库、队列、调度器、部署、产品状态、会话查找、租户策略和现有传输层，除非所请求的迁移切片包含这些内容。
• 缺口： 明确指出没有受支持的公共接口能够保留的行为，说明其影响，并测试一个范围有限的适配器。不要仅为掩盖差异而创建仿冒的 ClaudeSDKClient，或模拟 Claude 对话记录文件。

通常的迁移方式是使用一个可复用的 Agent，通过类型化依赖提供应用服务，使用常规的 Pydantic AI 工具，在调用方需要结构化数据时使用类型化输出，并在后续轮次需要上下文时由应用存储 result.all_messages()。通过一个小型适配器保留现有的公共请求／响应／事件边界，同时逐步迁移调用方。

应用高风险关卡

• Claude Agent SDK 中的 allowed_tools 表示自动批准，而非独占可用性或隔离。请分别映射可用性、批准、策略和沙箱机制。
• Pydantic AI 的 message_history 会明确重放规范化消息。conversation_id 用于关联运行；它不是 Claude 会话恢复令牌。请验证重启和分叉行为，而不是仅仅重命名 ID。
• Pydantic AI 的批准机制会暂缓已验证的工具调用。应用仍负责经过身份验证的授权、身份和审计，并且受保护的操作不得在批准前执行。
• 请根据触发时机、输入、顺序、修改、阻止行为和错误行为映射钩子。Claude 钩子匹配器可能并发运行。Pydantic AI 按能力顺序运行 before_* 钩子，按相反顺序运行 after_* 钩子，并将 wrap_* 钩子嵌套起来，最先的能力位于最外层。任何可被钩子观察到的契约都必须有一份黄金轨迹。
• 请映射使用方对流式处理的意图。Pydantic AI 的输出流式处理、运行事件流式处理和图迭代是不同的接口；它们都不承诺采用 Claude SDK 的消息分类体系。
• 仅在模型指挥委派时使用 Harness SubAgents。将确定性编排和验证循环保留在应用代码中。
• Harness Skills 按需提供 SKILL.md 指令；请分别验证资源和脚本，不要假定它与 Claude Code 的技能或插件加载行为一致。
• Harness 命令控制只是尽力而为的策略，不是操作系统安全边界。对于不可信执行，请在适用时使用 ModalSandbox，或保留由应用管理的容器、虚拟机或沙箱隔离。
• 文件回退、Claude Code 提示词预设、插件打包、原始流事件标识，以及动态 MCP 控制都属于尚未覆盖的功能，除非迁移后的调用方确实需要这些功能，并且已验证存在公开的目标接口。

实施并验证一个垂直切片

1. 保留受支持的调用方边界，只替换 Agent 自有的内部实现。
2. 从仅包含核心功能开始。只有源契约要求时，才添加范围最窄的 Harness 能力。
3. 在该边界测试输入、类型化输出、错误、事件顺序、工具参数和结果、批准决策、跨轮状态及副作用。离线测试使用确定性模型和模拟的应用服务；只有当提供方行为属于契约时，才添加有针对性的录制测试或实时测试。
4. 对于恢复、持久性、批准、并发工具或外部操作，应在源代码承诺的确切边界测试中断与重启、沿袭关系、授权和幂等性。
5. 只有在没有任何保留路径导入 claude-agent-sdk、启动 Claude Code、读取其转录记录或使用其事件／结果类型后，才移除 claude-agent-sdk。

在实施前说明任何重大的语义变化：说明源行为、目标行为、对调用方的影响、建议的选择及剩余风险。

完成

遵循验证与切换中的完成标准。准确标注来自模拟对象、录制记录和实时提供方的证据。