エージェントのトレース

トレースについて

トレースは、エージェントが実行中に行ったすべての動作 (実行ステップ、処理されたデータ、決定、生成された結果など) の詳細な記録です。各トレースは、タイムスタンプ、エラー、入力/出力、コンテキストのメタデータなど、エージェントの動作の完全なタイムラインをキャプチャします。 トレースは、以下の場合に使用します。

• デバッグとトラブルシューティング: エージェントが失敗した場所やエージェントが予期しない動作を行った場所を正確に特定します。
• パフォーマンス分析: エージェントの実行全体にわたるレイテンシ、エラー、スループットを評価し、動作を最適化します。
• コンプライアンスと監査: エージェントが何を、いつ、どのように行ったかについて、検証可能な記録を維持します。これは、監査や規制対象のワークフローに不可欠です。
• 継続的な改善: トレースに関するインサイトを使用して、エージェントのロジックの微調整、動作の改良、新しいモデルのトレーニングを行います。

以下の表は、トレースの可視化によってエージェントの動作をデバッグ、分析、最適化する能力を強化できる、一般的なユース ケースの概要を示しています。各例では、開発中および実行時の監視中に、トレース データがどのようにインサイトを明らかにし、より適切な意思決定を促進するかを示しています。

ユースケース	トレースの利用方法
ツールの呼び出し中にエージェントが失敗する	正確なステップ、入力、出力、およびエラーを見つけて検証する
パフォーマンスが遅い	タイムスタンプを使用してボトルネックを特定する
エラーの急増を調査する	実行をステータスでフィルター処理し、パターンをトレースする
運用環境の修正を検証する	元の実行を再現し、問題が発生しなくなったことを確認する
監査レポートを準備する	意思決定の経路と処理したデータを示すトレースをエクスポートまたは確認する

トレースの種類

トレースには 2 つの異なる種類があり、エージェントの動作を把握して分析する上で、それぞれが特定の目的を果たします。

• エージェントの実行のトレース: このトレースは、ライブ実行中やスケジュール設定された実行中に、エージェントのステップごとの実行をキャプチャします。エージェントがどのようにデータを処理し、ツールを呼び出し、条件を処理し、さまざまなステートにリアルタイムで応答したかが分かります。
• 評価の実行のトレース: 評価のトレースは、定義済みの入力に対してエージェントをテストするときに生成します。通常は、モデルの評価、シナリオの検証、またはテスト ケースの実行時に使用します。エージェントの正確性、意思決定の品質、および制御された条件下での動作を評価するのに役立ちます。

トレースにアクセスする

どちらの種類のトレースにも、次の 2 つの主要な場所からアクセスできます。

• Agent Builder – エージェントの設計またはテスト中に、トレースをビルダーで直接利用できます。
  • エージェントを実行すると、下部のパネルが自動的に開いて [実行証跡] タブに移動し、現在の実行のライブ トレースが表示されます。[履歴] タブに切り替えて過去の実行を表示し、評価セットに実行を直接追加することもできます。
  • [評価] タブと [出力] タブには、最近の実行の別のビューで表示され、動作と結果をエージェントの定義と併せて検査できます。
• [エージェントのインスタンス] ページ – [Agents] > [インスタンス] セクションに移動します。ここから、特定のエージェントを選択して任意の実行を選択し、そのトレース ビューを開くと、視覚的な完全なトレースと [ログ] パネルが表示されます。

エージェントの実行でも評価の実行でも、トレースを表示すると、エージェントの実行を可視化できます。以下が可能です。

• 色分けされたノードで示される実行結果 (成功、失敗、またはリトライ) を確認できます。
• 任意のノードにカーソルを合わせると、開始と終了のタイムスタンプ、実行ステータス、入力スニペットと出力スニペットのプレビューが表示されます。
• ノードを選択すると、完全な JSON ペイロード、ログとエラー、実行時のメトリック (トークンの使用状況、レイテンシ) などの詳細が表示されます。

トレース データに対するアクセス権を管理する

このセクションでは、管理者がロールベースのアクセス制御モデルを使用してトレース データに対するアクセス権を設定する方法について説明します。

トレース ログを表示するには、次の権限が必要です。

• Logs.View
• Jobs.View

既定のロールの権限の詳細については、「既定のロール」を参照してください。

次のマトリクスは、権限の組み合わせによって可視性がどのような結果になるかについて説明しています。これらの組み合わせにより、ロールベースの権限に応じて表示できるトレースの詳細が定義されます。

Logs.View	Jobs.View	アクセス権の結果
有効化	有効化	すべての属性
有効化	無効化	すべての属性
無効化	有効化	一部の属性 (例: 名前、種類)
無効化	無効化	アクセス権限なし。

トレース データを表示するために必要な権限がない場合は、メッセージが表示され、アクセスが完全に制限されているか、それとも部分的に制限されているかが説明されるとともに、必要な権限を要求するためのガイダンスが提供されます。

エージェントの実行に関するフィードバック (プレビュー)

フィードバックは、エージェントのランタイムを解釈して改善するための重要なメカニズムです。フィードバックにより、動作を確認して問題を診断し、エージェントがどのように意思決定を行うかという点で意味のあるパターンを文書化できます。

フィードバックは、デバッグ以外に、フィードバックベースのエピソード メモリへの中心的なインプットとしても機能します。このため、調整を行うたびにプロンプト全体を書き直さなくても、エージェントは意思決定ポリシーを段階的に改良できます。

フィードバックとメモリの関係

フィードバックは注釈ツールとして機能しますが、その最も強力な用途はエピソード メモリに影響を与えることです。

トレースについてのフィードバックを提供することで、エージェントが今後の実行で再現または回避すべき動作を示します。

• 繰り返しによる進化: 静的な解決策とは異なり、フィードバックベースのメモリでは、エージェントの動作を時間の経過とともに改善できます。エージェントは学習によって、正しいまたは正しくないとしてフラグが付けられたパターンを認識します。
• 対象を絞った改善: このアプローチは、エージェントがほとんどの場合に「ほぼ正しい」フローや、意思決定ポリシーがまだ開発段階であるフローで最も役に立ちます。
• 選択的メモリ: すべてのフィードバックが自動的にメモリになるわけではありません。どの注釈が価値の高い学習機会に相当するかをユーザーが能動的に判断し、低品質のフィードバックや一貫性のないフィードバックによってパフォーマンスが低下するのを防ぐ必要があります。

フィードバックを適用する場所

エージェント トレース内の任意の範囲に対してフィードバックを提供できます。この柔軟性により、動作を確認または診断する際に、特定のツールの呼び出し、ガードレールの確認、または LLM の出力に注釈を付けることができます。

エピソード メモリの対象となるのは、エージェントの実行の範囲に適用されたフィードバックのみです。分析のためにトレースの任意の部分に注釈を付けることができますが、メモリとして保存され、今後の実行で取得されるのは、エージェントの実行の範囲に直接関連するフィードバックのみです。

フィードバックを適用すべき状況

すべてのトレースにフィードバックを提供すると反復学習は最大化されますが、現実的には、最適化に最高の価値を提供するトレースに集中することをお勧めします。

以下のシナリオに重点を置きます。

• 重要なシナリオ: 重要な意思決定や影響の大きいエラーを含むトレース。
• 繰り返し発生するパターン: エージェントが常に苦労しているか、繰り返しエラーが発生する領域。
• 難しい意思決定: エージェントが複雑な選択に直面した事例。
• 否定的な感情: 質の低いユーザー エクスペリエンスにつながった実行。
• モデルの動作: エージェントに厳密に模倣または回避させる特定の動作を明確に示す例。

継続的な改善のためにはフィードバックを適用することが不可欠です。これにより、より優れた動作を段階的にエンコードして、エージェントの実行の信頼性と一貫性を向上できます。

• トレースの優先順位の設定: 重要なシナリオ、影響の大きいエラー、またはエージェントが苦労している繰り返し発生するパターンのトレースに重点を置きます。
• 価値の高いシナリオ: エージェントにとって難しい意思決定を表す実行、ユーザーの否定的な感情を示す実行、またはエージェントに模倣または回避させる動作を明確に示す実行を優先します。
• 重視する領域: フィードバックを提供している領域を明確に指定します。
  • アウトプット: 最終的な結果が期待を満たしていたかどうか。
  • 計画の実行 (軌跡): エージェントはタスクのステップを期待された順序で実行したかどうか。
  • コメント: コメントを使用して、フィードバックを強化し、メモリの取得に情報を提供します。