migrating-vercel-ai-sdk-and-eve-to-pydantic-ai

将 Vercel AI SDK 和 Eve 迁移到 Pydantic AI

保留应用的可观察行为，而不是源 API。Vercel AI SDK Core、AI SDK UI 和 Eve 的职责各不相同：在选择目标之前，先确定每种源行为由谁负责。

选择目标之前先追踪源行为

1. 阅读仓库说明、依赖项、锁文件、测试和运行时入口。将 workspace:* 依赖解析为具体的软件包版本，并记录已安装的 AI SDK、Eve、Pydantic AI 和 Harness 版本。
2. 从公开入口开始，追踪一个真实请求经过的消息、模型调用、工具、审批、流、持久化、副作用，以及调用方使用的结果。建立有针对性的基线测试或特征测试。
3. 对观察到的每项契约进行分类：
   • AI SDK Core： 模型调用、步骤循环、工具执行、结构化输出和提供商路由；
   • AI SDK UI： UIMessage、useChat、传输、客户端工具、流块和重连行为；
   • Eve： 由文件系统定义的 Agent、持久会话、技能、子 Agent、状态、连接、通道、计划任务和沙箱；
   • 应用／平台： 身份验证、授权、存储、队列、部署、凭据、产品 UI 和 Vercel 托管服务。
4. 记录每项契约、其负责人、语义差异和可执行证明。未使用的功能不属于迁移范围。

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

选择最小化目标

• Core： 使用 pydantic_ai.Agent 实现 Agent 循环、类型化依赖项、工具、输出、消息、流式处理、MCP 客户端、审批、使用限制、插桩和持久运行时集成。
• Graph： 仅在显式类型化节点、分支和汇合仍有用时使用 pydantic_graph；对于简单的固定控制流，使用普通异步 Python。
• Harness： 仅当观察到的可复用策略需要它时，才添加 pydantic-ai-harness，例如 Agent Skills、由模型指派的子 Agent、规划、记忆笔记本、编码工具、护栏或步骤持久化。Harness 功能通过核心 Agent 循环组合；Harness 并非与 Eve 兼容的运行时。
• 评估： 对于观察到的数据集、案例和评估器，添加独立的 pydantic-evals 软件包。
• 应用： 保留 UI、HTTP 传输、身份验证、持久化、重连状态、计划任务、部署、租户策略和托管服务，除非请求范围包含替换它们。
• 差距： 指明没有受支持的公开接口能够保留的行为，解释其影响，并测试范围明确的适配器。不要仅为掩盖差异而重建 AI SDK 或 Eve 对象模型。

通常，AI SDK 迁移是在现有调用方后面放置一个可复用的 Agent。将 @ai-sdk/workflow 视为持久运行时迁移，而非普通的 Agent 循环。当 TypeScript 或 React 客户端使用 AI SDK UI 时，应保留该 UI，并通过 VercelAIAdapter 提供与其已安装版本完全一致的协议；不要不必要地迁移 UI。如果源代码只是进程内的 TypeScript 调用，则在同一迁移切片中迁移其最近的调用方，或明确商定新的、由应用负责的服务边界。

通常，Eve 迁移由核心 Agent 加上仅与观察到的行为相匹配的 Harness 功能组成。在每项功能都得到经过验证的替代方案之前，应将 Eve 的持久会话驱动程序、产品端点、计划任务、通道、身份验证和托管服务保留在应用中。

执行高风险检查关卡

• generateText() 和 streamText() 默认只执行单个步骤，ToolLoopAgent 默认会进行更长的循环，而 WorkflowAgent 除非经过配置，否则没有最大步骤数。保留观察到的停止条件、用量限制，以及 prepareStep 对模型、工具、指令、消息或运行时上下文所做的更改；不要盲目照搬默认值。
• 区分本地工具、由提供商执行的工具、浏览器端／客户端工具和 MCP 工具。保留执行和凭据的所在位置、输入／结果架构、错误恢复、取消传播以及副作用幂等性。
• AI SDK 的异步生成器工具可在最终输出之前提供初步结果。普通 Pydantic AI 工具只会返回一次；请通过显式自定义事件重现已消费的中间 UI 状态，或记录这一有意的更改。
• 完整结构化输出会经过验证；部分流式输出可能不完整，而将工具与结构化输出结合使用可能需要另一个步骤。请测试调用方可见的时序和失败形式。
• UIMessage 是由客户端控制的应用状态，不是可信的提供商历史记录或依赖上下文。验证传入的消息，将身份和服务保留在服务器端，并仅将获准的内容转换为模型消息。
• 匹配已安装的 AI SDK 线协议。当前文档将基于 SSE 的 UI 消息线协议称为 Data Stream Protocol，而较早的实现可能使用名称相似、带行前缀的帧。请求正文、标头、帧、分块顺序、工具状态、错误／中止行为以及重新连接端点不可互换。请根据已安装的 SDK 版本配置 VercelAIAdapter，并对边界进行黄金测试。
• AI SDK 的审批通常是一个包含两个请求的对话；Eve 可以持久化挂起的会话；Pydantic AI 可以在当前运行中或之后的运行中解析延迟调用。持久化完整的待处理请求，将决策绑定到经过验证的参数和调用身份，对审批人进行身份验证，并证明受保护的操作只执行一次。
• Pydantic AI 消息历史无法在未解决的工具调用之后继续。如果 Eve 在审批仍待处理时接受了无关的轮次，请在应用状态中单独保存待处理分支；不要将无关提示追加到这段未完成的历史记录中。
• Eve 的会话、轮次、步骤、重放单元、事件游标、后台子 Agent 和 NDJSON 会话流共同构成一个持久化协议。核心消息历史和 Harness StepPersistence 并不能自动复现它。在重启和重放测试证明所承诺的行为之前，应保留由应用负责的会话适配器，或注明差异。
• Eve 的 defineState 数据与对话历史相互独立，持久化记忆也有自己的生命周期和共享规则。分别映射每个存储，并测试会话、用户和租户之间的隔离。
• Eve 的技能可以提供辅助文件。Harness Skills 只会加载 SKILL.md 指令；请通过 FileSystem 或应用工具提供所需的参考资料、资源或脚本，并明确测试这些内容。
• Eve 的子 Agent 可能是持久化的子会话，具有后台结果批处理和独立流。Harness SubAgents 会运行隔离的 Agent，并通过工具返回结果。只有在这种较窄的生命周期能保留观察到的契约时才使用它；否则应由应用负责编排。
• 文件系统或 shell 策略不等于沙箱隔离。如果涉及不可信执行，请使用真正的容器、虚拟机或受支持的云沙箱，以保留 Eve 的沙箱、凭据代理和网络边界。
• Eve 频道、计划任务、连接／OAuth、默认 HTTP API、Workflow SDK 持久化后端、Vercel Agent Runs 和部署集成均属于应用或平台层面的职责。应有意替换并测试这些内容，而不要将其归属于 Core 或 Harness。
• 只有在追踪到的路径实际使用时，才保留提供商路由、网关允许列表／回退机制、提供商选项、重试语义、遥测关联和评估数据集。

实现并验证一个纵向切片

1. 保留受支持的调用方边界，只替换由 Agent 管理的内部实现。
2. 从核心功能开始。只有在观察到的契约确有要求时，才添加 pydantic_graph、Harness、Pydantic Evals 或持久化运行时。
3. 在该边界测试输入、输出、错误、消息历史、事件顺序、工具参数与结果、步骤数、状态和副作用。离线测试时使用确定性模型和模拟应用服务；只有当提供方行为属于契约的一部分时，才添加有针对性的录制测试或实时测试。
4. 对于审批、重新连接、持久化会话、后台工作或外部副作用，测试中断和新进程重启、稳定的关联标识、授权、重放、取消和幂等性。
5. 只有在保留的 UI、传输层、Agent 或平台路径都不再需要 ai、@ai-sdk/* 或 eve 后，才将其移除。

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

完成

按照验证与切换中的完成标准执行。准确标注来自模拟对象、录制、实时提供方和真实沙箱的证据。