エージェントトレースの理解と確認

PendoのPythonまたはTypeScript SDKを使用してAIエージェントを計測すると、会話イベントとともにトレースデータを送信できます。トレースを使用すると、エージェントがリクエストをどのように処理しているか（単に何を回答したかだけでなく、どのようにその応答を生成したか）を詳細に把握できます。

この記事では、トレースとは何か、会話イベントとの違い、そしてPendoでトレースデータを表示する方法について説明します。

トレースとは

トレースとは、AIエージェントが応答を生成するために行ったすべての処理の記録です。会話イベントには入力（訪問者のプロンプト）と出力（エージェントの応答）が記録されますが、トレースにはその間の各ステップ、つまりエージェントが呼び出したツール、使用したモデル、操作が実行された順序、各ステップにかかった時間、エラーが発生した箇所が記録されます。

トレースはスパンで構成されます。各スパンは、エージェントの実行内の単一の操作を表します。たとえば、言語モデルの呼び出し、ツールの実行、または検索ステップです。スパンはネストされており、どの操作が他の操作を開始したかを示すため、任意の応答におけるエージェントの行動を全体的に把握できます。

トレースと会話イベントの比較

会話イベントとトレースデータはどちらもエージェントアナリティクスに表示されますが、それぞれ異なる質問に答えるものです。

エージェントアナリティクスを使用するのに、トレースデータは必要ありません。会話イベントだけでも、ユースケースの検出、問題の特定、会話の確認、大半の概要指標に対応しています。トレースは、エージェントの仕組みについてより詳細な可視性が必要な場合の追加レイヤーとなります。

ユースケース

トレースは次のような場合に役立ちます。

• エージェントが特定の回答をした理由を理解する。
• どのツールやモデルが最も頻繁に呼び出されているかを特定する。
• プロセスのどこでエラーが発生したかを正確に把握することで、エラーや予期しない出力をデバッグできます。
• エージェントのプロセスにおける各ステップのレイテンシーを測定します。
• 変更を加えた後、エージェントの動作が一貫していることを確認する。

前提条件

トレースデータを送信および表示するには：

• エージェントにはPendo PythonまたはTypeScript SDKが導入されている必要があります。セットアップ手順については、「Python SDKをインストールして会話とトレースデータを送信する」と「TypeScript SDKをインストールして会話とトレースデータを送信する」をご覧ください。
• Pendoでエージェントの全会話を有効にする必要があります。
• Pendoで会話データやトレースデータを表示するには、サブスクリプション管理者であるか、AIエージェント管理者ロールが割り当てられている必要があります。

会話トレースを表示する

会話のトレースデータが利用可能な場合、Pendoはエージェントアナリティクスの会話パネルに表示します。PythonおよびTypeScript SDKでは、標準セットアップ時にトレースが自動的に有効になるため、追加の設定は必要ありません。

会話トレースにアクセスする

1. ［プロダクト］>［エージェントアナリティクス］に移動してください。
2. レビューしたいエージェントを選択してください。
3. ［会話］タブを開きます。
4. テーブルから会話を選択してください。
5. 会話パネルで、プロンプトやエージェントの応答の下にある［トレースを表示］アイコンを探してください。これはそのメッセージに対してトレースデータが利用可能であることを示します。選択すると［会話トレース］ビューが開きます。
   

トレースが示す内容

会話のトレースには以下が含まれます。

• スパンツリー。エージェントの応答中に実行されたすべての操作を階層的に表示し、どのステップが他のステップをアクティブにしたかを示します。
• ウォーターフォールのタイムライン。各スパンのタイムラインビューで、開始時期、稼働時間、他の操作との重複状況を示します。
• エラーの検出。エラーが発生したスパンにはフラグが付けられるため、プロセスのどこで失敗したかを正確に特定できます。
• 入力と出力の詳細。各スパンの入力と出力を確認できるため、エージェントの処理を通じてデータの流れを追うことができます。

注：会話トレースは、Python SDKまたはTypeScript SDKで計測されたメッセージでのみ利用できます。クライアント側とサーバー側のメソッドは、トレースデータを送信しません。

トレースの種類

すべてのトレースイベントには、記録されている特定の操作を分類するagentTraceTypeフィールドが含まれています。このフィールドを使って、トレースビューの各スパンが何を表しているかを理解してください。