本文へ移動
Telemetry
統合ガイド

ピダンティック AI エージェント Telemetry

Pydantic AI の実行結果、検証された出力、再試行、ツールのアクティビティ、レイテンシ、使用状況、製品の受け入れ状況を、安全な構造化イベントで測定します。

レビュー者 Telemetry 製品チーム に . インストルメンテーション契約、プライバシー境界、および実装ガイダンス. 基準と所有権を確認する

API キーを取得するスニペットを表示
役に立つ
  • ピダンティックな AI の信頼性
  • 検証済み出力のモニタリング
  • エージェントの品質とコストの分析
実装の証拠

Pydantic AI Agent Telemetry: 境界から検証された行まで

制御されたアプリケーション境界で Pydantic AI Agent Telemetry を使用し、イベント コントラクトを小さく保ち、集約ビューを構築する前に既知の結果を検証します。

  1. 1

    結果を選択してください

    ピダンティックな AI の信頼性

  2. 2

    契約を定義する

    run_id、ワークフロー、agent_name、プロバイダー、model_alias、および prompt_version

  3. 3

    境界を計測する

    Agent.run をアプリケーション境界でラップし、1 つのターミナル結果を出力します。詳細なモデルとツールのトレースには、複製する代わりに Pydantic AI インストルメンテーションを使用します。

  4. 4

    証拠を検証する

    Exercise a known fixture, then inspect agent_run_completed for one correctly typed terminal row.

始める前に

前提条件と境界

  • pydantic-ai と telemetry-sh が信頼できる Python プロセスで初期化されました
  • 安定したワークフロー名とアプリケーション所有の実行識別子
  • プロンプト、出力、依存関係オブジェクト、ツール引数、モデル メッセージを除外するホワイトリスト

配信設定

サーバー側のインストールと初期化

サーバー側キーを使用して、プロセスごとに 1 回、同期コードの場合は Telemetry を、非同期コードの場合は TelemetryAsync を初期化します。 ブラウザ バンドル、クライアントに表示される環境変数、ソース管理、ログ、および例外メッセージに取り込み資格情報が含まれないようにします。

pydanticai-インストール

pipのインストール

bash
python -m pip install telemetry-sh
  1. 1制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
  2. 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
  3. 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。

スニペット

1 つの構造化されたイベントから始める

ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。

pydanticai

Pydantic AI Agent Telemetryイベント

python
from time import perf_counter

async def run_support_agent(prompt: str, run_id: str):
    started_at = perf_counter()
    status = "success"
    error_type = None

    try:
        result = await support_agent.run(prompt)
        return result.output
    except Exception as error:
        status = "failed"
        error_type = classify_agent_error(error)
        raise
    finally:
        await telemetry.log("agent_run_completed", {
            "run_id": run_id,
            "workflow": "support_resolution",
            "agent_name": "support_agent",
            "status": status,
            "error_type": error_type,
            "duration_ms": round((perf_counter() - started_at) * 1000),
            "release": APP_RELEASE,
        })

イベント契約

run_id、ワークフロー、agent_name、プロバイダー、model_alias、および prompt_version

ステータス、duration_ms、retry_count、tool_call_count、承認時の使用量合計

output_validated、承認済み、human_handoff、error_type、リリース、および環境

実装のチェックポイント

チェックポイント 1

Agent.run をアプリケーション境界でラップし、1 つのターミナル結果を出力します。詳細なモデルとツールのトレースには、複製する代わりに Pydantic AI インストルメンテーションを使用します。

チェックポイント 2

出力検証の再試行とプロバイダーの再試行が異なるエンジニアリング上の決定につながる場合は、それらを別個のカテゴリとして扱います。

チェックポイント 3

RunResult、メッセージ、依存関係、ツール引数、または検証された出力を Telemetry イベントにシリアル化しないでください。

検証

イベントが到着したことを証明する

既知の成功例と失敗例を実行した後、これを実行します。最終的なイベント コントラクトがスニペットと異なる場合は、フォールバック テーブル名を置き換えます。

pydanticai-検証

Pydantic AI Agent Telemetry 検証クエリ

sql
SELECT *
FROM agent_run_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
論理結果ごとに 1 つのターミナル行を、予想されるステータス、識別子、単位、および UTC 時刻とともに確認します。
推論されたスキーマを検査し、再試行によってフィールド タイプが変更されたり、新しい論理イベント ID が生成されたりしないことを確認します。
保存されたフィールドで認証情報、生のペイロード、プロンプト、プライベート コンテンツ、および無制限のエラー メッセージを検索します。
ダッシュボードを完了として扱う前に、プロバイダーのタイムアウト、取り込みの拒否、およびプロセスのシャットダウンを実行します。

実装の参考資料

新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。

CI でのインストルメンテーション テスト機密データの管理エージェントループ検出 SQLピダンティック AI エージェントピダンティックな AI テスト

生産境界

結果イベントを小さく、回復可能なものに保つ

このパターンが提供するのは、

  • 上流のワークフローの横にある、制限付きの SQL 対応の結果。
  • ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
  • 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。

このパターンでは提供されません

  • OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
  • ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
  • 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。
配信と冪等性バッチ処理とシャットダウン取り込みのトラブルシューティング

イベントスキーマの開始点

このワークフローのイベント コントラクト

クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。

AIの運用10 フィールド

llm_request_completed

1 つの完了したモデルプロバイダーリクエスト。

契約書の検査
AIエージェントの運用10 フィールド

ai_agent_run_completed

論理エージェントの実行ごとに 1 つの最終結果。

契約書の検査
AIの運用11 フィールド

agent_tool_call_completed

エージェントの実行内で 1 回の完了したツール呼び出し試行。

契約書の検査

関連製品の機能

このワークフローを続行します AIエージェントの監視

レビュー可能な SQL を使用して、エージェントの実行、ツールの使用、モデルのコスト、品質、製品の結果を結び付けます。

探索 AIエージェントの監視顧客の証拠を確認する

関連する SQL レシピ

SQL で次の質問に答えてください

このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。

すべてのレシピを参照する
AIとLLM中級者

AI エージェントのタスクの成功と人間による引き継ぎを測定する

どのエージェントのワークフローが正常に終了し、受け入れられた結果をもたらしますか?

レシピを開く
構造化イベント中級者

ネストされた AI ツール呼び出しイベントのクエリ

最も失敗した呼び出しに関連する AI ツールと引数はどれですか?

レシピを開く
AIとLLM中級者

繰り返しを検出する AI エージェント ツール Loops

どのエージェントの実行が繰り返しのツール ループに陥っているように見えますか?

レシピを開く
AIとLLM初心者

機能とモデルごとに LLM コストを計算する

LLM の支出を促進しているのはどの製品機能とモデルですか?

レシピを開く
AIとLLM中級者

プロンプト バージョンごとに AI 品質の低下を見つける

新しいプロンプト バージョンでは、人間による引き継ぎを増やすことなく品質が向上しましたか?

レシピを開く
AIとLLM中級者

1 ドルあたりの受け入れられた AI 出力を測定する

どのモデルと機能の組み合わせが、1 ドルあたり最も受け入れられる出力を生成しますか?

レシピを開く
完全なコレクションAIとLLM SQL構造化イベント SQL

実装ファミリーごとに参照する

関連する統合パターンを比較する

AI エージェントと LLM Telemetry の統合Python Telemetry 統合

この統合と組み合わせるテンプレート

AI エージェント可観測性テンプレート

構造化された SQL 対応イベントを使用して、エージェントの実行、ツール呼び出し、再試行、モデルの遅延、エラー、受け入れられた結果を追跡します。

テンプレートを開く

AI エージェントのセキュリティ監査テンプレート

ツール認可の決定、ポリシーのバージョン、人間による承認、およびプライバシーに配慮した構造化イベントによる最終結果を計測します。

テンプレートを開く

LLM コスト トラッカー

機能、ユーザー、アカウントごとにモデルの支出、トークン使用量、レイテンシー、失敗率、および価値シグナルを測定します。

テンプレートを開く

さらなる統合

OpenAI エージェント Telemetry

OpenAI エージェントの実行、ツール呼び出し、モデルの使用状況、レイテンシー、コスト、および構造化イベントによる最終結果をログに記録します。

オープンガイド

クロード エージェント SDK Telemetry

プロンプトやツールのペイロードを保存せずに、クロード エージェント SDK の実行結果、期間、ツール アクティビティ、ターン、コスト、および承認された製品シグナルを追跡します。

オープンガイド

LangGraph エージェントの可観測性

LangGraph の実行結果、ノードとツールの障害、再試行、チェックポイント、人間によるハンドオフ、遅延、レビューされたタスクの品質を測定します。

オープンガイド