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: ファイルシステムで定義されたエージェント、永続セッション、スキル、サブエージェント、状態、接続、チャネル、スケジュール、サンドボックス
   • アプリケーション／プラットフォーム: 認証、認可、ストレージ、キュー、デプロイ、認証情報、製品 UI、Vercel のホステッドサービス
4. 各契約、その所有者、セマンティクスの違い、実行可能な証拠を記録します。使用されていない機能は移行の対象ではありません。

検出されたソース機能については、調査と概念のマッピングを参照してください。実装前に検証と切り替えを確認してください。

最小限の移行先を選ぶ

• Core: エージェントループ、型付き依存関係、ツール、出力、メッセージ、ストリーミング、MCP クライアント、承認、使用量制限、計装、永続ランタイムとの統合には pydantic_ai.Agent を使用します。
• Graph: 明示的な型付きノード、分岐、合流が引き続き有用な場合に限り pydantic_graph を使用します。単純で固定的な制御フローには、通常の非同期 Python を使用します。
• Harness: Agent Skills、モデル主導のサブエージェント、計画、メモリノートブック、コーディングツール、ガードレール、ステップの永続化など、観察された再利用可能なポリシーに限り、別途 pydantic-ai-harness を追加します。Harness の機能はコアエージェントループを通じて組み合わせられます。Harness は Eve 互換のランタイムではありません。
• 評価: 観察されたデータセット、ケース、評価器には、別パッケージの pydantic-evals を追加します。
• アプリケーション: UI、HTTP トランスポート、認証、永続化、再接続状態、スケジューラー、デプロイ、テナントポリシー、ホステッドサービスは、依頼された対象範囲に置き換えが含まれない限り維持します。
• ギャップ: サポートされている公開インターフェースで維持できない動作を明記し、その影響を説明したうえで、範囲を限定したアダプターをテストします。違いを隠すためだけに AI SDK や Eve のオブジェクトモデルを再現してはいけません。

通常の AI SDK 移行では、既存の呼び出し元の背後に再利用可能な Agent を配置します。@ai-sdk/workflow は、通常のエージェントループではなく、永続ランタイムの移行として扱います。TypeScript または React のクライアントが AI SDK UI を使用している場合は、そのまま維持し、インストール済みバージョンの正確なプロトコルを VercelAIAdapter で提供してください。UI を不必要に移行してはいけません。ソースがプロセス内の TypeScript 呼び出しのみの場合は、同じ対象範囲内でその最も近い呼び出し元を移行するか、新たなアプリケーション所有のサービス境界を明示的に合意してください。

通常の Eve 移行では、コアエージェントに、観察された動作に合致する Harness 機能のみを加えます。置き換えが証明されるまでは、Eve の永続セッションドライバー、製品エンドポイント、スケジュール、チャネル、認証、ホステッドサービスをアプリケーション内に維持してください。

高リスクのゲートを適用する

• generateText() と streamText() はデフォルトで単一ステップですが、ToolLoopAgent はデフォルトでより長いループを実行し、WorkflowAgent は設定しない限り最大ステップ数がありません。実際に確認された停止条件、使用量の上限、モデル、ツール、指示、メッセージ、ランタイムコンテキストに対する prepareStep の変更を保持してください。デフォルトをそのまま適用しないでください。
• ローカル、プロバイダー側で実行されるもの、ブラウザー／クライアント、MCP のツールを区別してください。実行場所と認証情報の保管場所、入力／結果スキーマ、エラーからの復旧、キャンセルの伝播、副作用の冪等性を保持してください。
• AI SDK の非同期ジェネレーターツールは、最終出力の前に予備的な結果を公開できます。通常の Pydantic AI ツールは一度だけ結果を返します。消費されていた中間 UI 状態は、明示的なカスタムイベントで再現するか、意図的な変更として記録してください。
• 構造化出力は完全な状態で検証されます。ストリーミング中の部分出力は不完全な可能性があり、ツールと構造化出力の併用には追加のステップが必要な場合があります。呼び出し元から見たタイミングと失敗時の形式をテストしてください。
• UIMessage はクライアントが制御するアプリケーション状態であり、信頼できるプロバイダー履歴や依存コンテキストではありません。受信メッセージを検証し、ID とサービスはサーバー側に保持し、許可されたコンテンツのみをモデルメッセージに変換してください。
• インストール済みの AI SDK のワイヤー仕様に合わせてください。現在のドキュメントでは、SSE ベースの UI メッセージワイヤー形式を Data Stream Protocol と呼んでいますが、古い実装では、似た名称で行頭にプレフィックスを付けたフレームを使用することがあります。リクエスト本文、ヘッダー、フレーム、チャンクの順序、ツールの状態、エラー／中断時の動作、再接続エンドポイントは互換性がありません。インストール済みの SDK バージョンに合わせて VercelAIAdapter を設定し、境界をゴールデンテストしてください。
• AI SDK の承認は通常、2 回のリクエストにわたる会話です。Eve はセッションを永続的に保留でき、Pydantic AI は遅延された呼び出しをその場で、または後続の実行で解決できます。保留中のリクエスト全体を永続化し、検証済みの引数と呼び出し ID に判断を紐付け、承認者を認証し、保護対象の処理が厳密に 1 回だけ実行されることを証明してください。
• Pydantic AI のメッセージ履歴は、未解決のツール呼び出しがある状態では継続できません。承認が保留中のまま Eve が無関係なターンを受け付ける場合は、保留中の分岐をアプリケーション状態内で分離してください。不完全な履歴に無関係なプロンプトを追加しないでください。
• Eve のセッション、ターン、ステップ、リプレイ単位、イベントカーソル、バックグラウンドのサブエージェント、NDJSON セッションストリームは、ひとつの永続化プロトコルです。Core のメッセージ履歴と Harness の StepPersistence だけでは、これらを自動的に再現できません。アプリケーションが所有するセッションアダプターを維持するか、再起動とリプレイのテストで約束した動作が確認されるまでは差異として明記してください。
• Eve の defineState データは会話履歴とは別であり、永続メモリには独自の存続期間と共有ルールがあります。各ストアを個別に対応付け、セッション、ユーザー、テナント間の分離をテストしてください。
• Eve のスキルは補助ファイルを展開する場合があります。Harness の Skills が読み込むのは SKILL.md の指示のみです。必要な参照資料、アセット、スクリプトは FileSystem またはアプリケーションのツールを介して提供し、明示的にテストしてください。
• Eve のサブエージェントは、バックグラウンドでの結果のバッチ処理と個別のストリームを備えた、永続的な子セッションの場合があります。Harness の SubAgents は分離されたエージェントを実行し、その結果をツール経由で返します。このより限定的なライフサイクルで確認済みの契約を維持できる場合に限り、SubAgents を使用してください。それ以外の場合は、アプリケーション内でオーケストレーションを維持してください。
• ファイルシステムやシェルのポリシーは、サンドボックスによる分離ではありません。信頼できない実行を扱う場合は、実際のコンテナー、VM、またはサポートされているクラウドサンドボックスを使用して、Eve のサンドボックス、認証情報の仲介、ネットワーク境界を維持してください。
• Eve のチャネル、スケジュール、接続／OAuth、デフォルトの HTTP API、Workflow SDK の永続化バックエンド、Vercel Agent Runs、デプロイ連携は、アプリケーションまたはプラットフォームに関するものです。意図的に置き換えてテストし、Core や Harness の機能だと誤認させないでください。
• トレースされた経路で使用されている場合に限り、プロバイダーのルーティング、ゲートウェイの許可リスト／フォールバック、プロバイダーオプション、リトライのセマンティクス、テレメトリーの相関付け、評価データセットを保持してください。

垂直スライスを1つ実装し、実証する

1. サポート対象の呼び出し元との境界を維持し、エージェントが所有する内部実装のみを置き換えます。
2. コアのみから始めます。観測された契約上の要件が生じた場合に限り、pydantic_graph、Harness、Pydantic Evals、または永続ランタイムを追加します。
3. その境界で、入力、出力、エラー、メッセージ履歴、イベント順序、ツールの引数と結果、ステップ数、状態、副作用をテストします。オフラインでは決定論的なモデルとアプリケーションサービスのフェイクを使い、プロバイダーの動作が契約の一部である場合に限り、対象を絞った記録テストまたはライブテストを追加します。
4. 承認、再接続、永続セッション、バックグラウンド処理、または外部への副作用がある場合は、中断と新しいプロセスでの再起動、安定した相関関係、認可、再生、キャンセル、冪等性をテストします。
5. 保持する UI、トランスポート、エージェント、またはプラットフォームの経路で不要になった後にのみ、ai、@ai-sdk/*、または eve を削除します。

重大なセマンティクスの変更を行う場合は、実装前に説明します。変更元の動作、変更先の動作、呼び出し元への影響、推奨する選択肢、残るリスクを明示してください。

完了

検証と切り替えに記載された完了基準を適用します。フェイク、記録、ライブプロバイダー、実際のサンドボックスから得た証拠を正確に区別して示してください。