logfire-gateway

Pydantic AI Gateway でアプリケーションを設定する

Claude Code／Codex 自体の監視やルーティングには、代わりに coding-agent setup を使用してください。この アプリケーションのワークフローは、コーディングセッションの記録やプロバイダーの設定とは分けてください。

ユーザーが確認済みのプロジェクト、リージョン、プロバイダー、既存の認証情報の 仕組みを維持してください。既存のアプリケーション用 Gateway キーに、CLI でのログインや SDK 書き込み トークンは必要ありません。CLI でキーを作成するには、 CLI Gateway credential procedure に従ってください。 CLI を利用できない場合は、UI の Gateway Connect フローを使用してください。

このスキルは、モデルのトラフィック、プロバイダーのルーティング、Gateway の認証情報に使用します。 logfire-instrumentation とは別のものです。Logfire 書き込みトークンはテレメトリを送信し、 Gateway キーはモデルリクエストを認証します。一方を他方の代わりに使用しないでください。コーディングエージェントのプロバイダー、テレメトリ、MCP 連携は設定しないでください。

準備済みのセットアップ引き継ぎ情報に、正確なプロジェクトと認証情報がすでに記載されている場合があります。 認証を繰り返したり別のプロジェクトを選択したりせず、その情報を再利用してください。

1. アプリケーションを特定する

ファイルを変更する前に、リポジトリを調査して、既存のモデル クライアント、モデル、プロバイダー、環境ローダー、実行可能なエントリーポイントを特定してください。リクエストでアプリケーションが指定されている場合、またはリポジトリに明確な推論 クライアントが含まれている場合は、そのアプリケーションを Gateway 経由で接続してください。ユーザーが変更を求めない限り、プロバイダープロトコルとモデルは維持してください。

推論アプリケーションがない場合や対象が曖昧な場合は、どの アプリケーションを接続するかユーザーに尋ねてください。新しいアプリケーションをスキャフォールディングする前に、その目的を確認してください。

Gateway のセットアップリクエストは、選択したアプリケーションのモデル呼び出しを Gateway 経由でルーティングすることを許可します。通常の Logfire 計装は、その選択を意味しません。

このセットアップは現在のエージェントで続けてください。準備済みのウィザード引き継ぎ情報では、アカウントとプロジェクトの選択がすでに完了しています。ウィザードを再度呼び出したり、別のセットアップエージェントを起動したりしないでください。既存のモデルクライアント、プロバイダー抽象化、依存関係のバージョン、環境に関する規約を維持してください。

2. 認証情報を公開せずに扱う

リポジトリのシークレット機構で提供されている既存の Gateway 認証情報を再利用してください。それ以外の場合は、UI の Connect フローまたはCLI 認証情報の手順を使用して、プロジェクトスコープの Gateway キーを取得してください。既存の Gateway キーを設定するためだけに、テレメトリー書き込みトークンを作成しないでください。記録されるターミナルやエージェントのメッセージに、一度しか表示されないシークレットを決して出力しないでください。選択した SDK または Connect スニペットが読み取る環境変数を使って保存してください。Pydantic AI の場合は PYDANTIC_AI_GATEWAY_API_KEY です。その他のクライアントでは、アプリケーションの既存の変数をそのまま使用するか、LOGFIRE_GATEWAY_API_KEY を使用して、クライアントの API キーオプションに明示的に読み込んでください。変数を設定しただけでは、任意のクライアントがその変数を読み込むようにはなりません。

無関係な値はそのまま保持してください。ローカルの環境ファイルの場合は、Git で無視される通常ファイルで、ユーザーのみがアクセスできる権限が設定されていることを確認し、既存の代入をちょうど 1 つ置き換えるか、代入を 1 つ追加して、ファイルをアトミックに書き込んでください。シークレットを含むファイルやキーを、ソース管理にステージングまたはコミットしないでください。代入を重複して追加しないでください。既存のシークレット機構を安全に更新できない場合は、通常使用しているシークレットマネージャーを通じてキーを登録するようユーザーに依頼してください。

ダウンロードした Connect 認証情報は、ダウンロードしたファイルを表示したり読み込んだりせずに、同じシークレット機構で使用できます。エージェントのメッセージ、ソースコード、ログ、テスト、スナップショットにキーを決して記載しないでください。

選択した SDK が想定する環境変数を使用してください。キーをブラウザーコードやクライアント側のバンドルに含めないでください。キーを作成しても、Gateway が有効になるわけではなく、プロバイダーの課金が設定されるわけでも、ルーティングエンドポイントが選択されるわけでもありません。Gateway が無効である、または権限が不足しているために公開 API が作成を拒否した場合は、その具体的な前提条件を説明してください。OAuth スコープが不足している場合は、必要な権限を付与するための再同意が必要です。プロバイダーの有効化や課金の設定が必要な場合は、Gateway の設定が必要です。ユーザーの同意なしに有料プロバイダーへのアクセスを有効にしないでください。キーの作成に成功した場合はそのキーを再利用し、設定の再試行時に別のキーを新たに作成しないでください。

3. 検出したアプリケーションを設定する

既存のクライアントと依存関係のバージョンを優先してください。アプリケーションの現在のプロバイダー抽象化を維持するために、変更は最小限にしてください。

Pydantic AI

選択したプロバイダーとモデルが判明している場合は、Gateway モデル形式を使用してください。

from pydantic_ai import Agent

# Set PYDANTIC_AI_GATEWAY_API_KEY and PYDANTIC_AI_GATEWAY_BASE_URL from Connect.
agent = Agent('gateway/openai:gpt-5.2')

選択したリージョンまたはセルフホスト型デプロイメント向けに Connect から提供された Gateway のルート URL を、API キーとともに PYDANTIC_AI_GATEWAY_BASE_URL に設定してください。他のクライアントのスニペットからコピーしたプロバイダー固有のエンドポイントではなく、Pydantic AI スニペットのルート URL を使用してください。明示的に設定されている URL が一致する場合はそのまま保持してください。SDK によるリージョンの推測やデフォルト値を使って、ユーザーの接続先を選択しないでください。

通常使用する認証情報は PYDANTIC_AI_GATEWAY_API_KEY です。アプリケーションで明示的なキーまたはカスタムルートが必要な場合は、インストール済みの Pydantic AI バージョンの gateway_provider() を使用し、Connect の引き継ぎ情報にあるプロバイダータイプとルートをそのまま保持してください。モデル名からプロバイダーのスラッグを推測しないでください。

OpenAI 互換クライアント

Connect から提供された正確な Gateway のベース URL とルートを使用するか、引き継ぎ情報と既存のプロバイダープロトコルに基づいて、ドキュメントに記載されたリージョナルルートを導き出してください。必要に応じて Gateway ドキュメントにあるプロバイダー固有の例を確認してください。クライアントの既存の API 形式を維持し、通常の環境変数読み込み機構を通じて、選択したアプリケーションの環境変数からクライアントの API キーオプションにキーを読み込んでください。引き継ぎ情報に URL がすでに記載されている場合、リージョナル URL をハードコードしないでください。セルフホスト型のオリジンはホストされたリージョンではありません。確認済みの Gateway リソースと設定済みのルートを使用するか、ユーザーに確認してください。ドキュメントにプロバイダーのパスが記載されているだけでは、その組織でそのルートが有効であることの証明にはなりません。

Anthropic、Google、その他のネイティブクライアント

選択したリージョンに対応する、Connect のプロバイダー固有の Gateway スニペット、またはリンク先の公開 Gateway ドキュメントを使用してください。ネイティブプロバイダーのパスは相互に置き換えられません。Anthropic、OpenAI Responses、Google、Bedrock、チャット補完の各ルートでは、URL とリクエストの形式が異なります。サンプルをコンパイルできるようにするためだけに、ネイティブリクエストを別のプロトコルに変換しないでください。

4. 実際のリクエストを1件検証する

ライブリクエストでは、プロンプトが Gateway 経由で選択したプロバイダーに送信され、使用料金が発生する可能性があることを説明してください。アプリケーション、顧客、秘密情報のデータを含まない、小さな合成ペイロードを1つ使用してください。選択したルートの設定とテストを明示的に依頼された場合は、この範囲を限定した確認が許可されています。それ以外の場合は、送信前に承認を求めてください。有料アクセスを有効化したり、本番ワークロードをテストとして実行したりしないでください。

選択したルートを通じて、そのリクエストを実行してください。レスポンスとアプリケーションの通常のエラー処理を確認してください。インポート、設定の解析、またはプロセスの終了が成功しただけでは、リクエストが Gateway を使用した証拠にはなりません。

プロジェクトに読み取り可能な Logfire ログインがある場合は、該当するプロジェクトで新しい Gateway リクエストを検索するか、Gateway アクティビティ画面を開いてください。読み取りには、送信専用 SDK 書き込みトークンを使用しないでください。読み取りによる検証ができない場合は、リクエストレスポンスを検証済みとして報告し、Logfire 側への到達は未検証と明記してください。

プロジェクトのフォーマッター、型チェッカー、ビルド、対象を絞ったテストを実行してください。プロバイダー、ルート、モデル、エンドポイントの種類、認証情報の変数、リクエスト結果、Logfire 側で未検証の確認事項を正確に報告してください。このセッションで Gateway リクエストを確認していない場合は、確認したと主張しないでください。

セットアップ後、該当するプロジェクトまたは Gateway の画面へのリンクを返してください。プロバイダーの有効化やその他の前提条件が原因でリクエストを実行できない場合は、その阻害要因を報告し、アプリケーションでの推論は未検証と明記してください。

参考資料

• Pydantic AI Gateway ドキュメント