migrating-agno-to-pydantic-ai

将 Agno 迁移到 Pydantic AI

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

先追踪源行为，再选择目标

1. 阅读仓库说明、依赖项、测试和运行时入口。记录已安装的 Agno、Pydantic AI 和 Harness 版本。
2. 从 Agent.run() / arun()、Team.run() / arun()、Workflow 或 AgentOS 端点出发，追踪一个真实请求经过的指令、模型和工具调用、钩子、会话加载、记忆或知识检索、事件、结果、状态及副作用。建立有针对性的基线或特征测试。
3. 在以下内容存在时，分别明确其源行为约定：
   • 可信依赖、模型选择的工具输入、会话状态和工作流状态；
   • 对话历史、会话摘要、用户记忆、知识检索、工作流检查点和模型持有的计划；
   • 最终内容、结构化输出、令牌增量、运行事件、暂停和终止状态；
   • 确认、用户输入、外部工具执行、经过身份验证的授权和进程隔离；
   • 团队委派、确定性工作流控制、AgentOS 传输、队列和部署。
4. 记录每项观察到的行为约定、其所有者、语义差异和可执行证明。未使用的 Agno 功能不属于迁移范围。

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

选择最小目标

• **Core：**使用 pydantic_ai.Agent 实现 Agent 循环、类型化依赖、工具、输出、规范化消息、通用钩子、流式传输、MCP 客户端、审批、用量限制、检测、实时功能和持久运行时集成。
• **Graph：**仅在显式类型化节点、分支和汇合仍有价值时使用 pydantic_graph；简单的固定控制流则使用普通的异步 Python。
• **Harness：**仅当观察到可复用策略（例如记忆笔记本、规划、模型指派的子 Agent、Agent Skills、编码工具、护栏、模型无关的压缩或步骤持久化）时，才添加 pydantic-ai-harness。Harness 功能通过核心 Agent 循环组合；Harness 不是第二套运行时。
• **Evals：**对于观察到的数据集和评估器，添加独立的 pydantic-evals 包。
• **应用：**保留身份验证、数据库、向量搜索、队列、AgentOS/API 路由、存储架构、部署、产品状态和 UI 传输，除非请求的切片包含它们。
• **差距：**明确说明哪些行为无法通过受支持的公共接口保留，解释其影响，并测试有界适配器。不要仅为掩盖差异而重建 Agno 的注册表、数据库抽象、事件分类体系或 AgentOS。

常规迁移方案是使用一个可复用的 Agent，通过类型化依赖提供应用服务，使用类型化工具和输出，并由应用负责存储序列化后的 result.all_messages()，供后续轮次使用。通过小型适配器保留现有 HTTP、作业或 UI 边界，并沿用当前字段名。

应用高风险检查项

• Agno 的 dependencies、user_id、session_id 和经过身份验证的身份属于可信运行时上下文，而非模型参数。将它们放入类型化依赖项，并在应用代码中授权存储操作或副作用。
• Agno 会话会合并不同所有者的数据。将聊天历史映射为序列化的 Pydantic AI 消息；在应用存储中保留可变的产品／会话状态；将摘要、用户记忆、知识检索、工作流检查点和 Harness Memory 视为不同的契约。选择并测试记录转换、直读适配器或重新开始，并将其作为已接受的变更。
• 检查 Team 的实际委派模式及调用方可见的成员事件。仅在由模型决定且任务相互隔离的委派场景中使用 Harness SubAgents。除非已证明语义一致，否则应在应用代码或图代码中保留路由、广播、确定性扇出、共享上下文协作、聚合和重试。
• 保持 Agno Workflow 步骤、条件、路由器、循环和并行汇合操作为确定性逻辑。不要将它们移入 Agent 提示词。图状态本身并非持久化检查点。
• Agno 的确认暂停、用户输入暂停和外部执行暂停具有不同的负载和归属方。Core 延迟工具可以保留待处理的模型工具调用；但身份、授权、UI、审计、持久化、关联和幂等性仍由应用负责。如果源暂停可在重启后保留，就必须验证重启行为。
• 根据触发时机、修改内容、短路行为、顺序、重试、流式可见性和持久化情况，映射前置／后置钩子、工具钩子和护栏。钩子名称相似并不能证明生命周期语义一致。
• 根据使用方意图映射流式处理。Pydantic AI 输出流、运行事件流、能力事件、UI 适配器和图迭代是不同的接口；它们都不保证与 Agno 的运行事件分类或恢复游标一致。
• Agno Skills 可以提供指令、参考资料和脚本。Harness Skills 会按需加载 SKILL.md 指令，但不会加载附带资源或执行脚本；只有在观察到确切行为且其可信时，才添加显式的 FileSystem、Shell 或应用工具。
• AgentOS 的路由、身份验证、会话 API、遥测、控制平面、数据库选择和部署属于产品基础设施。应有意保留或替换各项，而不要将 Agent 迁移视为 AgentOS 迁移。
• 工具允许列表、路径检查和护栏属于策略，并非操作系统隔离。若涉及不可信执行，请使用容器、虚拟机或云沙箱。

实现并验证一个端到端切片

1. 保留受支持的调用方边界，只替换由 Agent 管理的内部实现。
2. 从仅使用 Core 开始。只有在源契约有要求时，才添加 pydantic_graph、Harness、Evals 或持久化运行时。
3. 在该边界测试输入、类型化输出、错误、事件顺序、工具参数／结果、钩子决策、跨轮次状态和副作用。离线使用确定性模型和模拟应用服务；仅当提供方行为属于契约时，才添加有针对性的录制测试或在线测试。
4. 对于持久化、暂停、并发工作流或外部副作用，请在 Agno 保证的确切边界测试中断与重启、沿袭关系、授权、失败聚合和幂等性。
5. 只有在确认不再有保留路径依赖它们后，才移除 agno、AgentOS 设置以及 Agno 存储或事件适配器。

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

完成

应用验证与切换中的完成标准。准确标注来自模拟对象、录制数据、在线提供方和运维测试的证据。