メインコンテンツへスキップ
EastBraver Labs

Guides

AI AgentのObservabilityとTraceとは — 判断と実行の経路を追う

AI AgentのTrace・Span・Log・Metricを整理し、Model呼び出し、Tool実行、Outcomeを本番で調査・評価できる観測設計を示します。

(更新日:)6分で読めます
#ai-agent#software-engineering#evaluation

AI AgentのObservabilityとTraceは、利用者のRequestから最終結果まで、Modelが何を判断し、どのToolを呼び、外部システムがどう変わったかを、一回の処理の実行経路として追跡・調査できる状態にすることです。

Agentが「返金しました」と自然に答えていても、返金APIは失敗しているかもしれません。逆に、返答が短くても、正しい相手へ正しい処理を完了できている場合があります。

最終回答だけをLogへ残しても、Agentが正しい経路で処理したかは分かりません。途中で権限外のToolを呼んでいないか、実行経路とOutcomeを一緒に追う必要があります。

Traceは一回の処理を端から端まで結ぶ

OpenTelemetry Trace APIでは、Traceを構成する操作単位をSpanとして扱います。AI Agentでも、既存の分散Tracingを土台にできます。

MermaidAgent処理のTrace階層User requestからModel、Tool、外部API、OutcomeまでのTrace

1件のUser request spanの下にAgent runを置き、その内部へModel callとTool callを関連付けます。外部API呼び出しと最終Outcomeまで同じTraceで追うと、遅延や失敗の発生箇所を特定できます。

  1. User request spanからAgent run spanを開始します。
  2. Agent runの配下にModel call spanとTool call spanを記録します。
  3. Tool callから外部APIを追跡し、最後にOutcomeまたはResponseを記録します。

一つのTrace IDで、次を結び付けます。

  • User RequestとSession
  • Agent RunとStep番号
  • Model Request、Model ID、Prompt Version
  • Tool名、入力、実行結果
  • 下流APIやDatabase操作
  • Approval、Policy判定、拒否
  • 最終回答と業務Outcome

Log、Metric、Trace、Transcriptは役割が違う

観測情報主な用途
Log個別Event、Error、監査記録を読む
MetricError率、Latency、Token、費用の傾向を見る
Trace一Request内の因果関係と時間を追う
TranscriptModelとToolのMessage列を評価する
Audit log誰が何を許可・実行したかを証跡として残す

すべてを一つの長いLog messageにすると、検索、Retention、Access controlを分けられません。目的ごとに保存先と閲覧権限を決めます。

AI Agent固有のSpanを残す

OpenAI Agents SDKのTracingは、LLM generation、Tool call、Handoff、Guardrail、Custom eventをTraceへ記録します。AgentCore Observabilityも、OpenTelemetry互換のTelemetryでAgentのStep、Session、Latency、Token Usage、Errorを観測します。

最低限、次の属性を検討します。

  • agent.nameとAgent Version
  • model.provider、Model ID
  • Prompt / Context Version
  • Input / Output Token
  • Tool名とTool Version
  • Retry回数と終了理由
  • Policy decisionとApproval ID
  • Error type
  • Outcome ID

Framework固有のFieldだけへ依存すると、移行時に過去Traceと比較しにくくなります。自社の共通属性を決めます。

なお、TraceはRequest単位の実行経路を残す記録です。その時点でどのModel・Runtime・Dataへ依存していたかという構成側の記録は、AI BOMで扱います。

機微情報をそのまま記録しない

Prompt、Context、Tool引数、Tool結果には、個人情報、Credential、社内文書が含まれます。詳細なTraceを有効にするほど、観測基盤自体が情報漏えい経路になります。

  • API keyとAccess TokenをMaskする
  • Payload本文をDefaultで保存しない
  • Field単位のAllowlistを使う
  • Tenantと環境を分離する
  • Retentionを決める
  • 閲覧権限と監査を持つ
  • Debug時の一時的な詳細取得を期限付きにする

「調査に必要かもしれない」で全文保存をDefaultにしません。保存しない場合に何を再現できなくなるかも明示します。

最終回答ではなくOutcomeまで追う

Support Agentが「返金しました」と回答しても、返金APIが失敗している可能性があります。逆に、回答文が短くても、正しいCustomerへ正しい処理を行えていれば業務Outcomeは成功です。

AI Agent評価では、Transcriptと外部状態を使ってOutcomeを判定します。Traceは評価データを集める基盤ですが、Traceがあるだけで評価基準が決まるわけではありません。

Alertは操作可能な失敗へ結び付ける

Token使用量が増えた、Tool callが多い、といったMetricだけでは対応を決めにくい場合があります。

  • Task failure率が基準を超えた
  • Permission deniedが特定Toolで急増した
  • 同じToolを一定回数以上繰り返した
  • Userあたりの費用上限へ達した
  • Approval待ちが期限を超えた
  • 外部更新とAgent回答が不一致になった

誰が何を確認し、Agentを止めるか、ModelやPromptを戻すかまでRunbookへつなげます。

よくある誤解

会話履歴を保存すればObservabilityになる

会話だけでは、下流API、権限判定、Retry、外部状態の変化を追えません。Trace IDで実行経路を結びます。

Traceをすべて保存すれば再現できる

Model出力は確率的で、Provider側のModel更新もあります。Model ID、Prompt Version、入力、外部状態を残しても完全再現できない場合があります。

OpenTelemetryを入れれば評価できる

Telemetryは記録の形式です。Task成功、許容失敗、品質基準は別に定義します。

DebugのためならPrompt全文を保存してよい

個人情報、秘密情報、Retention要件を先に確認します。観測基盤へのAccess controlも本番システムの一部です。

EastBraver Labsの判断基準

EastBraver Labsでは、一つのAgent RunをTrace IDで端から端まで追えるようにします。

Model、Prompt、Context、Tool、Policy、Outcomeを分け、失敗箇所を特定できる属性を残します。

本文Payloadは最小限にする。必要な場合もMask、Retention、閲覧権限を先に決めます。

観測項目を増やすことが目的ではありません。

異常時に止める、戻す、評価セットへ失敗を追加する。その判断へつながるTelemetryを残します。

関連記事