エージェントトレーシングとは？スパン木の設計・gen_ai属性・記録範囲を実装目線で解説【2026年版】

エージェントトレーシングとは、AIエージェントが依頼を1件片づけるまでの推論・ツール実行・再試行の連なりを、親子関係を持つスパンの木として記録し、後から1手ずつ辿れる状態にしておく計装のことです。実装で困るのは記録の開始ではありません。どこをスパンの単位に切るか、属性名を何に揃えるか、入出力の本文をどこまで残すか、そして溜まったトレースから不具合へどう辿り着くか。この記事では、分散トレーシングの計装で足りなくなる3点、invoke_agent配下にchatとexecute_toolを並べる階層の作り方、2026年8月9日時点で確認できるOpenTelemetryのGenAI規約の状態、壊れた実行を読み解く3つの失敗型、そして作り込まずに済ませてよい場面までを整理します。プロンプト版管理や評価データセットを含む運用全体の設計はLLMOpsの4層構成で扱っているため、本記事は記録側だけに絞ります。

まとめ｜スパン木の設計と属性の統一と記録範囲で決まる成否

先に結論を置きます。エージェントのトレースが役に立つかどうかは、記録量ではなくスパンの切り方で決まります。1依頼を1トレースとし、モデル呼び出し1回とツール実行1回をそれぞれ独立したスパンにする。この単位が崩れていると、何回モデルを呼んだのか、どのツールで落ちたのかが後から分かりません。全部を1スパンに詰めた記録は、遅い理由も高い理由も説明できない状態のままです。

着手前に決めることは3つあります。第一にスパンの階層。エージェント起動を親、推論とツール実行を子に置き、再試行は別スパンとして並べます。第二に属性名。OpenTelemetryのGenAI規約に沿って gen_ai 接頭辞で揃え、規約が Development のうちはエクスポート先を差し替えられる構造にしておく。第三に記録範囲です。入出力の本文は既定で残さず、必要な案件だけ明示的に有効化し、失敗したトレースだけ長期に保管します。この3点を決めずにSDKを入れると、機微情報を含む巨大なログが溜まる割に、障害のたびに本文をgrepする運用へ戻ります。

エージェントトレーシングの定義と分散トレーシングでは追えない3つの差

言葉としては分散トレーシングの一種ですが、対象が生成AIの実行になると計装で押さえるべき点が入れ替わります。まず範囲を確定させます。

1依頼を1トレースとして記録するエージェントトレーシングの範囲

入力はユーザーの依頼1件、出力はその依頼が終わるまでに起きた処理の記録です。1トレースの中には、モデルへの問い合わせ、ツールや外部APIの呼び出し、検索、後処理、そして失敗した試行がすべて子スパンとして並びます。各スパンには開始時刻と所要時間、成否、そして生成AI固有の情報（モデルID、トークン数、ツール名）が付きます。

ここに含まれないものも決めておきます。出力が業務として妥当だったかという採点、プロンプトの版をどこで管理するか、費用をどう削るか。これらはトレースを材料に別の層で扱う話です。記録は判断の材料であって、判断そのものではありません。

分散トレーシングの計装で足りなくなる非決定性・入れ子・費用の3点

既存のマイクロサービス向け計装をそのまま持ち込むと、3点で足りなくなります。

• 非決定性：同じ入力でも通る経路が変わる。成功したときと失敗したときで木の形そのものが違うため、経路の固定を前提にした監視では異常を定義できない
• 入れ子の深さ：1依頼で数十スパンに達する。HTTPリクエスト1本＝数スパンという前提の保存設計だと、件数と保存量が桁で外れる
• 費用の可視化：レイテンシとエラー率だけでは足りず、スパン単位のトークン数と推定コストを持たないと、遅い箇所と高い箇所の区別がつかない

逆に言えば、伝播の仕組みやバックエンドは既存資産をそのまま使えます。Jaegerによる分散トレーシングやAPMによる性能監視を既に運用しているなら、土台を作り直す必要はなく、属性と単位を生成AI向けに足す作業になります。

エージェント実行をスパン木で表す階層設計とgen_ai属性の付け方

スパンの切り方は好みで決めません。OpenTelemetryのGenAI規約が操作ごとの型を定義しているため、そこへ寄せるのが後の乗り換えを楽にします。

invoke_agentの下にchatとexecute_toolを並べる階層の作り方

規約では、エージェントの起動を表す操作として create_agent・invoke_agent・invoke_workflow・plan が定義され、ツール実行は execute_tool、モデル呼び出しは chat などの推論操作として扱われます。推論スパンの名前は「操作名＋モデルID」の形式です（規約上は {gen_ai.operation.name} {gen_ai.request.model}）。

実装上の勘所は再試行の扱いです。同じツールを3回叩き直したなら、1スパンの中で回数を属性に持たせるのではなく、3つの兄弟スパンとして並べます。こうしておくと、何回目で通ったのか、毎回同じ引数だったのかが木の形から読めます。ツール呼び出しそのものの設計はAIツール使用の実装、計画を作り直す条件はプランニングと再計画の設計で詳しく扱う内容です。

GenAI規約で決まっている必須属性と開発中ゆえに動く箇所の扱い

属性は3層で考えると迷いません。必ず付けるのが gen_ai.operation.name で、規約上 Required です。create_agent と invoke_agent（クライアント側）では gen_ai.provider.name も Required とされています。次に条件付きで求められるのが gen_ai.agent.id・gen_ai.agent.name・gen_ai.conversation.id、失敗時の error.type。ツール側は gen_ai.tool.name・gen_ai.tool.call.id・gen_ai.tool.type の3点です。

費用と速度の分析に効くのはトークン系で、gen_ai.usage.input_tokens・gen_ai.usage.output_tokens に加え、推論用の出力を分けて数える gen_ai.usage.reasoning.output_tokens が定義されています。入力トークンにはキャッシュ済みの分も含めるべきと明記されているため、キャッシュ利用時に費用を過大評価しないよう、単価計算側で分けて扱ってください。

ただし前提として、2026年8月9日時点でGenAI規約は本体から分離した専用リポジトリに置かれ、リリースタグは1件も切られていません。エージェント系スパンのステータスもすべて Development です。属性名は今後も動く前提で、ダッシュボードのクエリを属性名べた書きで量産しないほうが安全に運用できます。

入出力メッセージを既定で記録しないopt-in設計とマスキング

プロンプトと応答の本文を残すかどうかは、設計の分かれ目です。規約では gen_ai.input.messages・gen_ai.output.messages・gen_ai.system_instructions はいずれも Opt-In かつ Development に置かれ、利用者情報や個人情報を含む可能性が高いという警告が明記されています。

実務では、本文の記録を環境変数などで切り替えられる形にし、既定は無効にします。開発環境と、顧客の同意が取れている案件だけ有効化する。有効化する場合も、メールアドレスや電話番号のような定型パターンは送信前にマスキングし、社外のSaaSへ送る構成なら送信先と保持期間を情報セキュリティの担当と先に合意しておきます。この判断を後回しにすると、本番稼働後に「全リクエストの本文が外部に残っていた」という指摘を受けてから設計をやり直すことになります。

自動計装と手動スパンの境界・コンテキスト伝播・エクスポート先の設計

計装の作業量は、フレームワークの自動計装をどこまで信じるかで変わります。全部を手で書く必要はなく、足りない部分だけを補う進め方が現実的です。

フレームワークの自動計装で取れる範囲と手動スパンを足す境界線

主要なエージェントフレームワークとLLMのSDKには計装ライブラリが用意されており、モデル呼び出しとツール実行はほぼ自動でスパンになります。まずこれを入れて、木が出るところまで確認する。ここまでは半日で終わります。

足りないのは自社ロジック側です。検索前の問い合わせ整形、取得した文書の絞り込み、出力の検査、承認待ちの時間。これらはフレームワークから見えないため、手動でスパンを切ります。目安として、失敗の原因になり得る分岐と、100ミリ秒以上かかる自社処理には自分でスパンを置いてください。逆に、ループ内の細かなヘルパー関数まで刻むと、木が読めなくなるだけです。

非同期処理と並列実行でトレース文脈を落とさないための伝播の実装

エージェントを並列実行やバックグラウンドのワーカーへ載せた時点で、コンテキストの伝播が主要な事故源になります。症状は分かりやすく、親のない孤立スパンが大量に現れる、あるいはツール実行だけが別トレースとして記録される形です。

対処は2つ。プロセス内の非同期処理では、フレームワークの提供する文脈伝播の仕組みに乗せ、タスクを起動する側で現在のコンテキストを明示的に引き渡します。プロセスをまたぐ場合は、キューのメッセージや外部APIのヘッダにトレース情報を載せて運びます。ここは一般の分散システムと同じ作法で、生成AI固有の工夫は要りません。

専用SDKで始めてエクスポート先を差し替え可能にしておく構成

収集した後の置き場所は、既存基盤の有無で決まります。社内にトレース基盤があるならOTLPで同じ経路へ流し、生成AI向けの画面が要るならLangfuseのようなセルフホスト可能なOSSを併用する構成が扱いやすい形です。

選定で迷ったときの原則は1つで、計装コードと送信先を分離しておくことです。規約がDevelopmentの段階では、送信先の乗り換えが数年内に発生する前提で組みます。ツールごとの守備範囲やセルフホストの負担、既存のMLflow資産との関係はLLMOpsのツール選定基準に整理しました。

壊れた実行をトレースから特定する3つの失敗型と読み解きの具体手順

記録を始めた現場でよく聞くのが、木は出るようになったが結局どこを見ればよいか分からない、という話です。エージェントの不具合は3型に集中します。

ツール選択の誤りを親スパンの入力と引数の突き合わせで見つける

最も多い型が、そもそも呼ぶべきツールを間違えているケースです。個々のスパンは成功扱いで終わるため、エラー率の監視には引っかかりません。

読み方は決まっています。invoke_agentの入力と、その下に並ぶexecute_toolの gen_ai.tool.name と引数を並べて突き合わせる。依頼が在庫照会なのに検索ツールだけが2回叩かれている、引数の日付が依頼と1日ずれている、といったズレがここで見えます。運用では、ツール名の出現分布を日次で並べ、特定ツールの比率が跳ねた日をトレースの入口にする方法が効きます。

ループ暴走と再試行の重複を同一引数の反復とスパン数で検出する

2つ目は同じ手を繰り返す型です。観測は単純で、1トレースあたりのスパン数を分布で持ち、上位パーセンタイルだけを抜き出します。中央値が12スパンの系で80スパンのトレースが出ていれば、ほぼ確実に堂々巡りです。

木を開いたら、同一のツール名かつ同一の引数を持つスパンが何回並んでいるかを数えます。3回以上続くなら、モデルが前回の結果を読めていないか、失敗が呼び出し側へ伝わっていません。対策は計装ではなく実装側で、反復回数の上限と、同一引数の再実行を弾くガードを入れる。副作用を持つツールの二重実行はここで止めます。

遅延と費用の犯人をスパン単位の待ち時間とトークン数で切り分ける

3つ目は遅い・高いという相談です。合計時間だけを見ても原因は割れません。トレースを開いて、待ち時間の内訳をモデル待ち・ツール待ち・自社処理に分けます。ツール側のAPIが詰まっているだけなら、モデルを小型に替えても改善しません。

費用側は gen_ai.usage.input_tokens の推移を見ます。エージェントは会話履歴と過去のツール結果を毎回積み直すため、後半のスパンほど入力が膨らむのが通例です。何手目から入力トークンが跳ねるかを見れば、履歴の要約を入れる位置が決まります。同じ依頼を処理した2本のトレースで入力トークンが倍違うなら、原因は履歴の持ち方にあります。

トレースの記録範囲とサンプリングの判断・作り込む条件と見送る場面

ここは条件を付けて言い切ります。エージェントのトレースは、全部を全期間残すと保存料と分析速度の両方で行き詰まります。

全件保存から入るか失敗トレースを残すテールベースへ寄せるかの判断

初期は全件保存で構いません。日次で数百リクエスト程度なら、間引く前に母数が足りず、間引くほうが害になります。件数が増えて保存量が問題になった段階で、実行が終わってから残すかを決めるテールベース側へ寄せます。

エージェントでこの順序を勧める理由は、1依頼あたりのスパン数が数十に達し、しかも壊れた実行ほどスパン数が多いためです。入口で確率的に間引くと、いちばん見たい暴走トレースが真っ先に消えます。失敗したもの、閾値を超えて遅かったもの、費用が跳ねたものを残す条件付きの保存にすると、量を1割に落としても分析力はほとんど落ちません。ヘッドベースとテールベースの一般的な比較と率の決め方はトレースサンプリングの設計にまとめています。

原文は30〜90日・失敗例は無期限という保存期間の二段構えの設計

保存期間は2段に分けます。入出力の本文を含む詳細は30〜90日で消し、スパン数・トークン数・所要時間・成否といった集計値は長期に残す。詳細はデータ量が大きく、機微情報を含む可能性もあるため、長く置くほど負債になります。

例外は不具合の実例です。原因を特定できた失敗トレースは、匿名化したうえで期限の対象から外して保管します。回帰の確認材料になり、評価データセットの種にもなるためです。トレースを評価へつなぐ工程はAIエージェント評価の指標と実装で扱っています。

トレース基盤を作り込む3条件とログ1本で済ませてよい2つの場面

作り込む価値があるのは、次の3条件のうち2つ以上に当てはまる場合です。第一に、1依頼でモデルを3回以上呼ぶ多段構成であること。単発の要約や分類なら木にする意味が薄い。第二に、副作用を持つツールを含むこと。二重実行の検証に木が要ります。第三に、不特定多数へ出力を返すこと。事後に説明を求められる場面が発生します。

逆に、社内数人が使う単発プロンプトの機能や、人が結果を必ず確認する月次バッチなら、入力・出力・モデルID・トークン数をテーブルに残すだけで足ります。この段階でトレース基盤を入れても、運用対象が1つ増えるだけで意思決定は速くなりません。多段のエージェントを業務システムへ載せる設計や、記録から監査ログまでを含めた構築はAIエージェント開発で相談を受け付けています。どの業務をエージェントに任せるかという上流の判断はAIエージェントの導入判断を参照してください。

よくある質問

エージェントトレーシングの導入検討で実際に問われることの多い5点に答えます。

エージェントトレーシングと分散トレーシングは何が違いますか？

仕組みは同じで、記録する対象と単位が違います。分散トレーシングはサービス間の呼び出しを追う技術で、経路がほぼ固定であることを前提にできます。エージェントの場合は同じ入力でも通る経路が変わり、1依頼で数十スパンに達し、レイテンシに加えてトークン数と推定コストを持たないと分析が成立しません。既存の分散トレーシング基盤はそのまま土台に使えるため、属性とスパンの単位を生成AI向けに足す作業と捉えてください。

OpenTelemetryのGenAI規約に今から寄せるべきですか？

属性の命名だけ寄せて、実装は差し替え可能にしておく折衷が現実的です。2026年8月9日時点で、GenAI規約は本体から分離した専用リポジトリに置かれ、リリースタグは1件も公開されていません。エージェント系スパンのステータスもすべて Development です。規約に完全準拠する前提でダッシュボードや警報を作り込むと、属性名の変更のたびに定義を書き直すことになります。フレームワーク付属のSDKで記録しつつ、送信先を差し替えられる構造にしておく判断で足ります。

プロンプトと応答の本文はトレースに残すべきですか？

既定では残さず、必要な環境と案件だけ有効化してください。規約でも入出力メッセージとシステム指示はOpt-In扱いで、利用者情報や個人情報を含む可能性が高いという警告が付いています。開発環境では全文を残してデバッグを速くし、本番では原則メタデータだけにする運用が扱いやすい形です。本番で本文が必要な場合は、定型パターンのマスキング、保持期間の短縮、送信先の合意の3点を先に決めてから有効化します。

トレースを取ればエージェントの品質は測れますか？

測れません。トレースが答えるのは「何が起きたか」までで、「その出力が業務として妥当だったか」は別の層で採点します。ただし採点の材料はトレースからしか出ません。ツール選択が正しかったか、無駄な手数がなかったかといった軌跡の評価は、スパンの単位が揃っていて初めて成立します。指標の設計と採点の実装はAIエージェント評価、評価データセットを含む運用全体はLLMOpsで整理しています。

既存のAPMやJaegerにそのまま載せられますか？

載せられます。OTLPで送れる基盤なら、収集と保存の仕組みは共通で、生成AI向けの属性を足すだけで木は表示できます。差が出るのは画面側で、トークン数や推定コストの集計、プロンプト単位の比較といった生成AI固有の分析は汎用のAPM画面には用意されていません。既存基盤に流しつつ、分析用に専用ツールを併設する二重構成から始め、片方に寄せるかは運用してから判断する進め方を勧めます。

関連記事

• LLMOpsとは：トレースを含む4層の運用基盤、プロンプト版管理・評価・費用監視の全体像を扱います。
• AIエージェント評価とは：記録したトレースを材料に、軌跡とツール呼び出しを採点する指標設計を解説しています。
• トレースサンプリングとは：ヘッドベースとテールベースの仕組みと、サンプリング率の決め方をまとめています。
• Langfuseとは：セルフホストできるトレース基盤の機能とLangSmithとの違いを製品目線で整理しています。
• AIエージェントとは：どの業務にエージェントを載せるかという導入判断の基準を発注者視点で解説しています。