migrating-pi-to-pydantic-ai

Pi から Pydantic AI への移行

Pi の TypeScript API ではなく、観察可能な動作を維持してください。最小限の完全な呼び出し経路を移行し、製品／ホストのインフラストラクチャはアプリケーション側に残してください。

移行先を選ぶ前にソースを追跡する

1. リポジトリの指示、package.json、Pi の設定、テスト、拡張機能／パッケージのマニフェスト、ランタイムのエントリーポイントを読みます。インストールされている Pi、Pydantic AI、Harness のバージョンを記録します。
2. Pi CLI、RPC 境界、または createAgentSession().prompt() から、リソースの検出、システム指示、ツール、拡張機能、モデルリクエスト、メッセージ、圧縮／再試行、イベント、セッションエントリー、UI／RPC 出力、副作用に至るまで、実際のリクエストを1つ追跡します。焦点を絞ったベースラインまたは特性テストを確立します。
3. 有効な拡張機能ファクトリーとパッケージリソースをすべて一覧化します。各 pi.on(...)、registerTool、registerCommand、プロバイダー登録、レンダラー／UI への寄与、スキル、プロンプト、永続化されたエントリーについて、発火タイミング、信頼できる入力、変更内容、出力、状態の所有者、呼び出し元から見える効果を記録します。
4. 次の契約がある場合は、それぞれを分けて整理します。
   • モデルメッセージ、追記専用のセッションエントリー／ツリーブランチ、圧縮サマリー、拡張機能の状態。
   • モデルが選択したツール入力、信頼できるホストコンテキスト、プロジェクトの信頼性、承認、認可、OS 分離。
   • トークン差分、ツールのライフサイクル、Pi 拡張機能イベント、機能イベント、RPC イベント、ターミナルへの描画。
   • エージェントループの動作、CLI／TUI ホストの動作、プロバイダーのトランスポート、パッケージ配布、外部への副作用。
5. 観察した各契約、その所有者、意味上の違い、実行可能な証拠を記録します。インストールされていても有効ではない Pi パッケージ機能は、移行の対象ではありません。

検出された機能については、調査と概念の対応付けを参照してください。実装前に検証と切り替えを読んでください。

拡張機能を機能候補として扱う

Pi の拡張機能は、Pydantic AI の機能に最も近いソース概念ですが、範囲はより広いものです。拡張機能は、エージェントの動作に加えて、ターミナル UI、コマンド、プロバイダー登録、リソース検出、ホストのライフサイクルを組み合わせることがあります。拡張機能ファイルではなく、役割を移植してください。

1. ツール、指示、モデル設定、履歴／イベント処理、ガードレール、エージェントループのフックなど、再利用可能なモデル向けの動作は、ライフサイクルが一致する既存の Core または Harness の機能に対応付けます。
2. 関連する指示とツールはコアの Capability にまとめます。ライフサイクルフック、適応型モデル／設定、ネイティブツール、型付き機能イベントを必要とする再利用可能な動作に限り、AbstractCapability をサブクラス化します。
3. CLI コマンド、フラグ、キーボードショートカット、TUI レンダラー／ダイアログ、セッション選択、プロジェクトの信頼性、パッケージのインストール、プロバイダーの認証情報設定は、Python アプリケーションまたはインターフェースアダプターに残します。Pi の拡張機能が所有しているという理由だけで、これらがエージェント機能になるわけではありません。
4. 混在する拡張機能は、その境界で分割します。権限拡張機能は ToolGuardrail または承認機能と、アプリケーションが所有する承認 UI に分けられる場合があります。コーディングパッケージは Coder とホスト設定に分けられる場合があります。プロバイダー拡張機能は、モデル／プロバイダーとの統合として残します。
5. 順序が重要であることを証拠が示す場合に限り、その順序を維持します。Pi のハンドラー読み込み順と Pydantic AI の機能／フックの順序は、異なる契約です。

最小の移行先を選ぶ

• コア： エージェントループ、型付き依存関係、ツール／ツールセット、出力、正規化されたメッセージ、機能／フック、ストリーミング、承認、使用量制限、計装、MCP、プロバイダー／モデル統合には、pydantic_ai.Agent を使用します。
• ハーネス： Pi の標準的なコーディングツールのみを対象とする場合は、その正確な構成が要件に合うときに限り、Coder を使用します。実際に確認された動作に応じて、FileSystem、Shell、Skills、Planning、SubAgents、ガードレール、コンパクション、ツール出力制限、ステップの永続化など、目的を絞った機能を追加します。
• アプリケーション／インターフェース： CLI／TUI／RPC、認証、プロジェクトの信頼設定、設定、プロバイダーへのログイン／カタログ、セッションの閲覧、パッケージ管理、デプロイ、トランスポートは、意図をもって維持または置き換えます。
• グラフ： 決定論的なワークフローには通常の非同期 Python または pydantic_graph を使用し、プロンプトやサブエージェントには実装しないでください。
• ギャップ： 対応する公開シームがない動作を明示し、その影響を説明したうえで、範囲を限定したアダプターをテストします。同等性を主張するためだけに、Pi の拡張バスや JSONL 形式を複製しないでください。

通常の組み込み移行では、再利用可能な Agent、Coder またはより小さな機能の組み合わせ、型付き依存関係に格納したアプリケーションサービス、アプリケーションが所有するメッセージ／セッションストア、既存の RPC または UI 境界に置く薄いアダプターを使用します。

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

• ctx、プロジェクトの信頼設定、認証情報、セッションマネージャー、サービスハンドルは、信頼されたホストコンテキストです。同等のものは型付き依存関係またはアプリケーションサービスに格納し、モデルが選択するツール引数には含めないでください。
• Pi のセッション JSONL は、モデルコンテキスト以外の情報も含む、追記専用の分岐可能なホストログです。result.all_messages() が保持するのはモデル履歴であり、ツリーのナビゲーション、ラベル、拡張エントリー、コンパクション記録、モデルの変更、キュー、破棄された分岐は保持しません。変換、互換ストア、または新規スタートのいずれを選ぶか決め、テストしてください。
• Pi のコンパクション、コンテキストの割り込み、ステアリング／フォローアップキュー、再試行、分岐サマリーには、それぞれ固有のタイミングがあります。コア／ハーネスの対応するシームを個別に選び、順序をテストしてください。一般的なメッセージ履歴や要約で自動的に同等になるわけではありません。
• tool_call の権限ゲートは、作用に応じて対応付けます。検証／ブロック／秘匿にはガードレールを、承認を待つ必要があるアクションには遅延ツールを使用します。ID、認可、UI、監査、永続化、冪等性はアプリケーションで管理してください。
• Pi の拡張機能は、ホスト権限を持つ任意の TypeScript を実行します。Pydantic AI の機能もアプリケーションコードを実行します。どちらもサンドボックスではありません。信頼されていないコマンドやコードには、OS／コンテナー／クラウドの隔離境界を使用してください。
• ハーネスの Skills は、設定された SKILL.md の指示を必要に応じて読み込みますが、Pi の探索ルート、リソースファイル、スクリプト、再読み込み、パッケージインストール、動作に関するフロントマターは再現しません。実際に確認されたものは個別に維持してください。
• SubAgents は、モデルが指示する隔離タスクにのみ使用してください。決定論的なオーケストレーションや、Pi 固有のサブプロセス／tmux／パッケージの意味論はアプリケーションコードに残してください。
• 動的なツール有効化をコアの ToolSearch または必要に応じた機能に対応付けるのは、読み込みのタイミング、スキーマ、プロンプト／キャッシュの変更、プロバイダーのフォールバック動作をテストした後に限ります。
• Pydantic AI の実行イベントや機能イベントは、Pi の拡張イベントバス、RPC プロトコル、TUI のレンダリングライフサイクルを再現しません。利用側が使う安定したフィールドのみをアダプトしてください。
• Pi のプロバイダー拡張機能やペイロードフックは、認証、カタログ、ワイヤーペイロード、ヘッダー、ストリーミングを変更する場合があります。Pydantic AI のモデル／プロバイダー層またはアプリケーションのトランスポート層に実装し、プロバイダーのコントラクトテストを実行してください。汎用的な機能に隠さないでください。

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

1. サポート対象の CLI、RPC、SDK、ジョブ、または UI の境界を維持し、エージェントが所有する内部実装のみを置き換えます。
2. コアと最小限のコーディング機能から始めます。トレースされた契約で必要とされるまでは、Harness のより広範な動作を追加しません。
3. ソースを拡張するたびに、機能の動作、アプリケーション／インターフェースの動作、維持する統合、未対応部分を分けて記録します。それぞれの側を実際の境界を通じてテストします。
4. RPC／イベントおよび永続化されたレコードには、言語に依存しないフィクスチャを使用します。ツールの引数／結果、エラー、イベントの順序、セッションの継続、UI の判断、副作用をテストします。オフラインでは決定論的なモデルを使用し、プロバイダーの動作を検証する場合に限り、対象を絞った記録済み／ライブプロバイダーのテストを追加します。
5. 維持する経路で不要になってから、Pi のパッケージ、設定、Node ランタイム、または拡張アダプターを削除します。

重大な意味上の変更を実装する前に説明します。Pi での動作、移行先の動作、呼び出し元への影響、推奨する選択肢、残るリスクを示します。

完了

検証と切り替えに記載されている完了基準を適用します。フェイク、記録、ライブプロバイダー、ターミナル、再起動、サンドボックスに関するエビデンスには、それぞれ正確なラベルを付けます。