migrating-agno-to-pydantic-ai

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate Agno to Pydantic AI

将 Agno 迁移到 Pydantic AI

Preserve observable behavior, not Agno's object model. Migrate the smallest complete caller path and keep application infrastructure in place.

保留可观察行为，而非 Agno 的对象模型。迁移最小但完整的调用方路径，并保持现有应用基础设施不变。

Trace the source before choosing a target

在选择目标前追踪源实现

Read repository instructions, dependencies, tests, and the runtime entrypoint. Record the installed Agno, Pydantic AI, and Harness versions.
Trace one real request from
```
Agent.run()
```
/
```
arun()
```
,
```
Team.run()
```
/
```
arun()
```
, a
```
Workflow
```
, or an AgentOS endpoint through instructions, model and tool calls, hooks, session loading, memory or knowledge retrieval, events, results, state, and side effects. Establish a focused baseline or characterization test.
Separate these source contracts when present:
- trusted dependencies, model-chosen tool input, session state, and workflow state;
- conversation history, session summaries, user memories, knowledge retrieval, workflow checkpoints, and model-owned plans;
- final content, structured output, token deltas, run events, pauses, and terminal status;
- confirmation, user input, external tool execution, authenticated authorization, and process isolation;
- team delegation, deterministic workflow control, AgentOS transport, queues, and deployment.
Record each observed contract, its owner, semantic difference, and executable proof. An unused Agno feature is not migration scope.

Read Research and concept mapping for the detected features. Read Verification and cutover before implementation.

阅读仓库说明、依赖项、测试和运行时入口点。记录已安装的 Agno、Pydantic AI 和 Harness 版本。
追踪一次真实请求：从
```
Agent.run()
```
/
```
arun()
```
、
```
Team.run()
```
/
```
arun()
```
、
```
Workflow
```
或 AgentOS endpoint 出发，经过指令、模型和工具调用、Hook、Session 加载、Memory 或 Knowledge 检索、事件、结果、状态和副作用。建立一个聚焦的基线测试或特征化测试。
存在以下源契约时，将它们彼此分离：
- 受信任的依赖项、模型选择的工具输入、Session 状态和 Workflow 状态；
- 对话历史、Session 摘要、用户 Memory、Knowledge 检索、Workflow checkpoint 和由模型持有的 plan；
- 最终内容、结构化输出、token 增量、运行事件、暂停和终止状态；
- 确认、用户输入、外部工具执行、经过身份验证的授权和进程隔离；
- Team 委派、确定性的 Workflow 控制、AgentOS 传输、队列和部署。
记录每个观察到的契约、其所属方、语义差异和可执行证明。未使用的 Agno 功能不属于迁移范围。

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

Choose the smallest target

选择最小目标

Core: use
```
pydantic_ai.Agent
```
for the agent loop, typed dependencies, tools, outputs, normalized messages, generic hooks, streaming, MCP clients, approvals, usage limits, instrumentation, realtime, and durable-runtime integrations.
Graph: use
```
pydantic_graph
```
only when explicit typed nodes, branches, and joins remain useful; use plain async Python for simple fixed control flow.
Harness: add
```
pydantic-ai-harness
```
only for observed reusable policy such as memory notebooks, planning, model-directed subagents, Agent Skills, coding tools, guardrails, model-agnostic compaction, or step persistence. Harness capabilities compose through the core agent loop; Harness is not a second runtime.
Evals: add the separate
```
pydantic-evals
```
package for observed datasets and evaluators.
Application: retain authentication, databases, vector search, queues, AgentOS/API routes, storage schemas, deployment, product state, and UI transports unless the requested slice includes them.
Gap: name behavior that no supported public seam preserves, explain its impact, and test a bounded adapter. Do not rebuild Agno's registry, database abstraction, event taxonomy, or AgentOS merely to hide a difference.

The normal migration is one reusable

Agent

, application services supplied through typed dependencies, typed tools and output, and application-owned storage of serialized

result.all_messages()

for later turns. Preserve an existing HTTP, job, or UI boundary with a small adapter and its current field names.

Core: 使用
```
pydantic_ai.Agent
```
处理 Agent 循环、类型化依赖项、工具、输出、标准化消息、通用 Hook、流式传输、MCP 客户端、审批、用量限制、instrumentation、realtime 和 durable-runtime 集成。
Graph: 仅当显式类型化节点、分支和汇合仍有价值时，才使用
```
pydantic_graph
```
；对于简单的固定控制流，使用普通异步 Python。
Harness: 仅当存在已观察到的可复用 policy 时，才添加
```
pydantic-ai-harness
```
，例如 memory notebook、planning、model-directed subagent、Agent Skill、coding tool、guardrail、model-agnostic compaction 或 step persistence。Harness 能力通过 Core Agent 循环进行组合；Harness 不是第二套 runtime。
Evals: 为观察到的数据集和评估器添加独立的
```
pydantic-evals
```
包。
Application: 除非请求的切片包含，否则保留身份验证、数据库、向量搜索、队列、AgentOS/API 路由、存储 schema、部署、产品状态和 UI 传输机制。
Gap: 明确指出任何受支持的公共扩展点（seam）都无法保留的行为，解释其影响，并测试一个有边界的 adapter。不要仅仅为了掩盖差异，就重建 Agno 的 registry、数据库抽象、事件分类体系或 AgentOS。

常规迁移方案是使用一个可复用的

Agent

，通过类型化依赖项提供应用服务，使用类型化工具和输出，并由应用负责存储序列化后的

result.all_messages()

，以供后续轮次使用。通过小型 adapter 保留现有 HTTP、job 或 UI 边界及其当前字段名。

Apply high-risk gates

执行高风险关卡检查

Agno
```
dependencies
```
,
```
user_id
```
,
```
session_id
```
, and authenticated identity are trusted runtime context, not model arguments. Put them in typed dependencies and authorize storage or effects in application code.
Agno sessions combine distinct owners. Map chat history to serialized Pydantic AI messages; keep mutable product/session state in an application store; treat summaries, user memories, knowledge retrieval, workflow checkpoints, and Harness
```
Memory
```
as separate contracts. Choose and test record conversion, a read-through adapter, or starting fresh as an accepted change.
Inspect a
```
Team
```
's actual delegation mode and caller-visible member events. Use Harness
```
SubAgents
```
only for model-directed, isolated task delegation. Keep routing, broadcast, deterministic fan-out, shared-context collaboration, aggregation, and retries in application or graph code unless parity is proved.
Keep Agno
```
Workflow
```
steps, conditions, routers, loops, and parallel joins deterministic. Do not move them into an agent prompt. Graph state alone is not a persisted checkpoint.
Agno pauses for confirmation, user input, and external execution have different payloads and owners. Core deferred tools can preserve pending model tool calls; the application still owns identity, authorization, UI, audit, persistence, correlation, and idempotency. Prove restart when the source pause survives one.
Map pre/post hooks, tool hooks, and guardrails by firing point, mutation, short-circuit behavior, ordering, retries, streaming visibility, and persistence. Similar hook names do not prove lifecycle parity.
Map consumer intent for streaming. Pydantic AI output streaming, run-event streaming, capability events, UI adapters, and graph iteration are different surfaces; none promises Agno's run-event taxonomy or resume cursor.
Agno Skills can expose instructions, references, and scripts. Harness
```
Skills
```
loads
```
SKILL.md
```
instructions on demand but does not load bundled resources or execute scripts; add explicit
```
FileSystem
```
,
```
Shell
```
, or application tools only for observed, trusted behavior.
AgentOS routes, auth, session APIs, telemetry, control plane, database selection, and deployment are product infrastructure. Keep or replace each deliberately rather than treating an agent port as an AgentOS port.
Tool allowlists, path checks, and guardrails are policy, not OS isolation. Use a container, VM, or cloud sandbox when untrusted execution is in scope.

Agno
```
dependencies
```
、
```
user_id
```
、
```
session_id
```
和已认证身份属于受信任的 runtime 上下文，而不是模型参数。将它们放入类型化依赖项，并在应用代码中对存储或副作用执行授权。
Agno Session 将不同所属方的内容组合在一起。将聊天历史映射为序列化后的 Pydantic AI 消息；将可变的产品/Session 状态保留在应用存储中；将摘要、用户 Memory、Knowledge 检索、Workflow checkpoint 和 Harness
```
Memory
```
视为独立契约。选择并测试记录转换、read-through adapter，或重新开始，并将其作为一项已接受的变更。
检查
```
Team
```
的实际委派模式和调用方可见的成员事件。仅在需要模型驱动的隔离任务委派时使用 Harness
```
SubAgents
```
。除非已证明行为一致，否则将路由、广播、确定性 fan-out、共享上下文协作、聚合和重试保留在应用或 Graph 代码中。
保持 Agno
```
Workflow
```
的步骤、条件、路由器、循环和并行汇合具有确定性。不要将它们移入 Agent prompt。仅有 Graph 状态并不能构成持久化 checkpoint。
Agno 中用于确认、用户输入和外部执行的暂停具有不同的 payload 和所属方。Core deferred tool 可以保留待处理的模型工具调用；应用仍负责身份、授权、UI、审计、持久化、关联性和幂等性。如果源暂停需要跨重启保留，请证明重启后的行为。
按触发点、变更行为、短路行为、顺序、重试、流式可见性和持久化方式映射 pre/post hook、tool hook 和 guardrail。相似的 hook 名称不能证明生命周期一致。
明确消费者对流式传输的具体需求。Pydantic AI output streaming、run-event streaming、capability event、UI adapter 和 Graph iteration 是不同的交互面；它们均不保证提供 Agno 的 run-event 分类体系或 resume cursor。
Agno
```
Skills
```
可以提供 instructions、references 和 scripts。Harness
```
Skills
```
会按需加载
```
SKILL.md
```
instructions，但不会加载随附资源或执行脚本；仅针对已观察到且可信的行为，添加显式的
```
FileSystem
```
、
```
Shell
```
或应用工具。
AgentOS 路由、auth、Session API、telemetry、控制平面、数据库选择和部署属于产品基础设施。应有意识地逐项保留或替换，而不要将 agent port 当作 AgentOS port。
工具白名单、路径检查和 guardrail 属于 policy，而不是 OS 隔离。当迁移范围包含不可信执行时，使用 container、VM 或 cloud sandbox。

Implement and prove one vertical slice

实现并证明一个垂直切片

Preserve the supported caller boundary and replace only agent-owned internals.
Start core-only. Add
```
pydantic_graph
```
, Harness, Evals, or a durable runtime only after a source contract requires it.
Test inputs, typed outputs, errors, event order, tool arguments/results, hook decisions, state across turns, and side effects at that boundary. Use deterministic models and fake application services offline; add a focused recorded or live test only when provider behavior is the contract.
For persistence, pauses, concurrent workflows, or external effects, test interruption and restart, lineage, authorization, failure aggregation, and idempotency at the exact boundary Agno promised.
Remove
```
agno
```
, AgentOS setup, and Agno storage or event adapters only after no retained path needs them.

Explain any consequential semantic change before implementing it: state the source behavior, target behavior, caller impact, recommended choice, and remaining risk.

保留受支持的调用方边界，仅替换由 Agent 负责的内部实现。
从仅使用 Core 开始。只有在源契约需要时，才添加
```
pydantic_graph
```
、Harness、Evals 或 durable runtime。
在该边界处测试输入、类型化输出、错误、事件顺序、Tool 参数和结果、Hook 决策、跨轮次状态及副作用。离线使用确定性模型和伪造的应用服务；仅当 provider 行为本身构成契约时，才添加有针对性的录制测试或实时测试。
对于持久化、暂停、并发 Workflow 或外部副作用，在 Agno 所承诺的确切边界处测试中断与重启、执行链路、授权、失败聚合和幂等性。
只有在任何保留路径都不再需要时，才移除
```
agno
```
、AgentOS 设置以及 Agno 存储或事件 adapter。

在实施任何影响重大的语义变更之前，先予说明：陈述源行为、目标行为、调用方影响、建议选择和剩余风险。

Completion

完成

Apply the completion criterion in Verification and cutover. Label evidence from fakes, recordings, live providers, and operational tests accurately.

应用验证与切换中的完成标准。准确标注证据来源，区分 fake、recording、live provider 和 operational test。