16. 実行を追う（トレース）¶

16.1. 何が見える画面か¶

この画面は、エージェントの実行を一覧・絞り込みし、気になる 1 件をスパン単位まで掘り下げて原因を確認するためのものです。典型的には、次のような場面で使います。

• 運用ダッシュボードで異常の兆候（エラー率の上昇、特定エージェントの遅延、ガードレールの発動など）に気づいたとき（「トレースへの掘り下げ」）
• 精度評価で失敗ケースを見つけ、指標だけでは分からない中身を確認したいとき（「評価結果からトレースへ」）
• 利用者から個別の問い合わせがあり、特定の実行を直接調べたいとき

サイトマップから「Copilot」→「Accel Agent」→「ワークスペース」を開き、画面左のサイドナビゲーションの「トレース」から移動します。

トレースは、1 回の実行を構成する個々の処理単位（スパン）を、親子関係を持つ木構造として記録したものです。例えば「実行全体」のスパンの中に「イテレーション」のスパンがあり、その中に「モデル呼び出し」「ツール呼び出し」などのスパンが入ります。スパンの種別には、実行全体、イテレーション、モデル呼び出し、ツール呼び出し、ナレッジ検索、ガードレールなどがあります。

エージェントの実行に加えて、エージェント定義を経由しないIM-Copilotの生成AIの呼び出し（チャット アクション・埋め込み アクションなど）も、プロセス種別「直接実行」として記録されます。

画面は一覧と詳細の 2 段構成です。トレース一覧は、原因そのものは示さず、「いつ・どのエージェントが・どれだけ時間とコストを使い・どう終わったか」を並べて、掘り下げる実行を選ぶための画面です。トレース詳細は、選んだ 1 件について、スパンの木・時系列・中身まで掘り下げて原因を読むための画面です。

16.2. トレース一覧・詳細の読み方¶

イテレーション回数は列としても絞り込みとしても持ちません。イテレーション回数は実行ストラテジによって「1 回のイテレーションで LLM を何回呼ぶか」が変わり、繰り返しの多さを比べる指標として意味が揺れるためです。この代わりに、ストラテジによらず同じ意味を持つ LLM 呼び出し回数に一本化しています。

一覧の絞り込みは、期間・プロセス種別・エージェント・バージョン（エージェントを選んだときだけ表示）・ステータス（「すべて」「エラー」「正常」の 3 つ。初期表示は「すべて」）・エラー種別（ステータスを「エラー」にしたときだけ表示）・実行種別・所要時間（下限・上限）・使用モデル・LLM 呼び出し回数（下限・上限）・要注意実行（「ツールエラーあり」「出力リトライあり」を独立した ON/OFF で指定し、両方 ON なら両方に該当する実行だけを絞り込む）です。並べ替えができるのは、開始時刻（既定・降順）・実行時間・LLM 呼び出し回数・コストの 4 列だけです。1 ページは 20 件です。

詳細画面は、上から、実行全体の概要（サマリ帯）、スパンツリー（ウォーターフォールを兼ねる）、スパン詳細の 3 段で構成されます。サマリ帯には実行全体の状態・トークン数・コスト・イテレーション数・LLM 呼び出し回数が並びます。スパンツリーは親子構造とウォーターフォール形式の時系列を兼ね、初回トークンが返るまでの時間（TTFT）はモデル呼び出しスパンを選んだときにスパン詳細で確認できます。プロンプト・応答・ツールの入出力は折りたたみで表示され、プロンプトだけは既定で閉じています（本文が長く、開いたままだと後続の項目が画面から隠れるためです）。

図：トレース詳細画面。モデル呼び出し・ツール呼び出し・ナレッジ検索のスパンが、親子構造とウォーターフォールで並ぶ。

トレースからは、そのエージェント定義の編集画面へ逆リンクできますが、これはエージェント経由の実行の場合だけです。エージェント定義を持たない実行では、リンクの代わりに理由が表示されます。逆リンクの文言には選択中のスパンに応じたセクション名が表示されますが、移動先はエージェントID とバージョンに対応する編集画面です。セクションは指定されません。

16.3. 評価結果からトレースへ¶

精度評価の結果画面からは、対応するトレースへ辿ることができます。指標だけでは分からない失敗の内容を、トレースの詳細で確認します。

16.4. コストの見方¶

トークンの単価は AIモデル管理で設定します。精度評価では、対象エージェントの実行コストと採点コストが別々に記録されます。対象コストは対象エージェント自身が使うモデルの単価から、採点コストは採点モデルと Embeddings モデルの単価から、それぞれ算出されます。データセットの自動生成や改善提案の呼び出しにも別途コストがかかるため、評価実行の一つの金額を総費用として扱うことはできません。

金額は USD で集計・表示されます。画面右上の「1 USD =」の欄に通貨単位（既定は「¥」）とレートを入力すると、画面上の金額をその通貨に換算して表示できます。運用ダッシュボードと経営ダッシュボードでも、同じ欄で換算できます。換算は表示のためだけの概算で、集計は USD のまま行われます。入力したレートと通貨単位は保存されず、画面を開き直すと USD の表示に戻ります。為替レートは日々変動するため、期間の集計を 1 つのレートで換算した値は、あくまで概算として扱ってください。

16.5. 外部の監視基盤で追う¶

「トレースの外部送出設定（OTLP）」でトレースの外部送出を有効にした場合、外部の監視基盤にはトレース（スパン）だけが送られます。メトリクス、ログ、監査ログは送出の対象に含まれません。プロンプトや応答の本文も送られず、送られるのは属性のみです。どこまで細かい属性が送られるかは、内部のダッシュボードで見る場合との使い分けの判断材料です。

16.6. 保持期間¶

スパン詳細と、アーカイブ済みのトレースは、保持日数を過ぎると、ジョブ「トレース・監査ログ削除」の実行でデータベースから削除されます。ジョブネット「トレース・監査ログアーカイブ」「トレース・監査ログ削除」にトリガを設定するまでは、スパン詳細もトレースも削除されません。トリガの設定と、保持日数を変えるパラメータは「ジョブの運用」を参照してください。

16.7. 閲覧権限¶

トレースを参照する権限は、一覧と詳細で分かれていません。一覧を見られる利用者は、実行内容の本文（プロンプト・応答・ツールの入出力など）も含めて、テナント内の全実行を参照できます。「一覧だけ見せて中身は見せない」という権限の分け方は現在できません。トレースを参照する権限は、テナント内の全実行の本文を見せてよい利用者にだけ割り当ててください。

16.8. 読み違えやすい点¶

• トレース一覧のコスト列の「-（ハイフン）」は 0 ではなく、単価未設定で金額を算出できないことを示します。実際にコストが 0 で終わった実行（LLM に到達する前に終了した実行など）は「$0.0000」と表示され、区別されます。

• サマリ帯に出る「イテレーション」はトレース全体の集計値、スパンツリーの各イテレーションスパンに付く番号は個々のイテレーションの通し番号です。ツリーを絞り込んで表示行数が減っても、サマリ帯の値は変わりません。

• ロジックツールなど、ツールの処理の中から呼び出した生成AIは、トレースに記録されません。エージェント定義を経由しない実行として、プロセス種別「直接実行」に記録されることもありません。そのため、そのツールを呼び出したエージェントの実行について、次の箇所にはその生成AIの呼び出しの分が含まれません。

  • トレース詳細のサマリ帯のトークン数・コスト・LLM 呼び出し回数と、トレース一覧のコストと LLM 呼び出し回数（実際より少なく集計されます）
  • 運用ダッシュボードと経営ダッシュボードのトークン数とコスト（実際より少なく集計されます）
  • 経営ダッシュボードの「モデル別」の集計
  • 「使用モデル」での絞り込み（ツールの処理の中だけで使ったモデルで絞り込んでも、トレース一覧と運用ダッシュボードにそのエージェントの実行は表示されません）
  • 外部の監視基盤へ送出するトレース（OTLP）

  処理の中で生成AIを呼び出すツールを使うエージェントでは、トークン数とコストを実際より小さい値として読んでください。

  ロジックツールとして定義したロジックフローでも、エージェント定義を経由せずに実行した場合は、その中で呼び出した生成AIはプロセス種別「直接実行」として記録されます。

• ツールの処理の中から生成AIを呼び出すと、トレース詳細では、ツール呼び出しのスパンの配下にモデル呼び出しのスパンが表示されません。その生成AIの呼び出しにかかった時間は、ツール呼び出しのスパンの所要時間とウォーターフォールに含まれます。そのため、ツール呼び出しのスパンの所要時間が長いときは、ツールの処理の中の生成AIの呼び出しに時間がかかっていることがあります。

• スパン詳細の「finish_reason」（生成を終えた理由）が記録されるのは、チャット（テキスト生成）のモデル呼び出しだけです。埋め込み（ナレッジのベクトル化を含む）・イメージ生成・文字起こしなど、チャット以外のモデル呼び出しには値が無いため、常に「-（ハイフン）」と表示されます。記録に失敗したことを示すものではありません。

• エージェントの実行では、LLM がツールの呼び出しだけを返した応答について、呼び出すツール名と引数がツール呼び出しのスパンに記録されます。プロセス種別「直接実行」の記録では、ツール名と引数は記録されません。

  エージェントの実行でも直接実行でも、LLM がツールの呼び出しだけを返したモデル呼び出しのスパンには、スパン詳細に応答が表示されません。保持日数を過ぎて本文が削除された場合（「スパン詳細」）とは異なり、応答は最初から記録されていません。ツールの呼び出しを返したことは、「finish_reason」の値（tool_callsなど）でわかります。