エージェントが失敗したAPIを5回呼び続けた——バグはコードになかった

本番でバグが出た。エージェントが同じAPIコールを5回繰り返していた。習慣でまずコードを開いた。リトライロジックは正常。関数の流れもおかしくない。ログにはエラーひとつない。

コードに答えはなかった。トレースを開いて初めて、原因が見えた。

エージェントのコードは抜け殻だ

エージェントのソースコードを開くと、モデルの指定、ツールの一覧、システムプロンプト——だいたいそれだけだ。どのタイミングでどのツールを呼ぶか、どういう推論の順序で動くか、そういったことはコードに書いていない。

LangGraphベースのエージェントを運用しているチームが口を揃えて言う。「コードレビューでエージェントの品質は判断できない」と。

• 同じコード、同じ入力でも、毎回ツールの呼び出しパターンが変わる
• handleSubmit() のような関数と違って、分岐ロジックがコードに存在しない
• 同じクエリをGPT-5.2に10回投げると、ツール呼び出しの順序が一致するのは4割程度
• エラーが起きても、コードにバグがないため再現できない

これが本質的な変化だ。従来のソフトウェアでは、コード自体が振る舞いだった。エージェントでは、コードは足場に過ぎない。実際の振る舞いはランタイムで生まれる——モデルが受け取ったコンテキストを元に推論した結果として。

トレースが新しいソースコードになる

トレースは、エージェントが踏んだすべての足跡を記録する。各ステップで何を考え、なぜそのツールを呼んだか——すべてが残る。コードを読んで行っていたデバッグ、テスト、パフォーマンス分析は、今やトレースを通じて行うしかない。

エージェントがエラーメッセージを受け取って、それでも同じコールを繰り返すとき、それはコードのバグではない。推論の失敗だ。そしてそれはトレースにしか見えない。

• プロンプト変更前後のトレースを比較すると、推論の質の差が一目で分かる
• LangSmithでは、特定の地点のトレースをPlaygroundに読み込むことで、ブレークポイントを置くような感覚でデバッグできる
• 一本のトレースから、エージェントの推論がどこで狂ったか正確に特定できる——大量のログを積み上げても見えないものが

こう考えるとわかりやすい。従来のデバッグはレシピを読んでミスを探すことだ。エージェントのデバッグはキッチンの監視カメラ映像を見て、シェフがどこで間違えたかを確認することだ。レシピは完璧かもしれない。問題は実行の中にある。

テストの考え方が根本から変わる

従来のソフトウェアはデプロイ前にテストして終わりだった。エージェントは非決定的なので、本番で評価し続けなければならない。

トレースを収集して評価データセットを作り、品質の劣化やドリフトを検知するパイプラインがなければ、エージェントをスケールさせて運用することは不可能だ。

トレースベースの評価を取り入れたチームでは、タスク成功率に目に見える改善が出ている。パターンは一貫している——デプロイ前のどんなテストスイートでも予測できなかった障害モードが、トレースから浮かび上がってくる。

• 週次で本番トレースをサンプリングする自動評価パイプラインを作る
• デプロイ前テストだけで非決定的なシステムの品質を保証することはできない
• トレースなしの監視は、サーバーが起動しているかどうかだけを確認するようなものだ
• エージェントが「正常動作」しながら、完全に的外れなタスクをこなしていることがある——それを捉えられるのはトレースだけだ

コラボレーションもプロダクト分析もトレースで起きる

コードレビューはGitHubでやる。エージェントの判断のレビューはどこでやるのか。

その役割を担っているのが観測プラットフォームだ。チームはトレースにコメントし、特定の意思決定ポイントを共有し、プルリクエストをレビューしていたように、エージェントの推論をレビューしている。コラボレーションのモデルそのものが変わりつつある。

プロダクト分析も同じ構図だ。指標が「ユーザーの30%が不満を持っている」と示しても、トレースを開かなければ原因にたどり着けない。エージェントは自分の基準では正常にタスクをこなしていながら、ユーザーが本当に求めていたものを完全に外している可能性がある。

• Mixpanelのようなプロダクトアナリティクスツールとデバッグツールは、共通の基盤としてトレースに収束しつつある
• エージェントのツール呼び出しパターンを分析することで、ユーザーが本当に必要としている機能を逆算できる

結局のところ

エージェントの時代において、コードは建物の設計図でトレースは防犯カメラの映像だ。建物の中で何かが起きたとき、最初に設計図を広げるのではなく、映像を巻き戻す。

エージェントの品質を高めているチームは、重心をコードからトレースに移したチームだ。コードが重要でないのではない。ユーザーとお金を失うような本当の障害は、トレースにしか記録されないランタイムの振る舞いの中にあるからだ。