AI Agent をどう観測するか - AI Workforce における OpenTelemetry 計装の実践 / How to Observe AI Agents: Implementing OpenTelemetry for the AI Workforce

Transcript

1. AI Agent をどう観測するか - AI Workforce における OpenTelemetry 計装の実践 OpenTelemetry Meetup / 2026/05/21 Joe / @joe_yuzupi
2. 自己紹介
3. Joe (Yuzuru Ohira) © LayerX Inc. About Me 株式会社 LayerX Ai Workforce 事業部 Platform Enablement グループ マネージャ ー 趣味: ゴルフ シングルになりたい。 。 。 3
4. 事業紹介 © LayerX Inc. 4
5. Engineering Hiring Deck © LayerX Inc. We're hiring! Engineering Hiring Deck 5
6. バクラク事業部でも採用しています！ © LayerX Inc. We're hiring! Bakuraku Engineering Team Deck 6
7. 本日の流れ
8. アジェンダ © LayerX Inc. 本日の流れ AI Agent トレーシングにおける OpenTelemetry の現在地 Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 8
9. 話すこと、話さないこと © LayerX Inc. 話すこと、話さないこと 話すこと AI Agent トレーシングにおける OpenTelemetry の現在地 主要 framework が実際に出す trace model Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 話さないこと GenAI semconv の属性を網羅的に読む話 個別 SaaS への連携方法 Langfuse 等のLLM Opsツールの話 9
10. AI Agent トレーシングにおける OpenTelemetry の現在地
11. 2026 年時点の現在地 OTel GenAI agent spans は Development status。AI Agent tracing は標準化済みではなく、各 framework の trace を OTel で扱える形にそろえている途中。 framework 側 OTel 側 © LayerX Inc. AI Agent トレーシングにおける OpenTelemetry の現在地 agent / tool / handoff / workflow を独自 概念として持つ trace は dashboard や runtime の実行モデ ルに寄る OTel export はあるが、span 名や属性は framework ごとに違う agent / workflow / tool / retrieval の span と operation を定義 agent・workflow spans は Development status 独自 span をそのまま見るか、共通の名 前・属性に変換して見るかを設計する https://opentelemetry.io/docs/specs/semconv/gen-ai/ 11
12. OTel GenAI semantic conventions GenAI semconv は gen-ai-spans と gen-ai-agent-spans の 2 ドキュメントにわたって定義されている。 Agent spans Development · gen-ai-agent-spans create_agent / invoke_agent / invoke_workflow agent の生成・実行、workflow の起動。CLIENT または INTERNAL span として定義。 Inference spans gen-ai-spans chat / text_completion / generate_content LLM への inference call。token usage / model を載せる。 Embeddings span gen-ai-spans embeddings embedding 生成 call。 Retrieval / Execute tool gen-ai-spans retrieval (CLIENT) / execute_tool (INTERNAL) vector store 検索と tool 実行の実行単位。 © LayerX Inc. AI Agent トレーシングにおける OpenTelemetry の現在地 gen-ai-spans / gen-ai-agent-spans 12
13. 例: AI Agent のフロー（チャット型） チャット型 AI Agent（例: Claude Code / Cursor chat / ChatGPT など）は、ユーザー入力を受け取り LLM が planning し、必要に応じて tool を呼び、結果を統合して応答を返す。 I/O 1. 入力 ユーザーの質問・指示を 受け取る → LLM 2. Planning 何を、どの順序でやるか 組み立てる → TOOL 3. Tool call 検索 / API / DB など外部 副作用を実行 → LLM 4. 統合 tool 結果を読み、次の判 断を行う → I/O 5. 応答 最終結果をユーザーに返 す 3 - 4 はループすることがある（ReAct / 多段 tool call / sub-agent 呼び出し） 。 © LayerX Inc. チャット型のAIエージェントの例 13
14. チャット型 AI Agent の trace 例 invoke_agent (1 turn) └ invoke_agent (sub: コード分析) └ execute_tool (Read 設定ファイル) └ chat (planning) └ execute_tool (Edit ソース) └ invoke_agent (sub: 検証・応答) └ chat (検証・再計画) └ execute_tool (Bash: pytest) └ execute_tool (Write レポート) © LayerX Inc. チャット型 AI Agent の trace 例 1.2s 480ms 70ms 220ms 95ms 650ms 170ms 265ms 150ms 14
15. framework 別のスパン定義 Framework スパン定義 semconv との差分 Claude Agent SDK interaction / llm_request / tool / hook llm_request に gen_ai 属性を一部付与。span 名 は全て独自。 OpenAI Agents SDK agent / generation / function / handoff / guardrail operation.name なし。OTel bridge は自前実装。 handoff は semconv 未定義。 LangGraph / LangSmith llm / chain / tool / retriever LangSmith の run_type。semconv の operation.name とは別体系。 Google ADK invoke_agent / execute_tool / generate_content かなり semconv に準拠している。 同じ "agent trace" でも、root span と子 span の切り方は framework の runtime model に強く依存する。 © LayerX Inc. フレームワーク別のスパン定義 Claude Agent SDK: https://code.claude.com/docs/en/monitoring-usage OpenAI Agents SDK: https://openai.github.io/openai-agents-python/tracing/ LangGraph / LangSmith: https://docs.langchain.com/langsmith/run-data-format Google ADK: https://adk.dev/observability/traces/#traces-schema 15
16. サンプル: 服装アドバイザー アプリ概要 処理フロー 同じアプリを Claude Agent SDK / OpenAI Agents SDK / manual 計測の 3 パターンで実装し、trace の見え方を比較する 出力例 © LayerX Inc. サンプルアプリ 今日の天気を取得 カレンダーから予定を取得 服装アドバイスを生成 16
17. Claude Agent SDK 各ユーザープロンプトは claude_code.interaction がルートスパンとなり、LLM の呼び出し（ claude_code.llm_request ）や tool 呼び出 し（ claude_code.tool ）は子スパンとしてネストされる。 © LayerX Inc. Claude Agent SDK https://code.claude.com/docs/ja/monitoring-usage 17
18. claude_code.interaction の例 © LayerX Inc. AI Agent トレーシングにおける OpenTelemetry の現在地 18
19. OpenAI Agents SDK OpenAI Agents SDK では agent / generation / function が実行単位として並び、Agent の turn と LLM 呼び出し、関数呼び出しの関係 を trace 上で追える。 例: 服装アドバイザーの 1 workflow。root span の下に task / agent / turn / generation / function がネストされ、framework の runtime model がそのまま span 構造に表れる。 © LayerX Inc. OpenAI Agents SDK 19
20. OTel semconv manual 計測 OTel SDK を使って手動で計装した形。 invoke_agent / chat / execute_tool を直接 span として作成することで、semconv 準拠のト レースを出力できる。エージェントループやネスト構造は自身で設計する必要がある。 © LayerX Inc. AI Agent トレーシングにおける OpenTelemetry の現在地 20
21. 同じ OTel でも trace の作り方が違う 課題は「OTel に出せるか」ではなく、何を root span にして、どの単位を子 span にするかが framework ごとに違うこと。 そろっていること そろっていないこと © LayerX Inc. AI Agent トレーシングにおける OpenTelemetry の現在地 OTLP で送れる trace / span として見える model call / tool call / duration / token usage を持てる backend で検索・集計できる root span の単位 agent / workflow / run / task の名前 handoff / guardrail / hook の表現 payload を残す粒度 conversation / session の付け方 21
22. Ai Workforce における AI Agent アプリケ ーションの OpenTelemetry 計装の実践
23. Ai Workforce AI Agent アーキテクチャ © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 23
24. Ai Workforce のトレーシング採用 Ai Workforce では、トレーシング基盤として OpenTelemetry を採用している。 invoke_workflow {workflow} └ invoke_agent {orchestrator} └ db_read {task_fetch} └ chat {orchestrator} └ invoke_agent {assistant} └ chat {model} └ db_read {user_context} └ execute_tool {external_api} └ execute_tool {external_api} └ chat {model} └ db_write {result_save} → OTLP で Datadog Agent 経由で Datadog に転送 © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 15.3s 14.8s 80ms 1.1s 13.5s 5.5s 120ms 90ms 70ms 4.8s 60ms 24
25. 計装パッケージを内製 共通の telemetry パッケージに計装ロジックを集約している。Datadog Auto-Instrumentation（自動計測）と OTel 手動 span を組み合わせたハイブ リッド構成で、計測を誰でも同じ形式で導入できるようにしている。 パッケージが担う役割 パッケージを使う側 アプリは decorator を置くだけで計測が入る 計装ロジックはパッケージ側で一元管理。各アプリは再実装不要で最新の semconv に追随できる。ローカルでは OTel 自動計測も利用可能に しているため、テレメトリーバックエンドが変わっても即時対応できる。 © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 tracer / exporter の初期化 semconv 準拠の span 作成・属性付与 framework 独自 span → semconv 変換 パッケージ単位でのバージョン管理 25
26. Web アプリケーションと AI Agent の境界 AI Agent は Web アプリケーションの一部として動く。Ai Workforce では Redis Stream を境界に、Web App / Assistant Agent 側と AI Agent workflow 実行エンジン側に分かれる。 Web App / Assistant Agent 側 Trace A（HTTP span + GenAI span） → Redis Stream 境界 → AI Agent workflow 実行エンジン側 Trace B（GenAI span） Redis Stream を境界に trace が 2 本に分断される。Web App のレイテンシと AI Agent の処理時間を独立して観測できるが、 「1 件のリクエスト全体」を追うには 2 本の trace を繋 ぐ手段が必要になる。 © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 HTTP request 受付 ビジネスロジック処理 Redis Stream へ workflow を publish Stream から workflow を consume invoke_workflow / invoke_agent LLM call / tool call 26
27. Span Links Span Links — 親子関係を作らずに、別 trace の span を「関連がある」として参照する OTel の仕組み。 非同期境界（キュー・メッセージブローカー等）を越えて分断された 2 本の trace を繋ぐのに使う。 Trace A（Agent 側 / Producer） 新規 invoke_agent chat publish ↑ traceparent / tracestate をメッセージに埋め込む メッセージ payload traceparent: 00-abc… tracestate: dd=s:1… → Trace B（Workflow 実行エンジン側 / Consumer） 新規 invoke_workflow ↑ payload から取り出し Span Link として設定 task.execute operation.execute Span Link（参照） 親子継承（trace propagation）との違い: propagation は B を A の子にする → 1 本の長い trace になり、A の終了が B 完了まで待つ。Span Links なら 2 本のまま独立して観測で き、後から相互参照できる。 © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 https://opentelemetry.io/docs/concepts/signals/traces/#span-links 27
28. Span Links の実装 Producer 側はメッセージヘッダーに traceparent を注入、Consumer 側はそれを取り出して 親にせず Span Link として設定する。 Trace A — Producer 側（Agent） Trace B — Consumer 側（Workflow 実行エンジン） © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 https://tech.layerx.co.jp/entry/ai-agent-span-links#Python-%E3%81%AE%E4%BE%8B 28
29. Span Links — 実際の連携 © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 過去登壇資料: speakerdeck.com/yuzujoe/observability-of-ai-agent-agentic-workflow ブログ記事: tech.layerx.co.jp/entry/ai-agent-span-links 29
30. AI Agent 箇所の観測について AI Agent 箇所では、LLM の呼び出し・ツール実行・エージェントループを中心に以下を観測する。 パフォーマンス コスト・品質 OTel 側の GenAI agent spans はまだ Development status のため、この観点では Datadog LLM Observability を使っている。 計装パッケージを内製の章と同様にこちらもいつ Otel 側がGAしても切り替えられるように整備済み。 © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 LLM レイテンシ（TTFT / 総時間） ツール実行時間 エージェントターン数 ワークフロー全体の所要時間 input / output トークン数 ツール呼び出し成功率 リトライ回数 30
31. trace に残す情報を選ぶ AI Agent の trace は、原因調査に必要な情報と、残してはいけない情報の境界を決める必要がある。 説明に必要な情報 原則として残さない情報 © LayerX Inc. Ai Workforce における AI Agent アプリケーションの OpenTelemetry 計装の実践 agent / tool / model / workflow の識 別子 token usage / duration / retry / status tool result の成否、件数、サイズ prompt template / policy / toolset の version prompt / completion 本文 tool argument / tool result の生データ 顧客データや検索結果本文 必要な場合だけ sampled な開発環境で opt-in 31
32. 今後の課題 © LayerX Inc. 今後の課題 複雑性が上がった時の観測設計 Long Running Task の trace / metric / log の分担 イベント駆動で動く際の計測粒度 非同期境界をまたぐ workflow 全体の関連付け agent / tool / workflow のどの単位でコスト・品質・失敗を集計するか 評価の仕組み 32
33. まとめ © LayerX Inc. まとめ OTel GenAI semconv は発展途上だが、共通語彙として trace 設計の土台になる。 非同期境界や Long Running Task では、trace を無理に 1 本にせず、Span Links や metrics と組み合わせて運用で追える形にする。 観測設計は、複雑な AI Agent の挙動を説明し、改善できる状態を作るための土台にな る。 33
34. ご清聴ありがとうございました