AI システムの可観測性は Token の請求書だけではない

従来のサービスで問題が起きたとき、私たちはステータスコード、レイテンシ、エラースタックを確認します。AI アプリケーションでもこれらの指標は重要ですが、最も大切な問いに答えるには不十分なことがよくあります。

モデルはなぜこの選択をしたのか。

答えは一つのログにはありません。ユーザーの目標、コンテキストの組み立て、モデルの判断、ツールの実行、最終結果までのチェーン全体にあります。

まず四種類の失敗を区別する

すべての失敗を「モデルの性能が悪い」と記録してしまうと、チームは具体的な行動を取れません。少なくとも次の四つを区別する必要があります。

1. 入力の失敗

ユーザーの目標が不完全、またはタスクの完了に必要なコンテキストをシステムが取得できていません。この場合、モデルをアップグレードしても通常は解決しません。

2. 推論の失敗

コンテキストは正しいものの、モデルが誤った経路を選び、制約を見落とし、あるいは早すぎる結論に到達しています。

3. ツールの失敗

モデルの選択は正しいものの、権限、ネットワーク、パラメータ、外部状態などの理由で実行に失敗しています。

4. 伝達の失敗

内部の作業は完了しているのに、最終回答が結果、制約、次のステップを明確に説明できていません。

これら四つの問題は、プロダクト、プロンプト設計、プラットフォームエンジニアリング、インタラクション設計という異なる担当者を必要とします。可観測性の最初の価値は、問題を正しい人へ戻すことです。

一つの実行には共通の Trace が必要

各ユーザーリクエストには安定した trace_id を割り当て、モデル呼び出しとツール実行をつなぎます。

type AgentEvent = {
  traceId: string
  spanId: string
  parentSpanId?: string
  type: 'model' | 'tool' | 'handoff' | 'result'
  startedAt: string
  durationMs?: number
  status: 'running' | 'ok' | 'error'
}

ツール呼び出しは、モデル判断の外部表現です。呼び出した理由を残さず戻り値だけを記録すると判断コンテキストを失います。プロンプトだけを保存してツール結果を残さなければ、実行が意図どおりだったか判断できません。

観測は無制限な収集を意味しません。生のプロンプトには個人情報、認証情報、業務データが含まれる可能性があります。より安全な方法は次のとおりです。

• デフォルトでは構造化メタデータを記録する。
• 本文はフィールド単位でマスキングする。
• デバッグ用サンプルには短い保存期間を設定する。
• ユーザーや事業者が学習・分析への不参加を明示的に選べるようにする。
• ログにシークレットや完全な個人識別情報を保存しない。

品質指標をタスクに近づける

Token、レイテンシ、モデルエラー率はプラットフォーム指標ですが、ユーザーが結果を得られたかは示せません。

コード修正 Agent にとって、より意味のある指標は次のようなものです。

単なる呼び出し回数より「有効なツール呼び出し」が重要です。一度の正確な検索が、十回の推測的な読み取りを置き換えることがあります。

評価を日常的なフィードバックへ変える

オフライン benchmark はモデルのバージョン比較には役立ちますが、実際のワークフローすべてを網羅できません。持続可能な評価セットは、本番環境の価値あるサンプルから作ります。

1. 明確に成功した実行と明確に失敗した実行を集める。
2. 判断構造を保ちながら個人情報を削除する。
3. 総合点だけでなく、失敗の種類をラベル付けする。
4. プロンプト、モデル、ツールを変更したときに再実行する。
5. 結果品質、コスト、レイテンシを同時に比較する。

評価セットは最初から大規模である必要はありません。境界が明確で安定して再現できる二十件のケースは、出所が曖昧な二千件のサンプルよりも、エンジニアリングを導くことがあります。

人のための可観測性

最後の観測レイヤーはダッシュボードではなく、プロダクトの画面にあります。

Agent がファイルを読み、承認を待ち、デプロイを実行しているとき、ユーザーはどの段階にいるのかを知る必要があります。良いステータス更新は内部思考を垂れ流すのではなく、次を伝えます。

• 現在何を完了しようとしているか。
• すでに何を確認したか。
• ユーザーの行動が必要か。
• どのリスクがまだ残っているか。

この可視性は、システムの信頼性に対するユーザーの判断を直接変えます。数十秒かかっても過程が明確なタスクは、十秒後に突然不透明な結果を返すタスクより安心できることがあります。

説明可能であることは、すべてを公開することではない

AI システムは内部のすべての token をユーザーへ見せる必要はなく、機密コンテキストをそのままログに書くべきでもありません。必要なのは、十分に明確な因果チェーンです。

ユーザーの目標
  → どのコンテキストを使ったか
  → どのツールを選んだか
  → ツールがどの状態を返したか
  → 最終的にどの結果を届けたか

このチェーンを検索、比較、再現できるようになって初めて、チームは「時々とても賢い」を「長期的に信頼できる」へ変えられます。