Skip to main content
このドキュメントは、公式の OpenTelemetry GenAI Semantic Conventions に Agent Lens 固有のルールと推奨事項を追加したものです。上流の仕様で MAY または SHOULD とされている項目は、このプロファイルでは基本的に MUST となります (RFC 2119 に準拠) 。このドキュメントで特に記載がない限り、公式のセマンティック規約が適用されます。

API

OTLP protobuf を POST /agents/otel/v1/traces に送信します。認証と project ルーティングについては、Agent Lens に OpenTelemetry スパンを送信するを参照してください。

チェックリスト

Agent Lens が OTel スパンを正しく取り込めるように、スパンが次のルールに準拠していることを確認してください。

Agent Lens データモデルのマッピング

以下の属性は Agent Lens によって保存され、公開されます。このリストはすべてを網羅したものではなく、実際のフォールバックロジックはここに記載した内容よりも複雑な場合があります。レガシー属性および非推奨属性 (OpenInference を含む) のサポートは best-effort です。

特殊な GenAI オペレーション名

すべてのスパンで gen_ai.operation.name を設定する必要があります (MUST) 。その値には、公式の OTel セマンティック規約で定義されている既知の名前を使用することが推奨されます (SHOULD) 。以下のオペレーション名は、Agent Lens において特別な意味を持ちます。これらは、ほとんどのエージェント型ワークフローを記述するのに必要な最小限の操作です。

カスタム属性

Agent Lens は、ベンダー固有の属性名とユーザー定義の属性名を受け入れ、それらをカスタム属性として利用できるようにします。例: my_company.user.is_admin=true、my_company.user.sentiment="positive"、my_company.eval.score=0.5。
  • カスタム属性の値は、整数、float、string、または真偽値でなければなりません (MUST)。
  • カスタム属性名は低カーディナリティでなければならず (MUST)、動的に生成してはなりません (MUST NOT)。
  • カスタム属性名には、my_company.* のような一貫した namespace を使用すべきです (SHOULD)。

OTel のスパンと属性

このセクションは、OTel 公式のセマンティック規約における エージェント スパン と 推論スパン の構成に沿っていますが、記載しているのはこのプロファイルが公式と異なる点のみです。スパン名、スパンの種類、ここに記載されていないスパンなど、それ以外はすべて公式のガイドラインに従います。

Invoke workflow スパン

Agent Lens では、ルートスパンは invoke_workflow または invoke_agent のいずれかである必要があります (MUST)。ユーザーが複数のエージェントを同時に呼び出せる複雑なケースには invoke_workflow を使用します。それ以外の場合は invoke_agent を使用することをお勧めします。

エージェント呼び出しスパン

Agent Lens では、ルートスパンは invoke_workflow または invoke_agent のいずれかである必要があります (MUST)。ユーザーが複数のエージェントを同時に呼び出せるような複雑なケースには invoke_workflow を使用します。それ以外の場合は invoke_agent を推奨します。

推論スパン

Agent Lens は、推論スパンを使用して会話のメッセージ履歴を構築し、コストを推定します。推論スパンには、ツール呼び出しのリクエストと応答も含まれます。モデルがツール呼び出しで最終応答を送信する場合、そのツール名は final_answer、final_result、set_model_response、send_message のいずれかである必要があります (MUST) 。

トークン使用量とコスト

Agent Lens は、各推論スパンのコストをそのトークン使用量と gen_ai.response.model から推定します。
  • gen_ai.usage.input_tokens は、キャッシュされたトークンを含む入力の合計でなければなりません (MUST)。キャッシュの読み取りと書き込みも、gen_ai.usage.cache_read.input_tokens と gen_ai.usage.cache_write.input_tokens で報告する必要があります (SHOULD)。Agent Lens はこれらを合計から差し引き、それぞれ固有の料金で計算します。gen_ai.usage.input_tokens がキャッシュされていないトークンのみをカウントしている場合、入力が実際より少なく集計され、コストがマイナスと表示されることがあります。
  • gen_ai.usage.output_tokens は、推論トークンを含む出力の合計でなければなりません (MUST)。
  • 一部のプロバイダーはこれらのカウントを別々に報告するため、合計に加算し直してください。Anthropic はキャッシュされたトークンを入力トークンとは別に報告し、Gemini は思考トークンを出力トークンとは別に報告します。OpenAI は、キャッシュされたトークンを入力カウントに、推論トークンを出力カウントにすでに含めています。
  • gen_ai.response.model は、プロバイダーが返した正確なモデル ID でなければなりません (MUST)。opus や sonnet などのエイリアスには価格が設定されていないため、その Call には Cost - と表示されます。
  • 使用量の属性は、推論スパンにのみ設定する必要があります (SHOULD)。ターンの合計値を、そのターンの invoke_agent スパンにコピーしないでください。

Execute tool スパン

ツール呼び出しは、モデルがアプリケーションに関数の実行を要求したときに発生します。1 つのツール呼び出しは 3 つのスパンにまたがって記録されます。Agent Lens がこれらをリンクできるように、インストルメンテーションでは各スパンに同じ gen_ai.tool.call.id を記録する必要があります。
  1. モデルが呼び出しを要求する推論スパン (gen_ai.output.messages 内の tool_call パートとして記録) 。
  2. 関数の実行を表す execute_tool スパン。
  3. 結果をモデルに返す次の推論スパン (gen_ai.input.messages 内の tool_call_response パートとして記録) 。
リクエスト、実行、応答の各パートは、すべて同じ gen_ai.tool.call.id でリンクされている必要があり (MUST) 、この ID はトレース内で一意である必要があります (MUST) 。

サンプル

エージェントがツールを使用して質問に回答する

エージェントがサブエージェントをツールとして呼び出す

ワークフローで 2 つのエージェントを並列実行する

エージェントによる画像生成

失敗するツール呼び出し

最終更新日 2026年11月18日