migrating-google-adk-to-pydantic-ai

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate Google ADK to Pydantic AI

将 Google ADK 迁移到 Pydantic AI

Preserve caller-visible behavior, not ADK's class tree. Migrate the smallest complete request path and leave product infrastructure in the application.

保留调用方可见的行为，而不是照搬 ADK 的类层次结构。迁移最小但完整的请求路径，并将产品基础设施保留在应用程序中。

Work from the running application

从实际运行的应用入手

Read repository instructions, dependencies, tests, and runtime entrypoints. Record the installed Google ADK, Pydantic AI, and optional
```
pydantic-ai-harness
```
versions.
Trace one real request from
```
Runner.run_async()
```
or the deployed endpoint through the root agent, instructions, collaboration mode, model calls, tools, workflow nodes, callbacks/plugins, session service, emitted events, state/artifact deltas, and final response. Record only behavior that path uses.
Separate the contracts before choosing targets:
- ```
Session.events
```
  used as model context;
- session-, user-, app-, and invocation-scoped state;
- searchable long-term memory;
- workflow/node checkpoints and resume IDs;
- versioned artifacts and external side effects.
Classify the active slice:
- Ordinary
  LlmAgent
  : normally one reusable
```
Agent
```
  with typed dependencies, tools, and output.
- ADK graph or dynamic workflow: keep simple deterministic control flow in plain async Python; use
```
pydantic_graph
```
  when explicit typed nodes, branching, or graph inspection remain valuable.
- Multi-agent delegation: inspect ADK's collaboration
```
mode
```
  in Python 2.x; 1.x
```
sub_agents
```
  use
```
chat
```
  behavior. Use core multi-agent patterns for
```
chat
```
  transfer semantics. Harness
```
SubAgents
```
  can fit
```
task
```
  or
```
single_turn
```
  only when their isolated context, return, interaction, and concurrency behavior match.
- Product runtime: retain auth, session/state stores, artifact stores, queues, transport, A2A endpoints, evaluation, observability, and deployment unless they are explicitly in scope.
Add deterministic characterization tests, then migrate one vertical slice behind its existing caller boundary.
Run the original tests and focused parity tests. Mark unexercised behavior
```
unverified
```
; similar names are not equivalence evidence.

Read Concept Mapping for the features the slice uses. Read Semantic Gaps for workflows, state, resume, confirmation, callbacks/plugins, event streams, skills, or execution environments. Read Verification and Cutover before removing ADK or changing production traffic.

阅读仓库说明、依赖项、测试和运行时入口点。记录已安装的 Google ADK、Pydantic AI 以及可选的
```
pydantic-ai-harness
```
版本。
从
```
Runner.run_async()
```
或已部署的端点开始，追踪一次真实请求，贯穿根 Agent、instructions、协作 mode、模型调用、工具、工作流节点、callbacks/plugins、session service、发出的 events、state/artifact deltas 以及最终响应。仅记录该路径所使用的行为。
在选择目标之前，先分离各类契约：
- ```
Session.events
```
  用作模型上下文；
- session、user、app 和 invocation 作用域的 state；
- 可搜索的长期 memory；
- 工作流/节点检查点和 resume IDs；
- 带版本的 artifacts 和外部副作用。
对当前切片进行分类：
- **普通
```
LlmAgent
```
  ：**通常对应一个可复用的
```
Agent
```
  ，并配备类型化依赖项、工具和输出。
- **ADK 图或动态工作流：**将简单且确定性的控制流保留在普通异步 Python 中；当显式类型化节点、分支或图检查仍有价值时，使用
```
pydantic_graph
```
  。
- **多 Agent 委派：**在 Python 2.x 中检查 ADK 的协作
```
mode
```
  ；1.x 的
```
sub_agents
```
  使用
```
chat
```
  行为。对于
```
chat
```
  转移语义，使用核心 multi-agent patterns。只有当隔离上下文、返回结果、交互和并发行为完全匹配时，Harness 的
```
SubAgents
```
  才能适配
```
task
```
  或
```
single_turn
```
  。
- **产品运行时：**除非明确纳入范围，否则保留 auth、session/state 存储、artifact 存储、队列、传输、A2A 端点、评估、可观测性和部署。
添加确定性的特征测试，然后在现有调用方边界之后迁移一个垂直切片。
运行原始测试和聚焦的等价性测试。将未被测试覆盖的行为标记为
```
unverified
```
；名称相似不能作为等价性证据。

阅读 Concept Mapping，了解该切片使用的功能。阅读 Semantic Gaps，了解工作流、state、resume、confirmation、callbacks/plugins、event streams、skills 或执行环境。在移除 ADK 或更改生产流量之前，阅读 Verification and Cutover。

High-risk gates

高风险关卡

Do not pass ADK
```
Session
```
objects or mutable state dictionaries through model-chosen tool arguments. Put authenticated identity and service clients in typed dependencies; persist product and workflow state through application-owned stores.
```
message_history
```
continues model context. It does not replace ADK session state, memory, artifacts, event records, node checkpoints, or invocation resume.
ADK resumability replays recorded node/tool results and can execute tools more than once. Choose a durable execution design explicitly and prove restart plus idempotency for side effects.
Keep conversational input, approval, and authorization distinct. Map tool confirmation to deferred tool approval; keep identity and access checks in trusted application code.
Preserve callback/plugin ordering and short-circuit rules deliberately. Pydantic AI hooks have their own capability ordering and exception-based skip/recovery semantics; a list of lookalike hooks is not parity.
ADK partial events are delivered without applying state deltas; each non-partial event applies its delta when appended. Artifact writes happen during the artifact operation, before the current event records the returned version. If callers consume ADK event fields or final-event detection, retain a boundary adapter and test the exact stream and persistence order.
Use Harness only for an observed reusable capability. Ordinary agents need core only, and a command allowlist is not an OS security boundary.

不要让 ADK
```
Session
```
对象或可变 state 字典通过模型选择的工具参数传递。将已认证的身份和服务客户端放入类型化依赖项；通过应用自有存储持久化产品和工作流 state。
```
message_history
```
延续模型上下文。它不能替代 ADK session state、memory、artifacts、event records、node checkpoints 或 invocation resume。
ADK resumability 会重放已记录的节点/工具结果，并且可能多次执行工具。明确选定一种 durable execution 设计，并证明能够重启以及副作用具有幂等性。
明确区分对话输入、审批和授权。将工具确认映射到 deferred tool approval；将身份和访问检查保留在可信应用代码中。
有意保留 callback/plugin 的顺序和短路规则。Pydantic AI hooks 拥有自己的能力排序和基于异常的跳过/恢复语义；一组外观相似的 hooks 并不代表行为一致。
ADK partial events 会在应用 state deltas 前交付；每个非 partial event 在追加时会应用其 delta。Artifact 写入发生在 artifact 操作期间，早于当前 event 记录返回的版本。如果调用方依赖 ADK event 字段或 final-event 检测，请保留边界适配器，并测试完全一致的 stream 和持久化顺序。
仅将 Harness 用于已经观察到且可复用的能力。普通 Agent 只需要 core；命令 allowlist 不是 OS 安全边界。

Pydantic AI defaults

Pydantic AI 默认做法

Map
```
instruction
```
to
```
instructions
```
; use a
```
RunContext
```
instructions function when it depends on trusted runtime data.
Map function tools to typed Pydantic AI tools. Preserve tool names, descriptions, validation behavior, error shape, retries, confirmation, and concurrency only where callers rely on them.
Map
```
output_schema
```
to
```
output_type
```
when the terminal output contract is structured. Preserve an existing wire adapter if changing response shape would widen the migration.
Persist
```
ModelMessage
```
histories separately from workflow and product state. Reuse the application's current stores before adding a new persistence subsystem.
Use
```
Hooks
```
for local lifecycle interception or a custom capability for reusable policy that also owns tools, instructions, settings, or events.
Keep the active model/provider unless changing it is requested. Use provider-prefixed Pydantic AI model IDs and verify provider-specific tools, settings, streaming, and realtime behavior against installed APIs.

将
```
instruction
```
映射为
```
instructions
```
；当其依赖可信运行时数据时，使用
```
RunContext
```
instructions 函数。
将函数工具映射为类型化的 Pydantic AI 工具。仅在调用方依赖时，保留工具名称、描述、验证行为、错误结构、重试、确认和并发方式。
当终端输出契约为结构化格式时，将
```
output_schema
```
映射到
```
output_type
```
。如果更改响应结构会扩大迁移范围，请保留现有的 wire adapter。
将
```
ModelMessage
```
histories 与 workflow 和 product state 分开持久化。在添加新的持久化子系统之前，先复用应用程序当前的 stores。
使用
```
Hooks
```
进行本地生命周期拦截；对于还负责 tools、instructions、settings 或 events 的可复用策略，使用 custom capability。
除非明确要求更改，否则保持当前 model/provider 不变。使用带 provider 前缀的 Pydantic AI model IDs，并针对已安装的 API 验证 provider 特定的 tools、settings、streaming 和 realtime 行为。

Completion

完成标准

The slice is complete only when every observed caller contract is

preserved

by executable evidence, explicitly accepted as

changed

, or

not applicable

. Treat

unverified

and

blocked

contracts as unfinished. Do not remove

google-adk

while a retained runtime, session migration, deployment command, evaluation, or compatibility path still imports or invokes it.

只有当每个已观察到的调用方契约都通过可执行证据证明为

preserved

、明确接受为

changed

，或被判定为

not applicable

时，该切片才算完成。将

unverified

和

blocked

契约视为未完成。只要保留的运行时、会话迁移、部署命令、评估或兼容性路径仍会导入或调用

google-adk

，就不要移除

google-adk

。