Migrating Vercel AI SDK And Eve To Pydantic AI

PydanticOfficialPublished by Pydantic

Skill
Workflow
Software development
MIT
No issues found

From the author

Migrate TypeScript Vercel AI SDK or Eve applications to Python with Pydantic AI and, only when needed, Pydantic AI Harness. Use when source code imports `ai`, `@ai-sdk/*`, or `eve`, or relies on `generateText`, `streamText`, `ToolLoopAgent`, `useChat`, Eve agents, tools, skills, subagents, approvals, sessions, channels, schedules, or sandboxes.

— the description by Pydantic

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured methodology for porting AI-driven applications from TypeScript (Vercel AI SDK or Eve) to Python (Pydantic AI). It emphasizes preserving observable application behavior over direct API translation. The process involves tracing existing request lifecycles, classifying contracts, choosing the appropriate Pydantic AI components (Core, Graph, or Harness), and implementing vertical slices with rigorous verification to ensure parity.

What it does

Traces existing request lifecycles from entry points to final results.
Maps TypeScript AI SDK and Eve features to Pydantic AI equivalents.
Provides guidance on selecting between Pydantic AI Core, Graph, and Harness.
Defines a contract ledger to track migration parity and evidence.
Offers strategies for handling complex features like approvals, streaming, and durable sessions.
Establishes testing protocols for verifying cross-language boundaries.

When to use it

When migrating an existing TypeScript application using Vercel AI SDK or Eve to Python.
When you need to maintain specific agent behaviors, tool loops, or durable session states during a language migration.
When you require a structured approach to ensure parity in complex AI agent workflows.
When you need to verify that migrated agent logic behaves identically to the source implementation.

Advantages

Reduces risk by focusing on observable behavior rather than blind API mapping.
Ensures architectural integrity by separating agent logic from application infrastructure.
Provides clear criteria for when to introduce advanced components like Harness or Graph.
Includes built-in verification steps to prevent regressions in agent behavior.

Usage examples

“How do I start migrating a Vercel AI SDK v6 application to Pydantic AI?”: The agent will guide you to first trace the current request lifecycle, identify the specific AI SDK contracts being used, and establish a baseline test before selecting the appropriate Pydantic AI components.
“Should I use Pydantic AI Harness for my Eve migration?”: The agent will help you analyze your observed Eve behaviors to determine if Harness is necessary for features like subagents or step persistence, or if Pydantic AI Core is sufficient.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/pydantic/migrating-vercel-ai-sdk-and-eve-to-pydantic-ai/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip migrating-vercel-ai-sdk-and-eve-to-pydantic-ai.zip -d .agents/skills

Documentation by Pydantic

Migrate Vercel AI SDK and Eve to Pydantic AI

Preserve the application's observable behavior, not the source APIs. Vercel AI SDK Core, AI SDK UI, and Eve have different responsibilities: identify which one owns each source behavior before choosing a target.

Trace the source before choosing a target

Read repository instructions, dependencies, lockfiles, tests, and the runtime entrypoint. Resolve workspace:* dependencies to concrete package versions and record the installed AI SDK, Eve, Pydantic AI, and Harness versions.
Trace one real request from its public entrypoint through messages, model calls, tools, approvals, streams, persistence, side effects, and the result the caller consumes. Establish a focused baseline or characterization test.
Classify every observed contract:
- AI SDK Core: model calls, step loops, tool execution, structured output, and provider routing;
- AI SDK UI: UIMessage, useChat, transports, client tools, stream chunks, and reconnect behavior;
- Eve: filesystem-defined agents, durable sessions, skills, subagents, state, connections, channels, schedules, and sandboxes;
- Application/platform: authentication, authorization, storage, queues, deployment, credentials, product UI, and hosted Vercel services.
Record each contract, its owner, semantic difference, and executable proof. An unused feature is not migration scope.

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

Choose the smallest target

Core: use pydantic_ai.Agent for the agent loop, typed dependencies, tools, outputs, messages, streaming, MCP clients, approvals, usage limits, instrumentation, 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 Agent Skills, model-directed subagents, planning, memory notebooks, coding tools, guardrails, or step persistence. Harness capabilities compose through the core agent loop; Harness is not an Eve-compatible runtime.
Evals: add the separate pydantic-evals package for observed datasets, cases, and evaluators.
Application: retain UI, HTTP transports, auth, persistence, reconnect state, schedulers, deployment, tenant policy, and hosted services unless the requested slice includes replacing them.
Gap: name behavior that no supported public seam preserves, explain its impact, and test a bounded adapter. Do not recreate the AI SDK or Eve object model merely to hide a difference.

The normal AI SDK migration is one reusable Agent behind the existing caller. Treat @ai-sdk/workflow as a durable-runtime migration, not an ordinary agent loop. When a TypeScript or React client uses AI SDK UI, keep it and serve its exact installed-version protocol with VercelAIAdapter; do not migrate the UI unnecessarily. When the source is only an in-process TypeScript call, migrate its nearest caller in the same slice or explicitly agree on a new application-owned service boundary.

The normal Eve migration is a core agent plus only the Harness capabilities that match observed behavior. Keep Eve's durable session driver, product endpoints, schedules, channels, authentication, and hosted services in the application until each has a proved replacement.

Apply high-risk gates

generateText() and streamText() are single-step by default, ToolLoopAgent defaults to a longer loop, and WorkflowAgent has no maximum step count unless configured. Preserve the observed stop conditions, usage limits, and prepareStep changes to models, tools, instructions, messages, or runtime context; do not copy defaults blindly.
Distinguish local, provider-executed, browser/client, and MCP tools. Preserve where execution and credentials live, input/result schemas, error recovery, cancellation propagation, and side-effect idempotency.
An AI SDK async-generator tool can expose preliminary results before its final output. An ordinary Pydantic AI tool returns once; reproduce consumed intermediate UI states with explicit custom events or record an intentional change.
Complete structured output is validated; partially streamed output may be incomplete, and combining tools with structured output may require another step. Test the caller-visible timing and failure shape.
UIMessage is client-controlled application state, not trusted provider history or dependency context. Validate incoming messages, keep identity and services server-side, and convert only the permitted content to model messages.
Match the installed AI SDK wire contract. The current docs call the SSE-based UI-message wire format the Data Stream Protocol, while older implementations can use line-prefixed frames under a similar name. Request bodies, headers, frames, chunk ordering, tool states, error/abort behavior, and reconnect endpoints are not interchangeable. Configure VercelAIAdapter for the installed SDK version and golden-test the boundary.
AI SDK approval is commonly a two-request conversation; Eve can durably park a session; Pydantic AI can resolve a deferred call inline or in a later run. Persist the complete pending request, bind a decision to validated arguments and call identity, authenticate the approver, and prove the protected effect runs exactly once.
Pydantic AI message history cannot continue past unresolved tool calls. If Eve accepts an unrelated turn while approval remains pending, keep the pending branch separate in application state; do not append an unrelated prompt to that incomplete history.
Eve sessions, turns, steps, replay units, event cursors, background subagents, and NDJSON session streams are one durable protocol. Core message history and Harness StepPersistence do not automatically reproduce it. Retain an application-owned session adapter or mark the difference until restart and replay tests prove the promised behavior.
Eve defineState data is separate from conversation history, and durable memory has its own lifetime and sharing rules. Map each store independently and test session, user, and tenant isolation.
Eve skills can materialize supporting files. Harness Skills loads SKILL.md instructions only; provide required references, assets, or scripts through FileSystem or application tools and test them explicitly.
Eve subagents may be durable child sessions with background result batching and separate streams. Harness SubAgents runs an isolated agent and returns its result through a tool. Use it only when that narrower lifecycle preserves the observed contract; otherwise retain orchestration in the application.
A filesystem or shell policy is not sandbox isolation. Preserve Eve's sandbox, credential-brokering, and network boundaries with a real container, VM, or supported cloud sandbox when untrusted execution is in scope.
Eve channels, schedules, connections/OAuth, its default HTTP API, Workflow SDK persistence backends, Vercel Agent Runs, and deployment integrations are application or platform concerns. Replace and test them deliberately rather than attributing them to Core or Harness.
Preserve provider routing, gateway allow-lists/fallbacks, provider options, retry semantics, telemetry correlation, and evaluation datasets only when the traced path uses them.

Implement and prove one vertical slice

Preserve the supported caller boundary and replace only the agent-owned internals.
Start core-only. Add pydantic_graph, Harness, Pydantic Evals, or a durable runtime only after an observed contract requires it.
Test inputs, outputs, errors, message history, event order, tool arguments/results, step counts, state, and side effects at that boundary. Use deterministic models and fake application services offline; add a focused recording or live test only when provider behavior is the contract.
For approvals, reconnects, durable sessions, background work, or external effects, test interruption and fresh-process restart, stable correlation, authorization, replay, cancellation, and idempotency.
Remove ai, @ai-sdk/*, or eve only after no retained UI, transport, agent, or platform path needs them.

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

Completion

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

Files

ATTRIBUTION.mdAdded by AutoGineer909 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md9.0 KiB
agents/openai.yaml324 B
references/RESEARCH-AND-MAPPING.md12.1 KiB
references/VERIFICATION-AND-CUTOVER.md8.1 KiB

references/RESEARCH-AND-MAPPING.md

Research and concept mapping

Use this reference conditionally after tracing the source path. It is a decision guide, not a requirement to reproduce the entire Vercel AI SDK or Eve platform.

Primary documentation

Inspect installed versions before migrating because AI SDK, Eve, Pydantic AI, and Harness continue to evolve.

Vercel AI SDK: agents, tools, structured output, chatbot, stream protocol, and resume streams.
Eve: documentation and repository. Inspect the installed package and source because its durable protocol is evolving.
Pydantic AI: agents, message history, deferred tools, MCP, durable execution, and Vercel AI integration.
Pydantic AI Harness: overview, skills, subagents, memory, sandbox, and step persistence.

AI SDK and Eve are TypeScript while Pydantic AI is Python. Capture retained transport and storage boundaries with language-neutral fixtures and keep their field names, using Pydantic aliases where needed.

Gate on the installed AI SDK version

Read the matching v5, v6, or v7 migration guide before choosing fixtures. Important boundaries differ:

Source generation	Check before porting
Before v5	Legacy message shapes and line-prefixed stream frames may require an application adapter rather than the current UI path.
v5	`UIMessage.parts`, `ModelMessage`, `stopWhen`, transport-based `useChat`, and start/delta/end stream parts changed the client contract.
v6	`ToolLoopAgent`, async `convertToModelMessages`, current output APIs, and explicit approval states replaced earlier names or lifecycles.
v7	`stepCountIs` became `isStepCount`, `needsApproval` moved to per-call `toolApproval`, `onFinish` became `onEnd`, and usage/tool-call results aggregate across steps; Node and ESM requirements also changed.

Pydantic AI's VercelAIAdapter supports explicit SDK versions 5, 6, and 7. Its default is a compatibility choice, not evidence of the source version; configure it deliberately and test the emitted wire contract.

AI SDK Core and UI ownership map

Observed source behavior	Target owner and likely seam	Focused proof
`generateText()` / `streamText()` and text, steps, usage, or finish reason	Core: `Agent.run()` / `run_stream()` / `run_stream_events()`; Application: result adapter	Assert caller-visible result, exact required trajectory fields, step count, usage, errors, and effects.
`ToolLoopAgent`, `stopWhen`, `prepareStep`	Core: reusable `Agent`, `UsageLimits`, dynamic instructions and tool preparation; Application/Graph: explicit dynamic model or workflow policy	Exercise every observed stop condition and per-step mutation without assuming identical defaults.
`@ai-sdk/workflow` `WorkflowAgent`	Application/durable runtime: workflow state, persistence, approvals, and resume lifecycle; Core durable integration: agent model/tool operations inside a supported workflow	Interrupt and restart at model, tool, approval, and effect boundaries; assert replay, state, correlation, and idempotency.
Local `tool()` with Zod or JSON schema	Core: typed functions, `Tool`, `Tool.from_schema`, function toolsets	Assert advertised schema, call/result IDs, error recovery, timeout, cancellation, approval, and effects.
Async-generator tool with preliminary results	Core/Application: custom events plus final tool result when the client consumes intermediate states; otherwise an intentional change	Assert every consumed preliminary state, final output, order, cancellation, and behavior when the generator fails.
Provider-executed tool	Core/provider: matching provider tool when available; otherwise Gap/Application	Verify who executes it, provider payloads, credentials, result shape, and fallback behavior.
Client-side tool with no server executor	Application/UI: retain browser execution; Core: deferred/external tool call	Prove the server does not execute it and the validated result resumes the correct call.
Dynamic MCP tools	Core: `MCPToolset`; Application: auth and lifecycle	Assert discovery, schemas, name collisions, transport, credentials, errors, and version skew.
`Output.object`, `array`, `choice`, or `json`	Core: Pydantic output type and explicit output mode when transport matters	Assert complete validation, invalid-output behavior, partial-stream expectations, and any extra step after tools.
Tool approval request/response	Core: `requires_approval` or `ApprovalRequiredToolset`; resolve inline with `HandleDeferredToolCalls`, or later with `DeferredToolRequests` and `DeferredToolResults`; Application: policy, auth, persistence, audit, UI	Exercise approve, deny, invalid/replayed decisions, call correlation, and exactly-once effects.
`UIMessage`, `useChat`, and `ChatTransport`	Application: retained TS/React client; Core UI adapter: `VercelAIAdapter`	Golden-test request fields, validation, stream headers/chunks, tool states, errors, and final reconstruction for the installed SDK version.
Persisted UI messages and `ModelMessage` conversion	Application: UI-message store and trust policy; Core: normalized server-side history	Continue in a fresh process and prove client input cannot set trusted instructions, provider metadata, credentials, or ownership.
Resumable chat stream	Application: active-stream/message persistence and reconnect endpoint	Disconnect and reconnect; assert continuation, HTTP no-stream behavior, stable correlation, and no duplicate assistant message or effect.
`onStepFinish`, response `onFinish`, or v7 `onEnd` lifecycle callbacks	Core/Application: hooks or event stream handling; the `on_complete` parameter of `VercelAIAdapter.dispatch_request()` or `run_stream()` for completed-run persistence	Assert firing point, per-step versus terminal behavior, errors, persisted messages, and exactly-once writes.
Provider string, provider instance, Gateway routing or fallback	Core/provider: model/provider configuration; Application: allow-list and policy	Exercise each configured route, fallback order, provider options, and failure shape.
AI SDK subagent implemented as a tool	Core: agent-as-tool; Harness: `SubAgents` only for matching reusable delegation policy	Assert fresh child context, input projection, result projection, usage/cancellation/error propagation, and approval limitation.
OpenTelemetry and provider metadata	Core: instrumentation; optional Logfire; Application: trace and result adapter	Assert trace correlation, privacy policy, required spans, usage, and retained dashboards.

Eve ownership map

Observed Eve behavior	Target owner and likely seam	Focused proof
`instructions.md`, `agent.ts`, and filesystem compilation	Core: explicit `Agent` construction; Application: configuration loader only if runtime discovery is required	Construct every configured agent and assert instruction, model, tool, and environment selection.
`tools/` with `defineTool`	Core: typed tools/toolsets; Application: dependencies and protected services	Assert schema, executor result, error/retry, approval, cancellation, and effects.
`defineWorkflowTool` and durable waits	Application/durable runtime: workflow and wait lifecycle; Core durable integration: model/tool operations within a supported workflow	Kill and restart around the wait; assert correlation, validated resume data, replay, and idempotency.
`skills/` with descriptions, `load_skill`, and materialized files	Harness: `Skills` for `SKILL.md`; Harness/Application: `FileSystem` or explicit tools for other files	Assert discovery, request-scoped loading, instruction injection, and access to every required reference, asset, or script.
Built-in or declared `subagents/`	Harness: `SubAgents` for synchronous isolated delegation; Application/Gap: durable children, background results, and child streams	Assert child history/state isolation, dependency/tool sharing, handback, cancellation, errors, events, and restart.
`defineState` durable session state	Application: separately typed and persisted state	Assert mutation, schema/version handling, fresh-process continuation, concurrency, and non-sharing with children.
Long-lived memory	Harness: `Memory` only for matching model-owned notebook semantics; otherwise Application: retained memory provider	Assert lifetime, namespace, locking, attribution, bounded injection, and sharing rules independently from messages and state.
Session → turn → step durability and step replay	Application/durable runtime: session driver, replay unit, event log; optional Harness: `StepPersistence` only for its narrower documented contract	Interrupt model, tool, and effect boundaries; assert which step re-runs, event identity, ordering, and exactly-once external effects.
Eve HTTP session API, NDJSON stream, event cursor	Application/Gap: compatibility endpoint and durable event store	Golden-test status codes, payloads, framing, cursor semantics, reconnect, retry, cancel, and terminal state. `VercelAIAdapter` does not implement Eve's protocol.
`connections/`, MCP/OpenAPI discovery, app/user OAuth	Core: MCP/toolsets where compatible; Application: connection registry, OAuth, token persistence, tenant policy	Exercise discovery, qualification, auth parking/resume, refresh, revocation, isolation, and errors.
`channels/` and `schedules/`	Application/platform: channel adapters, scheduler, queues, and deployment	Exercise trigger identity, authorization, deduplication, delivery, retry, cancellation, timezone, and failure behavior.
Sandbox adapters and `/workspace` boundary	Harness: a supported real sandbox when it matches; Application: existing sandbox and credential broker	Run containment, network, secret, filesystem, resource, timeout, and cleanup tests in the actual isolation boundary.
Evals and agent-run observability	Evals: `pydantic_evals`; Core: instrumentation; Application: HTTP eval target, sampling, storage, and dashboards	Re-run the same dataset and essential metrics; assert trace/run correlation and retained privacy policy.
Workflow SDK backends, Vercel Sandbox, Cron, Connect, Blob, Gateway, Agent Runs, and deployment	Application/platform	Verify each retained or replacement service at its public boundary; do not claim Core or Harness equivalence.

Do not collapse distinct state

Keep these stores separate unless the source contract proves they are interchangeable:

UI messages restored by the frontend;
provider-facing normalized message history;
Eve per-session structured state;
long-lived memory across sessions;
durable step/session records and event cursors;
model-owned plans or Harness memory notebooks;
application identity, authorization, and tenant configuration.

The same fact appearing in two prompts does not prove equivalent ownership, lifetime, consistency, or restart behavior.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Pydantic

Publisher

Pydantic (Official)

Source

pydantic/skills · skills/migrating-vercel-ai-sdk-and-eve-to-pydantic-ai · commit 98f591c

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

pydantic/skills

AutoGineer is not affiliated with or endorsed by Pydantic.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download migrating-vercel-ai-sdk-and-eve-to-pydantic-ai.zip