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

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またはTypeScript SDKを介して送信された会話でのみ利用可能です。クライアント側またはサーバー側の方法で取得された会話には、トレースデータは含まれません。

トレースの種類

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