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

> OpenTelemetryのGenAI規約はDevelopment段階で専用リポジトリへ移管済みです。invoke_agentなど5種のスパンを版固定と内容の既定オフで安全に運用する設計をまとめます。

- Canonical: https://kuucorp.com/blog/otel-genai-semconv-agent-span-version-pinning-design/
- Date: 2026-10-31
- Last modified: 2026-10-31
- Publisher: Kuu株式会社 (https://kuucorp.com)

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

基本のスパン設計は[エージェントのトレース計装](/blog/agent-observability-tracing-instrumentation/)、Claude API側の出力統制は[Claude API OpenTelemetry出力の統制設計](/blog/claude-api-opentelemetry-export-destination-governance-design/)で扱いました。本記事は「規約が動く」ことを前提に、版固定と変換層をどこに置くかを整理します。

## 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層に分けると改定の影響を局所化できます。

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

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](https://kuucorp.com/services/rde/)での基盤設計もご検討ください。

## 参考

- [open-telemetry/semantic-conventions-genai — GitHub](https://github.com/open-telemetry/semantic-conventions-genai)
- [Semantic conventions for GenAI agent and framework spans — GitHub](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md)
- [Semantic conventions for Anthropic client operations — GitHub](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/anthropic.md)
- [Semantic Conventions for GenAI agent and framework spans — OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/)

## まとめ

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