migrating-openai-agents-sdk-to-pydantic-ai

将 OpenAI Agents SDK 迁移到 Pydantic AI

保留调用方可见的行为，而不是 OpenAI Agents SDK 的对象形状。迁移最小的完整运行时切片，并保留现有应用基础设施。

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

1. 阅读仓库说明、依赖文件、测试和运行时入口。记录已安装的 openai-agents、Pydantic AI 和 Harness 版本。
2. 跟踪一个有代表性的 Runner.run、run_sync 或 run_streamed 调用，了解其指令、上下文、模型设置、工具、交接、护栏、会话状态、审批、事件、追踪和公开结果。检查使用 final_output、last_agent、new_items、to_input_list()、中断或流式事件的调用方。
3. 在现有应用边界建立确定性基线。只记录活跃路径实际使用的行为。
4. 在设计之前对切片进行分类：
   • 普通 Agent： 使用一个可复用的 Pydantic AI Agent，并为其配置带类型的依赖项、工具和输出。
   • 包含专家 Agent 的管理器： 根据最终响应的责任归属，采用显式应用编排、Agent 工具或 Harness SubAgents。
   • 交接工作流： 首先判断活跃 Agent、其指令和下一轮负责方是否会影响可观察行为。嵌套 Agent 工具不等于交接。
   • 沙箱或编码 Agent： 评估 Harness Coder 及其组件能力。单独选择执行环境；Shell 允许列表不等于隔离。
   • 实时或语音路径： 将传输、中断、音频和实时会话行为视为单独的迁移切片，并使用 Pydantic AI 实时 Agent。
   • 产品运行时： 保留身份验证、存储、队列、部署和服务集成，除非明确将其纳入范围。
5. 添加或保留特征测试，在现有公开边界后迁移一个纵向切片，并运行原有测试及针对性的行为一致性测试。

阅读概念映射，了解你发现的源功能。在更改持久化、交接、审批、流式处理、安全性或生产流量之前，以及在宣布完成或移除 openai-agents 之前，请阅读验证与切换。

在语义关卡处停下

• 上下文：RunContextWrapper.context 是可信的应用状态，通常会成为类型化的 deps。模型生成的交接字段和工具参数不是依赖项。
• **交接：**OpenAI 交接会在一次运行中替换当前 Agent，并通过 last_agent 提供继续执行所需的信息。Pydantic AI 的 Agent 委派通常会通过工具调用返回；请使用显式的应用路由保留转交语义，或记录这是有意变更。
• **对话状态：**区分手动的 to_input_list() 历史记录、SDK 的 Session 存储、OpenAI 的 conversation_id、OpenAI 的 previous_response_id，以及序列化后中断的 RunState。Pydantic AI 消息历史记录、提供方端继续执行、Harness 步骤持久化和持久化执行解决的是不同问题。
• **护栏：**保留检查的边界、是否会在工作开始前阻止执行、失败形式、替换行为和执行顺序。OpenAI 输入护栏默认可能并行运行，因此即使模型工作或工具副作用已经开始，也可能随后才触发熔断。
• **审批：**OpenAI HITL 会恢复序列化后的 RunState。如果同一次调用中即可获得决策，请使用 HandleDeferredToolCalls，让 Pydantic AI 运行能够在当前流程中继续。如果必须先结束运行，请将 DeferredToolRequests 纳入 output_type，然后持久化消息和完整请求——或持久化包含类别、已验证参数和元数据的等效待处理操作记录——再使用 DeferredToolResults 恢复运行。在受保护的工具内部重新授权；审批不等于授权。
• 工具完成：tool_use_behavior 可以让普通工具结果成为终止结果。在 Pydantic AI 中，应将成功的终止操作建模为输出函数或 ToolOutput；不要通过抛出异常来把成功值从工具中带出。
• **流式处理：**原始 Responses API 事件、运行项事件、生命周期事件、输出增量和最终完成是不同的契约。如果必须完成整个 Agent 循环，请使用 run(event_stream_handler=...)、run_stream_events() 或 iter()。只有在提交第一个匹配的输出并跳过后续工具调用仍能保留源契约时，才使用 run_stream()。请使所选接口适配公开架构。
• **追踪：**OpenAI 追踪和 Pydantic AI 的 OpenTelemetry 检测是不同的运维产品。除非用户接受范围更广的迁移，否则应保留现有遥测；如果选择 Pydantic AI 的一方体验，则推荐 Logfire。

Pydantic AI 默认设置

• 将凭据、经过身份验证的身份、客户端和配置放在类型化依赖项中，并在模型层以下强制执行权限。
• 如果使用 Pydantic 模型作为结构化终止输出能够保留线路契约，就应采用这种方式。确认源实现使用的是纯文本、结构化输出还是终止工具输出。
• 对应用执行的工具使用核心函数工具和 MCP 工具集。只有在所选提供方支持所需工具并能保留观测到的结果／事件契约时，才使用提供方原生功能。
• 普通 Agent 保持在 core 上。只有在观察到可复用能力时才添加 Harness，例如护栏、子 Agent、记忆、技能、文件系统／Shell 工具、规划、步骤持久化或沙箱。
• 除非提供方迁移属于范围，否则保留现有模型／提供方路径。转换 OpenAI 专属选项之前，先检查已安装的 Pydantic AI 模型设置。
• 检查源实现实际生效的 max_turns，包括省略时 SDK 的默认值。只有在确认计数和失败契约后，才使用 UsageLimits.request_limit 保留该限制，而不要直接沿用 Pydantic AI 不同的默认值。

完成

在干净的环境中安装并导入迁移后的项目，使其依赖文件与运行时保持一致。当每项已观察到的公共契约都通过可执行检查得到保留、经过有记录的影响评估后有意更改、归属明确的外部组件，或明确标记为不适用时，该部分即告完成。未经测试的契约属于未验证状态；尚未解决的必需契约会阻止切换。