私は小規模な体制で運営しています——リードの適格性確認、ドキュメント処理、カスタマーサポートのトリアージなどを扱う、いくつかのAIエージェントです。大規模に回しているわけではありません。とはいえ、稼働中のエージェントが数個しかないとしても、それらのデバッグがこの仕事の中で最も大変な部分の1つであることには変わりありません。
従来のソフトウェアのバグは予測可能です。エージェントのバグはどうでしょう？ 特定の組み合わせ——ユーザー入力、APIのレイテンシ、モデルの温度が絶妙に揃ったときにだけ表面化するかもしれません。ここでは、現実の世界でAIエージェントをデバッグして学んだことをまとめます。
エージェント・デバッグの問題点
通常のAPIエンドポイントが失敗したときは、ステータスコードとスタックトレースが得られます。エージェントが失敗したときはどうでしょう——自信満々に誤った回答が返ってくるかもしれません。あるいは、ツール呼び出しのループに陥るかもしれません。さらに厄介なのは、技術的には成立しているのに、不要なAPI呼び出しを47回も行ったせいで、結果として費用が$4.50もかかってしまうケースです。
根本的な課題は、エージェントが自律的な判断を行う非決定論的なシステムであることです。すべてのシナリオをカバーするユニットテストを書くだけでは足りません。まったく別のアプローチが必要になります。
シナリオ1: 静かに間違う回答
最も怖い失敗モードです。エージェントがタスクを完了し、結果を返し、皆が次へ進む——ただし、その結果が間違っている、というパターンです。
私は、請求書の金額を抽出するはずのドキュメント処理エージェントを持っていました。最初は素晴らしく機能していましたが、クライアントが少し違う形式の請求書を送ってくるようになってから数か月後に破綻しました。エージェントは自信満々に数字を抽出しているのですが、それが明細行の合計であって、請求書の合計ではありませんでした。エラーも警告もありません。
何が役に立ったか: エージェントの出力に対するアサーションチェックを追加しました。「何か返すか」だけでなく、「その値が期待される範囲に入っているか」を確認します。さらに、事後に意思決定を監査できるように、推論の全チェーンをログ出しするようにもしました。このようなドリフト（ズレ）系の問題を、増幅する前に見つけることができるようにするには、しっかりしたエージェントの可観測性（agent observability）を用意しておくことが決定的でした。
シナリオ2: 暴走するツール呼び出しループ
ツールを呼び出せるエージェントは、ときどきループに固まってしまいます。ツールAを呼び、結果を得て、それでもエージェントが「少し違うパラメータで再度ツールAを呼ぶ必要がある」と判断し、同じことを延々と繰り返します。
これはたいてい、エージェントのプロンプトが終了条件を明確に定義していないとき、またはツールが曖昧な結果を返して、エージェントがそれを「直そう」とし続けてしまうときに起こります。
何が役に立ったか: セッションごとのツール呼び出し回数にハードな上限を設けました。私は各タスクで上限を15回に制限しています。エージェントがその上限に到達したら停止し、人のレビュー対象としてフラグを立てます。加えて、トレーシングを使ってツール呼び出しの全シーケンスを可視化するようにしました。タイムライン表示でエージェントのツール呼び出しをトレースすることができるようにすると、エージェントが空回りしている様子が一目で分かるようになりました。
シナリオ3: 複数エージェントにまたがる連鎖的な失敗
お互いに依存する複数のエージェントがある場合、あるエージェントの失敗が、想定外の形で連鎖することがあります。エージェントAがドキュメントを要約し、エージェントBがその要約を使って意思決定をし、エージェントCがその意思決定に基づいて行動する——エージェントAの要約が微妙にズレているだけでも、最終的にろくでもない結果につながる、いわゆる伝言ゲームが発生します。
何が役に立ったか: エージェントの引き渡し（handoff）をAPI契約（contract）のように扱うことです。各エージェントが、処理を進める前に入力を検証します。さらに、すべてのエージェントにまたがってリクエストに追従するトレースIDを追加しました。鎖の終点で何かがうまくいかなかったときでも、発端となったエージェントまで追跡できます。
実践的なログ解析のパターン
ここから先は、私が日々実際に使っているパターンです。
1. コンテキスト付きの構造化ログ。 すべてのエージェントのアクションを、次の情報とともにログ出しします。タスクID、エージェント名、呼び出しているツール、入力パラメータ、出力サマリー、レイテンシ、トークン数です。JSON形式で構造化されたログなら、後からこれらの次元すべてに対して横断的にクエリできます。
2. リトライのための差分ログ（diff logging）。 エージェントがツール呼び出しを再試行するときは、試行間で何が変わったのかをログに残します。ここにこそバグが潜んでいることがよくあります——エージェントが何かを修正しようとしているのに、その修正戦略が間違っている、という状況です。
3. タスクごとのコスト追跡。 これはデバッグというより会計の話に聞こえるかもしれませんが、思いがけないコストの急増は最良の早期警告シグナルの1つです。普段$0.03で済んでいるタスクが突然$0.30になったなら、エージェントの振る舞いに何か変化が起きています。私は単純な計算機でデバッグによるオーバーヘッドの推定コストを出し、どのタスクでも移動平均の3倍を超えたらアラートを出すようにしています。
4. 出力のサンプリング。 エージェントの出力の5〜10%をランダムに抽出し、人間のレビューに回します。自動チェックでは見つからない、静かに間違う回答を捕捉できます。
本番でのインシデント対応
本番環境でエージェントが何かを壊したときは、私の手順書（プレイブック）はこうです。
まず、その特定のリクエストのトレースを確認します。すべてのツール呼び出し、すべての意思決定ポイントを見てください。ほとんどの場合、全シーケンスを見られるようになれば、問題は明らかです。
次に、失敗が再現可能かどうかを確認します。エージェントの場合、再現できることもあれば、できないこともあります——同じ入力でも、次の実行では異なる振る舞いをするかもしれません。再現できない場合は、外部状態が関与していないかを調べる必要があります（APIレスポンス、DBの状態など）。
3つ目に、上流の変更を確認します。依存しているAPIが、そのレスポンス形式を変更したのでしょうか？ 誰かがシステムプロンプトを更新したのでしょうか？ モデル提供者が静かにアップデートしたのでしょうか？ 私の経験では、これらが最もよくある根本原因です。
実際に役立つツールとセットアップ
複雑な可観測性（observability）の基盤は不要です。私が実際に動かしているのは次のようなものです。
- 検索可能なストアに配送する構造化JSONログ
- エージェント間の境界を越えて伝播するトレースID
- ツール呼び出し、トークン数、タスクごとのコストに関する厳格な上限
- 妥当な閾値（しきい値）による自動出力検証
- エージェント出力の週次サンプルレビュー
重要な洞察は、エージェントのデバッグは、単一のプログラムをデバッグするよりも、分散システムをデバッグするのに近いということです。ログだけでなく、トレースが必要です。エージェントが何を決め、なぜそうしたのか、そしてその後に何が起きたのか——全体像を見通す必要があります。
まとめ
本番環境でAIエージェントをデバッグするのは本当に難しくて、まだ誰も完全に解決できているとは思いません。とはいえ、基本の「良いログ」「トレーシング」「出力検証」「コスト監視」が効く範囲はかなり大きいです。それらから始めて、基本では解決できない問題に遭遇したときだけ複雑さを追加してください。
あなたも本番でエージェントを運用しているなら、どんなパターンがうまくいったかぜひ聞かせてください。コメントを残すか、Twitterで私を見つけてください。
