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

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

Canonical URL: https://labs.eastbraver.com/guides/observability-tracing
Published: 2026-07-01
Updated: 2026-07-24
Category: field-guide
Tags: ai-agent, software-engineering, evaluation

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

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

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

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

[OpenTelemetry Trace API](https://opentelemetry.io/docs/specs/otel/trace/api/)では、Traceを構成する操作単位をSpanとして扱います。AI Agentでも、既存の分散Tracingを土台にできます。

### Agent処理のTrace階層

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

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

*User requestからModel、Tool、外部API、OutcomeまでのTrace*

一つの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、監査記録を読む |
| Metric | Error率、Latency、Token、費用の傾向を見る |
| Trace | 一Request内の因果関係と時間を追う |
| Transcript | ModelとToolのMessage列を評価する |
| Audit log | 誰が何を許可・実行したかを証跡として残す |

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

## AI Agent固有のSpanを残す

[OpenAI Agents SDKのTracing](https://openai.github.io/openai-agents-python/tracing/)は、LLM generation、Tool call、Handoff、Guardrail、Custom eventをTraceへ記録します。[AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html)も、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](/guides/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評価](/guides/ai-agent-evaluation)では、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を残します。

## 関連記事

- [AI Agent 時代に、エンジニアは何を設計する人になるのか](/blog/ai-development-20260706)
- [エージェント運用の検証が主題に](/digest/ai-digest-20260704)
- [評価基盤の外部依存を見直す日](/digest/ai-digest-20260706)
- [AIエージェント運用は堅牢性と統制へ](/digest/ai-digest-20260716)

## 検証範囲

- 一次情報: 公式ドキュメント / 設計面からの分析
- ローカル検証: コードは動かしていません
- 実運用: 関連するWeb業務システムの設計・運用経験をもとにしています

## 変更履歴

- 2026-07-24: Mermaid図にテキスト等価物を追加
- 2026-07-15: 検証範囲と根拠区分を明示
- 2026-07-01: 初版公開