Building_AI_Agent_Observability_with_OpenTelemetry.pdf

Transcript

1. Building AI Agent Observability with OpenTelemetry Japan Community Day 2026 / OpenTelemetry Meetup Japan · 2026/07/28 Joe / Yuzuru Ohira @joe_yuzupi
2. 自己紹介 Joe (Yuzuru Ohira) LayerX Inc. / Ai Workforce Division Group Manager, Platform Enablement Observability Architect for the AI Agent Platform 好きな技術は OpenTelemetry の Span Links © LayerX Inc. 2
3. © LayerX Inc. 3
4. 事業紹介 © LayerX Inc. 4
5. プロダクト構成 © LayerX Inc. 5
6. Agenda Agenda なぜ AI Agent を観測するのか GenAI Semantic Conventions について OTel をどう使って、評価・改善へつなげるか 今日はトレースをメインに扱います © LayerX Inc. 6
7. なぜ AI Agent を観測するのか AI Agent のオブザーバビリティをしたいモチベーション ① 経路が動的 どの Tool・Retrieval を呼ぶかは実 行時に Agent が決める。コードを 読んでも経路は分からない © LayerX Inc. ② 非決定的 同じ入力でも経路と結果が変わ る。デバッガで再現できない ③ 失敗が例外に出ない 処理は成功し、品質だけが失敗す る 7
8. なぜ AI Agent を観測するのか 例：根拠が曖昧なまま、回答が生成された User request 根拠付きで回答して 200 HTTP status © LayerX Inc. → Retrieval 結果 0件 → 0 Unhandled errors LLM 回答を生成 → Answer 根拠不足を明示しない 1 Answer generated 8
9. OTel で何を記録するか Traceで一連の実行を観測する Time Trace: answer a question end-to-end 2.4 s ecarT Span: invoke agent agent operation 2.3 s Span: retrieval 0.6 s Span: chat model inference 1.4 s © LayerX Inc. 9
10. OTel で何を記録するか Trace は、Agent の操作がつながった一回分の記録 Time Trace: answer a question end-to-end 2.4 s ecarT Span: invoke agent agent operation 2.3 s Span: retrieval 0.6 s Span: chat model inference 1.4 s Phoenix Traceを使って評価・改善を行う代表的なツール例 © LayerX Inc. 10
11. GenAI Semantic Conventions GenAI Semantic Conventions とは 生成AI・Agent の実行を記録するための OpenTelemetry の共通仕様 Model spans：モデル呼び出しの span Agent spans：Agent・Tool 実行の span Metrics：token 使用量やレイテンシ Events：モデルの入出力 Exceptions：実行中の例外 © LayerX Inc. open-telemetry/semantic-conventions-genai 11
12. GenAI Semantic Conventions の Span Spec例 属性 gen_ai.operation.name gen_ai.provider.name gen_ai.request.model gen_ai.usage.input_tokens gen_ai.input.messages © LayerX Inc. 必須か Required Description 実行した操作の種類 Required 計装側が識別したGenAI provider Conditionally リクエストで指定したモデル名 Required Recommended 入力に使用したtoken数 Opt-In デフォルトでは収集し モデルへ渡したchat history ない どういう値が入るか chat generate_content openai gcp.vertex_ai gpt-4 100 [{"role":"user", ...}] GenAI spans specification 12
13. GenAI Semantic Conventions の現在地 Development ステータスのため、破壊的変更もある前提で利用する Message EventのDeprecation System-specific naming policy Deprecated 移行先 変更前 変更後 gen_ai.system_instructions または gen_ai.input.messages gen_ai.system gen_ai.provider.name gen_ai.openai.* openai.* gen_ai.input.messages az.ai.* azure.ai.* gen_ai.system.message gen_ai.user.message gen_ai.assistant.message gen_ai.tool.message gen_ai.choice © LayerX Inc. gen_ai.output.messages v1.37 release notes · #2046 13
14. GenAI Semantic Conventions の変遷 継続的な変更とリリース遷移 v1.37 v1.38 v1.39 v1.40 v1.41 v1.42 © LayerX Inc. 2024-04 v1.37 v1.38-39 v1.42 SIG 発足 Breaking Change MCP SemConv 策定 Evaluation event 追加 専用リポジトリへ移管 Chat history を刷新。message event を / へ集約 Evaluation event、tool 定義と呼び出し詳細、 の span kind 指針 MCP の semantic conventions を追加 Retrieval span、cache token 属性 の span 名に tool 名を要求、reasoning token、 、streaming metrics を semantic-conventions-genai へ移管（2026-06） gen_ai.input.messages gen_ai.output.messages invoke_agent execute_tool invoke_workflow gen_ai.* 14
15. GenAI Semantic Conventions の現在地 フレームワークやプロバイダーごとに、記録仕様が異なる 実装 LangChain LangGraph Claude Agent SDK Google ADK (Python) Strands Agents SDK (Python) OpenAI Agents SDK © LayerX Inc. SemConv対応 部分対応 langsmith.* と併用 部分対応 claude_code.* が中心 対応あり experimental opt-in stable互換も混在 対応あり latestはopt-in 公式記載なし 独自Tracing 実際に記録する代表データ langsmith.span.kind gen_ai.system （旧名） gen_ai.system （旧名） input_tokens / agent_id gen_ai.agent.name gen_ai.usage.* gen_ai.agent.name gen_ai.operation.name gen_ai.usage.* agent / generation / function model / usage / tools OTel出力 OTLP Trace Trace（Beta） Metrics / Logs Trace / Metrics / Logs OTLP Trace / Metrics OpenAI Traces API custom processor LangChain OTel · Claude Agent SDK · Google ADK · Strands Agents SDK · OpenAI Agents SDK 15
16. GenAI 実装の対応状況 OTel Collectorで実装差分を吸収する Data Sources Backends OpenTelemetry Collector Grafana® collector.yaml ADK OpenAI Agents SDK © LayerX Inc. → → Splunk® Observability Cloud 16
17. オブザーバビリティサービスの対応状況 各オブザーバビリティサービスの GenAI 対応状況 サービス Datadog Langfuse Arize Phoenix New Relic Grafana Cloud Splunk © LayerX Inc. OTLP 受信 対応 HTTP 対応 対応（15.10.0+） 対応 対応 対応 GenAI 属性の扱い SemConv v1.37+ を Agent Observability へ自動マッピング OTel Span を Langfuse 形式へ変換（ を優先） を OpenInference へ自動変換 OTel 属性を保持し、NRQL で検索 OTLP を受信。GenAI dashboard は OpenLIT 経由で構成 を基準に Agent Span を抽出 langfuse.* gen_ai.* gen_ai.operation.name Datadog · Langfuse · Phoenix · New Relic · Grafana Cloud · Splunk 17
18. GenAI Semantic Conventions で計測する GenAI Semantic Conventions に沿って計装した Trace の例 Time invoke_agent research-agent plan research-agent chat Claude Sonnet 5 ecarT search_memory user-memory retrieval knowledge-base execute_tool web-search chat Claude Sonnet 5 © LayerX Inc. Invoke Agent span · Memory span · Retrieval span · Inference span 18
19. GenAI Semantic Conventions で計測する gen_ai.operation.name が、各 Span の役割を表す Time invoke_agent invoke_agent plan plan chat chat ecarT search_memory search_memory retrieval retrieval execute_tool execute_tool Agent 1回分の実行全体 実行前の計画・タスク分解 LLMによる回答やTool Callの生成 Agentの記憶ストアを検索 外部知識やコンテキストを検索 Agentが選択したToolの実処理 chat ※ 複数の Agent を束ねて実行する場合は、全体を invoke_workflow multi_agent_rag © LayerX Inc. ）。 として記録できる（例: gen_ai.workflow.name: Agent spans · GenAI spans · Memory span 19
20. ここから実行を追う まずは、通常の Trace と同じように読む 失敗を拾う Status: Error LLM API の rate limit・timeout Tool 実行の失敗 Retrieval backend への接続失敗 遅い実行を拾う duration 全体の所要時間 遅い Span・遅い operation の特定 重い DB コールなど、配下の Span へ掘り下げ invoke_agent W3C Trace Context により、GenAI の Span と従来の分散トレースを 同じ Trace として連携できる © LayerX Inc. https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ 20
21. ここから実行を追う 成功した実行にも、無駄な loop が埋まっている STATUS: OK・回答も正しい 探し方 同じ Tool を何度も呼び直している（配下の Span の数と並び） の duration が外れ値 / の 累積が突出 Time invoke_agent 42 s* chat invoke_agent web-search ecarT gen_ai.usage.input_tokens chat web-search output_tokens chat web-search… chat © LayerX Inc. 21
22. ここから実行を追う Trace の読み方で拾えるのはここまで Retrieval 0 results / low relevance © LayerX Inc. Status: unset 通常の読み方 品質の判定 → operation は完了 → 品質の失敗を検出で → Evaluation の領域 きない https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ 22
23. 主ケース — Evaluation を関連付ける Evaluation の結果を、対象の実行へ関連付ける Evaluation 単体では、悪いスコアがどの実行・どの経路で生まれたか辿れない。 GenAI operation 対象 Span OTel が担う 結果と対象 operation の相関 © LayerX Inc. ← Evaluation Event gen_ai.evaluation.result → Evaluator 人間の評価 / LLM-as-a-Judge Evaluator が担う groundedness 等の判定そのもの https://github.com/open-telemetry/semantic-conventions-genai/blob/c26a2c21d1ee70d5231bd440c7b48d3c94ee506a/docs/gen-ai/gen-ai-events.md#event-gen_aievaluationresult 23
24. Coding Agent から得た知見 Coding Agent は、実行過程の探索がしやすい 本スライドの誤字・表現チェック時の Trace（抜粋） Claude Code Trace claude_code.interaction claude_code.llm_request claude_code.tool · Bash claude_code.tool.execution claude_code.tool · preview_start claude_code.tool.blocked_on_user claude_code.llm_request claude_code.tool · get_page_text claude_code.tool.execution claude_code.llm_request © LayerX Inc. Time → 162.4 s 8.2 s 0.29 s 0.29 s 2.28 s 2.15 s 5.0 s 4 ms 3 ms 4.3 s 24
25. Coding Agent から得た知見 Trace に残すことで、失敗の因果関係を探れる parent agent handoff: pagination CSV export を実装 Subagent へ委任 reference: old helper offset 方式（件数で位置を指定） suspect subagent: implementation offset 方式で実装 ↓ 原因 Agent が古い実装方式を参照していた © LayerX Inc. https://www.langchain.com/blog/your-coding-agents-are-a-black-box-heres-how-to-crack-them-open 25
26. Coding Agent から得た知見 蓄積した Trace を、別の Agent が改善に使う ① Agent を実行 → ② Trace / usage を蓄積 ↑ 改善 ループ ↓ Prompt / Tool / Workflow を変更 ← タスクを処理し Tool / Handoff を実行 ④ 実行方法を改善 latency / token usage / error ③ 分析 Agent が調査 平常時との差 Token cost の急増 Tool / Handoff の偏り 改善後の実行も同じ指標で比較し、改善ループを回す。 © LayerX Inc. 26
27. Coding Agent から得た知見 Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses Model は固定 変更するのは 周辺だけ → Harness を編集 実行して観測 実行軌跡を → Agent が読める分析データへ → Prompt / Tool / Middleware をファイル管理 整理 検証・巻き戻し 効かない編集は revert 参考: Terminal-Bench 2 の pass@1 が 69.7% → 77.0%。 人間が設計したハーネス（71.9%）を超えた © LayerX Inc. https://arxiv.org/abs/2604.25850 27
28. Coding Agent から得た知見 鍵は、3つの Observability Component Harness をファイルの集合として表現 エラーの型ごとに直すファイルが決まる。編集は Git 履 歴で追跡し、いつでも revert できる © LayerX Inc. Experience 実行軌跡を Agent が読める分析データへ整理 実行軌跡（数百万 token） ↓ 圧縮 タスクごとの失敗分析 ↓ 集約 ベンチマーク全体の概要 Agent は概要から必要な箇所だけ drill-down して読む Decision 編集に予測を付け、実測で検証 編集 + 予測 「task 3, 7 が改善するはず」 ↓ 次ラウンドで実測 ✓ 当たり → 採用 ✗ 外れ → revert 効果の判定は自己申告ではなく、必ず実測値との照合で 行う 28
29. Coding Agent から得た知見 改善の効果は、実測でしか分からない 改善自体は確かに起きる SWE-bench verified でも成功率 75.6%（token は 32% 削減） 別のモデルに載せ替えても +5〜10pp 改善 Agent の自己申告は当てにならない 「この編集でどこが悪化するか」の予測は precision 11.8%（ほぼ盲目） 「効いたはず」では判断できない Agent 自身が効果を観測できる状態を作ることが、 改善ループの土台になる © LayerX Inc. 29
30. Coding Agent から得た知見 Coding Agent の評価・改善を OTel で回す取り組みを始めている FDE が運用する Workflow 構築・改善サイクル。この評価と改善の観測を、OTel の上で作る。 © LayerX Inc. https://speakerdeck.com/cipepser/layerx-fde-practices?slide=15 30
31. Content capture と機密性 注意：観測を増やすほど、機密も Trace に乗る Prompt / Output 全文・Source code / Shell output・Tool 入出力全文・環境変数は、 最初から記録しない（default-off） 記録が必要な場合だけ、allowlist・redaction・retention・access control・外部 artifact への参照を設計する © LayerX Inc. 31
32. 明日から始める最小セット まず Trace から始め、Metrics・Logs へ広げる Trace で Agent / Workflow / LLM / Tool の実行経路を残す Metrics で latency・token usage・error の傾向を継続的に見る Logs で個別イベントの詳細を Trace と関連付ける © LayerX Inc. 32
33. まとめ まとめ AI Agent は実行経路が動的で、最終結果や Status だけでは失敗・無駄・品質問題を判 断できない GenAI Semantic Conventions で Agent / LLM / Tool / Retrieval を共通の Span として記 録し、W3C Trace Context で既存の分散 Trace へつなぐ Trace の Status・duration・usage と Evaluation を関連付けると、失敗の混入地点や無 駄な loop を調べられる 観測データを共通化して資産として蓄積すれば、障害調査・品質評価・改善・別の Agent による分析へ利用の幅が広がる © LayerX Inc. 33
34. 今日話していないこと 今日話していないこと SDK / Agent Framework ごとの計装コード・OpenTelemetry Collector / Exporter / Backend の構成・Sampling・Batching・Retention・Redaction Evaluation の実装とデータセット設計・LLM-as-a-Judge の選定と評価・Dashboard / Query / Alert の設計 © LayerX Inc. 34
35. Appendix Appendix — Sources OpenTelemetry GenAI Semantic Conventions — commit c26a2c2 OpenTelemetry Semantic Conventions — Recording errors LangChain — How to Debug Coding Agents with LangSmith Traces LangSmith — Coding agent metadata contract Agentic Harness Engineering — arXiv v4 OpenLLMetry — Issue #3515（削除済み属性の未移行） OpenInference — Semantic conventions spec OpenLIT — semcov（sdk/python） Datadog — LLM Observability and OTel semantic conventions Langfuse — OpenTelemetry integration Google ADK — Observability / Traces Vercel AI SDK — Telemetry Pydantic Logfire — Issue #1586（legacy 混在の自認） © LayerX Inc. 35
36. Appendix — Metrics Metrics ：token 使用量 ：クライアント操作の所要時間 / ：streaming の応答特性 / / ：Agent 実行の時間と回数 ：Tool 実行の所要時間 ：推論サーバー側の request duration・time_to_first_token など gen_ai.client.token.usage gen_ai.client.operation.duration gen_ai.client.operation.time_to_first_chunk gen_ai.invoke_agent.duration time_per_output_chunk inference_calls tool_calls gen_ai.execute_tool.duration gen_ai.server.* © LayerX Inc. gen-ai-metrics.md 36
37. Appendix — Events Events gen_ai.client.inference.operation.details event ：推論の入出力とパラメータを記録する ：評価結果を記録する event 主な属性は gen_ai.input.messages / gen_ai.output.messages / gen_ai.system_instructions / gen_ai.tool.definitions 入出力本文は Opt-In。PII を含み得るため、計装はデフォルトで記録しない gen_ai.evaluation.result © LayerX Inc. gen-ai-events.md 37
38. Appendix — Exceptions Exceptions ：クライアント操作中の例外を記録する event 属性は exception.type / exception.message / exception.stacktrace 重大度は WARN（severity number 13）で記録する gen_ai.client.operation.exception © LayerX Inc. gen-ai-exceptions.md 38