エージェントのトレースを標準規約に沿って出力しているのに、半年後の規約改定でダッシュボードが空になる。この事故は、規約がまだ安定版ではないことを前提にしていないと起きます。
基本のスパン設計はエージェントのトレース計装、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_agent | create_agent {agent.name} | CLIENT |
invoke_agent(リモート) | invoke_agent {agent.name} | CLIENT |
invoke_agent(同一プロセス) | 同上 | INTERNAL |
invoke_workflow | invoke_workflow {workflow.name} | INTERNAL |
plan | plan {agent.name} | INTERNAL |
execute_tool | execute_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層に分けると改定の影響を局所化できます。
ここからは仕様ではなく、本記事の設計提案です。
- 版の固定: 採用した規約のコミットまたはタグを社内文書に記録し、属性の一覧を自社のスキーマ定義として持つ。追従は四半期など決めた周期で差分レビューする
- 変換層: アプリは自社名前空間の属性を出し、Collector側で標準属性へ写像する。改定時の修正はCollector設定1か所で済み、アプリの再デプロイを避けられる
- 契約テスト: CIで
invoke_agentとexecute_toolを1回ずつ実行し、必須属性とスパン親子関係が出ていることを検証する。計装ライブラリの更新で属性名が変わった場合に検知できる
監査証跡として使う情報(誰の権限で、どのポリシー判定を経て実行したか)は、標準規約に定義がありません。実行主体や判定結果は自社名前空間の属性で持ち、gen_ai.conversation.id と gen_ai.tool.call.id で標準スパンと突き合わせる構成にすると、規約が変わっても証跡の意味が保てます。
規模別の留意点(SMB / エンタープライズ)
SMB は、SaaS型の観測基盤に計装ライブラリ経由で送るだけでも始められます。内容属性は出さず、ライブラリのバージョンを固定することから着手してください。エンタープライズでは、複数チームが異なるフレームワークを使うため、Collectorでの正規化と契約テストの共通化が効きます。規模が大きい場合はRDEでの基盤設計もご検討ください。
参考
- open-telemetry/semantic-conventions-genai — GitHub
- Semantic conventions for GenAI agent and framework spans — GitHub
- Semantic conventions for Anthropic client operations — GitHub
- Semantic Conventions for GenAI agent and framework spans — OpenTelemetry
まとめ
GenAI規約は Development 段階で、専用リポジトリへ移管済みです。スパンは5種で木構造を作り、内容属性は Opt-In です。版の固定、Collectorでの正規化、契約テストの3層を置けば、規約の改定を計画的に取り込めます。エージェントのトレース設計と監査証跡の整備は、AI Opsが導入から定着まで伴走します。
