エージェント可観測性｜結果だけ見ると原因は4通り、途中を記録すると1通りに絞れた

エージェント可観測性とは何を見ることなのか

答えが正しいかではなく、そこに至る途中で何を判断し何を呼んだかを見ることです。エージェントは失敗しても止まらないため、結果だけでは足りません。

エージェント可観測性で見たいのは、答えに至るまでの過程です。普通のアプリの監視と目的が違うので、まずそこを整理します。

普通のアプリは失敗すると止まる

通常のアプリでは、処理が失敗すればエラーになって止まります。ログにエラーが残るので、失敗したこと自体はすぐ分かります。

エージェントは失敗しても答えを返す

エージェントは違います。ツールの呼び出しに失敗しても、その結果を受けて「見つかりませんでした」というそれらしい答えを組み立てて返します。処理としては正常終了です。

つまり、成功した実行と失敗した実行が外から見ると同じ形になってしまう。ここが可観測性を難しくしている点です。

記録の形式については標準化が進んでいます。OpenTelemetryが生成AI向けの記述規約を整備しており、現在は専用のリポジトリへ移管されました。エージェントの処理を記録するための項目も、そこで定義されています。

原因の候補が4通りから1通りに絞れた

同じ失敗を、結果だけ記録した場合と各段階を記録した場合で追いました。絞り込める範囲がはっきり変わります。

エージェント可観測性の効果を確かめるため、実際に試しました。注文を検索するエージェントが「見つかりません」と答えた場面を再現しています。

下のコードは読み飛ばして大丈夫です。同じ処理を、記録を取らない場合と取る場合の2通りで実行しています。

function runAgent(trace) {
  const rec = (step, data) => trace && trace.push({ step, ...data });

  rec('plan',      { ok: true,  chosenTool: 'search_orders', reason: '注文の検索が必要と判断' });
  rec('tool_call', { ok: false, tool: 'search_orders', args: { status: 'ACTIVE' },
                     error: 'status に ACTIVE は存在しない（有効値: OPEN/CLOSED）' });
  rec('answer',    { ok: true,  text: '該当する注文は見つかりませんでした' });

  return { finalAnswer: '該当する注文は見つかりませんでした', userSatisfied: false };
}

--- 記録なし: 結果だけを見る ---
  最終回答: 該当する注文は見つかりませんでした
  利用者の評価: 未解決
  分かること: 「答えられなかった」という事実のみ
  原因の候補: 質問の解釈ミス / ツール選択ミス / 引数ミス / データ不在 の4通り
--- 記録あり: 各段階を残す ---
  OK  plan       注文の検索が必要と判断
  NG  tool_call  search_orders({"status":"ACTIVE"}) → status に ACTIVE は存在しない（有効値: OPEN/CLOSED）
  OK  answer     該当する注文は見つかりませんでした
  失敗した段階: tool_call
  原因の候補: 1通り（引数の値が不正）

絞れました。4通りから1通りです。しかも直し方まで分かります。有効な値の一覧をツールの説明に書けば済む話でした。

答えは正常、途中だけが失敗している

注目してほしいのは、記録ありの出力で最後の段階がOKになっている点です。答えを組み立てる処理自体は正常に動いています。失敗したのは真ん中だけです。

結果だけを見ていると、この真ん中が見えません。「答えられなかった」という事実から、原因を推測するしかなくなります。

記録すべきものは3つ

上の例から分かるとおり、必要なのは3点です。どう判断したか、何を引数に渡したか、何が返ってきたか。この3つがあれば、失敗の箇所と理由がその場で分かります。OpenTelemetryの属性一覧にも、エージェントの説明・識別子・操作名といった項目が定義されています。

実際に運用するとき何を残すのか

全部を残すと量が膨らみます。判断・引数・結果を常に残し、やり取りの本文は失敗したときだけ残すのが現実的です。

エージェント可観測性を実際に組むときは、記録の量と使い道の釣り合いを取る必要があります。全部残せばよいというものではありません。

常に残すもの

1. どのツールを選んだかと、その理由の要約
2. ツールに渡した引数。これが最も原因になりやすい
3. ツールから返ってきた結果。成功か失敗か、失敗ならその内容
4. 使ったトークン量。費用の把握と、履歴の膨張の検知に使う

失敗したときだけ残すもの

やり取りの本文は量が大きいので、常に保存すると保管費がかさみます。失敗した実行だけ本文を残す方法にすると、量を抑えつつ調査には困りません。

ただし個人情報の扱いには注意が要ります。利用者の入力がそのまま保存されるため、保存する範囲と期間を先に決めておく必要があります。

標準規約は整備の途中

記録の項目名を独自に決めると、後で分析ツールに載せ替えるときに苦労します。OpenTelemetryの生成AI向け規約に合わせておくと移行が楽になります。

ただし現状では、この規約は専用のリポジトリへ移管され、元のページは維持されていないと明記されています。整備が続いている段階なので、採用するときは最新の定義を確認してください。

費用の把握についてはエージェントのコスト制御の記事で扱っています。トークン量の記録は、可観測性とコスト管理の両方で使えます。