migrating-google-adk-to-pydantic-ai

将 Google ADK 迁移到 Pydantic AI

保留调用方可见的行为，而不是 ADK 的类树。迁移最小的完整请求路径，并将产品基础设施留在应用中。

从运行中的应用着手

1. 阅读仓库说明、依赖项、测试和运行时入口。记录已安装的 Google ADK、Pydantic AI 和可选的 pydantic-ai-harness 版本。
2. 从 Runner.run_async() 或已部署的端点开始，追踪一个真实请求经过根 Agent、指令、协作模式、模型调用、工具、工作流节点、回调/插件、会话服务、发出的事件、状态/资源变更和最终响应的全过程。仅记录该路径实际使用的行为。
3. 选择目标前，先区分以下契约：
   • 用作模型上下文的 Session.events；
   • 会话级、用户级、应用级和调用级状态；
   • 可搜索的长期记忆；
   • 工作流/节点检查点和恢复 ID；
   • 有版本控制的资源和外部副作用。
4. 对当前使用的部分进行分类：
   • 普通 LlmAgent： 通常使用一个可复用的 Agent，并配置类型化依赖项、工具和输出。
   • ADK 图或动态工作流： 在普通异步 Python 代码中保留简单的确定性控制流；如果显式的类型化节点、分支或图检查仍有价值，则使用 pydantic_graph。
   • 多 Agent 委派： 在 Python 2.x 中检查 ADK 的协作 mode；1.x 的 sub_agents 使用 chat 行为。对于 chat 转交语义，使用核心多 Agent 模式。只有当隔离上下文、返回、交互和并发行为相符时，Harness SubAgents 才适用于 task 或 single_turn。
   • 产品运行时： 保留身份验证、会话/状态存储、资源存储、队列、传输、A2A 端点、评估、可观测性和部署，除非它们明确属于迁移范围。
5. 添加确定性的特征测试，然后在现有调用方边界后迁移一个垂直切片。
6. 运行原有测试和针对性的行为一致性测试。将未经测试的行为标记为 unverified；名称相似不能作为等价的证据。

对于切片使用的功能，请阅读概念映射。对于工作流、状态、恢复、确认、回调/插件、事件流、技能或执行环境，请阅读语义差异。在移除 ADK 或更改生产流量前，请阅读验证与切换。

高风险关卡

• 不要将 ADK Session 对象或可变状态字典通过模型选择的工具参数传递。将经过身份验证的身份和服务客户端放入类型化依赖项；通过应用自有存储持久化产品和工作流状态。
• message_history 会延续模型上下文。它不能替代 ADK 会话状态、记忆、工件、事件记录、节点检查点或调用恢复。
• ADK 可恢复性会重放已记录的节点／工具结果，也可能多次执行工具。请明确选择持久化执行设计，并验证重启行为及副作用的幂等性。
• 明确区分对话输入、审批和授权。将工具确认映射到延迟工具审批；在受信任的应用代码中执行身份和访问检查。
• 有意保留回调／插件的顺序和短路规则。Pydantic AI 钩子有自己的能力排序，以及基于异常的跳过／恢复语义；一组看似相同的钩子并不等于行为一致。
• ADK 部分事件会在不应用状态增量的情况下传递；每个非部分事件在追加时都会应用其增量。工件写入发生在工件操作期间，早于当前事件记录所返回的版本。如果调用方会使用 ADK 事件字段或最终事件检测逻辑，请保留边界适配器，并测试确切的流和持久化顺序。
• 仅在观察到可复用能力时使用 Harness。普通 Agent 只需要 core，而命令允许列表并非 OS 安全边界。

Pydantic AI 默认设置

• 将 instruction 映射为 instructions；如果指令取决于受信任的运行时数据，请使用 RunContext 指令函数。
• 将函数工具映射为类型化的 Pydantic AI 工具。仅在调用方依赖时，才保留工具名称、描述、验证行为、错误形式、重试、确认和并发行为。
• 当终端输出契约是结构化数据时，将 output_schema 映射为 output_type。如果更改响应形式会扩大迁移范围，请保留现有的线缆适配器。
• 将 ModelMessage 历史与工作流和产品状态分开持久化。添加新的持久化子系统之前，先复用应用当前的存储。
• 使用 Hooks 进行本地生命周期拦截；对于同时管理工具、指令、设置或事件的可复用策略，则使用自定义能力。
• 除非请求变更，否则保留当前模型／提供方。使用带提供方前缀的 Pydantic AI 模型 ID，并根据已安装的 API 验证提供方特有的工具、设置、流式传输和实时行为。

完成标准

只有在每个已观察到的调用方契约都有可执行证据证明其已保留、被明确接受为已变更或不适用时，此切片才算完成。将未验证和受阻的契约视为未完成。只要保留的运行时、会话迁移、部署命令、评估或兼容路径仍导入或调用 google-adk，就不要移除它。