約 4 分で読めます

GenAI規約の変更に耐えるエージェントトレース設計

エージェントのトレースを標準規約に沿って出力しているのに、半年後の規約改定でダッシュボードが空になる。この事故は、規約がまだ安定版ではないことを前提にしていないと起きます。

基本のスパン設計はエージェントのトレース計装、Claude API側の出力統制はClaude API OpenTelemetry出力の統制設計で扱いました。本記事は「規約が動く」ことを前提に、版固定と変換層をどこに置くかを整理します。

GenAI規約はいまどこにあり、どこまで安定しているのか

GenAI規約は専用リポジトリ semantic-conventions-genai に移管され、エージェントスパンは Development 段階です。

opentelemetry.io の旧ページには、GenAI規約が専用リポジトリへ移った旨と、そのページがもう保守されない旨の案内だけが残っています。現在の定義は open-telemetry/semantic-conventions-genai の docs/gen-ai/ 配下にあります。

同リポジトリの GenAI 文書とエージェントスパン文書は、先頭の Status が Development です。属性表でも gen_ai.* はほぼ Development で、Stable は error.type や server.port など共通規約から借りた属性に限られます。執筆時点で確認した範囲では、README のスキーマURL節は TODO のままで、Releases も空でした。

運用上の含意は2つです。ブログ記事や古いサンプルの属性名をそのまま信じないこと、そして規約の版を自社で固定して追従を計画的に行うことです。現行文書は gen_ai.provider.name を Required とし、Anthropic 向け文書は値を "anthropic" と定めています。

エージェントの実行はどのスパン構造で表されるのか

スパンは create_agent・invoke_agent・invoke_workflow・plan・execute_tool の5種で、実行を木構造に載せます。

gen_ai.operation.name の値がそのままスパン種別になります。

operationスパン名種別
create_agentcreate_agent {agent.name}CLIENT
invoke_agent(リモート)invoke_agent {agent.name}CLIENT
invoke_agent(同一プロセス)同上INTERNAL
invoke_workflowinvoke_workflow {workflow.name}INTERNAL
planplan {agent.name}INTERNAL
execute_toolexecute_tool {tool.name}INTERNAL

plan は計画を立てる段階を表し、計画を生成するLLM呼び出しはその子になります。計画から実行されるツールのスパンは、同じ invoke_agent 配下の兄弟になります。計画と通常の推論を区別できない計装は plan を出さないことが仕様で求められているため、フレームワークによってスパンの有無が違う前提で、クエリを書いてください。

execute_tool は gen_ai.tool.name が Required で、gen_ai.tool.call.id は条件付き必須です。ツールが別エージェントへの委譲として動く場合は、gen_ai.transfer.target.name などで委譲先を記録する専用の洗練形が用意されています。

内容属性はなぜ既定でオフにすべきなのか

プロンプトや応答、ツール引数の属性は Opt-In です。個人情報を含み得るため、既定では出力しない設計が前提です。

gen_ai.input.messages、gen_ai.output.messages、gen_ai.system_instructions、gen_ai.tool.definitions、gen_ai.tool.call.arguments、gen_ai.tool.call.result はいずれも要求レベルが Opt-In です。仕様自身が、メッセージ系の属性は利用者の個人情報を含み得ると注記しています。

これらには _ref 付きの対応属性(例: gen_ai.input.messages_ref)があり、外部ストレージ上の場所を絶対URIで指します。本文をスパンに載せず、アクセス制御つきの保管先へ置いてURIだけを残す設計が取れます。ただし仕様は、URIが保管先の情報を露出し得る点にも注意を促しています。

サンプリング判断に使う属性(gen_ai.agent.name、gen_ai.operation.name、gen_ai.provider.name、gen_ai.request.model など)は、スパン作成時に付与することが推奨されています。後から付けると、テールではなくヘッドでのサンプリングに使えません。

規約の変更に耐える層をどこに置くか

版を固定し、Collectorで属性名を正規化し、契約テストで欠落を検知する。3層に分けると改定の影響を局所化できます。

ここからは仕様ではなく、本記事の設計提案です。

  1. 版の固定: 採用した規約のコミットまたはタグを社内文書に記録し、属性の一覧を自社のスキーマ定義として持つ。追従は四半期など決めた周期で差分レビューする
  2. 変換層: アプリは自社名前空間の属性を出し、Collector側で標準属性へ写像する。改定時の修正はCollector設定1か所で済み、アプリの再デプロイを避けられる
  3. 契約テスト: CIで invoke_agent と execute_tool を1回ずつ実行し、必須属性とスパン親子関係が出ていることを検証する。計装ライブラリの更新で属性名が変わった場合に検知できる

監査証跡として使う情報(誰の権限で、どのポリシー判定を経て実行したか)は、標準規約に定義がありません。実行主体や判定結果は自社名前空間の属性で持ち、gen_ai.conversation.id と gen_ai.tool.call.id で標準スパンと突き合わせる構成にすると、規約が変わっても証跡の意味が保てます。

規模別の留意点(SMB / エンタープライズ)

SMB は、SaaS型の観測基盤に計装ライブラリ経由で送るだけでも始められます。内容属性は出さず、ライブラリのバージョンを固定することから着手してください。エンタープライズでは、複数チームが異なるフレームワークを使うため、Collectorでの正規化と契約テストの共通化が効きます。規模が大きい場合はRDEでの基盤設計もご検討ください。

参考

まとめ

GenAI規約は Development 段階で、専用リポジトリへ移管済みです。スパンは5種で木構造を作り、内容属性は Opt-In です。版の固定、Collectorでの正規化、契約テストの3層を置けば、規約の改定を計画的に取り込めます。エージェントのトレース設計と監査証跡の整備は、AI Opsが導入から定着まで伴走します。

関連記事

Claude API OpenTelemetry出力の統制設計AIエージェントのトレース計装——スパン設計とLLM呼び出し追跡評価スコアを疑う——トランスクリプト読解と採点バグ検出CI負荷25倍時代のTest Impact Analysis設計