火曜の午後。デバッグセッションが12ターン目に突入し、エージェントは自信満々に、当社の/usersエンドポイントが47秒で応答していると教えてくれました。実際の数字は47ミリ秒でした。
私はこのバグを2日間追い続けていました。MCPサーバーにprint文を追加するたびに、エージェントの答えは微妙に変わり、何か進展があるかのように思わせられました。システムプロンプトを書き直すたびに、応答はもっともらしく聞こえましたが、どれも正しくありませんでした。
その日の午後まで私がやっていなかったことは、実際の実行トレースを開き、モデルとツールの間で何がやり取りされているかを確認することでした。それこそがApidogのAI Agent Debuggerの目的です。私は3週間前にインストールしましたが、そのことを忘れていました。バグを見つけるのに12分しかかかりませんでした。
これが私を驚かせたことです。
私が追いかけていたバグ
セットアップはシンプルでした。GPT-5.5ベースのエージェント。週末に私が書いたMCPサーバーが1つあり、メトリクスパイプラインにクエリを実行するget_response_time(endpoint)ツールを公開していました。システムプロンプトはせいぜい40語程度。ユーザープロンプトは「/usersエンドポイントの速度はどれくらいですか？」でした。
エージェントは素早く答えました。自信満々に答えました。しかし、毎回違う形で間違った答えを出しました。時には「エンドポイントは47秒で応答しています」。時には「約0.05秒」。一度は、記憶に残ることに「パフォーマンスは許容範囲内です」と答えました。
私は通常行うべきことをしていました。MCPサーバーにロギングを追加したり、モデルの応答をトークンごとに読んだり、システムプロンプトを比較したり。そして、呪詛の言葉を吐いたり。火曜日の朝には、3つのターミナルウィンドウを開き、失敗した仮説をまとめたNotionページを持っていました。
エージェントのデバッグに関して言えば、バグは最初に見る場所にはめったにありません。システムプロンプト、モデルの選択、ツールの定義、モデルがツールに渡したパラメータ、ツールが返したデータ、あるいはモデルがそのデータをどのように解釈したか、のいずれかに存在する可能性があります。6つの場所です。コンソールログは1つしか示しません。
トレースパネルが実際に示すもの
Apidogデバッガーは3つのカラムで開きます。左側にセッション、中央にターン、右側にトレース。任意のセッションをクリックすると、中央のカラムにユーザーメッセージ、モデル応答、ツール呼び出し、ツール戻り値、次のモデル応答といった対話が表示されます。任意のターンをクリックすると、右のカラムはその下の完全な実行ツリーを展開します。
実行ツリーこそが、私が見落としていた部分でした。すべてのステップが順序立てて表示されます。
- モデルが受け取ったシステムプロンプト
- モデルが受け取ったユーザープロンプト
- モデルが発行したそのままのJSON形式のツール呼び出し名とパラメータ
- ツールが返したそのままのJSON形式のツール結果ペイロード
- ターンごとのタイミングとトークンを含むモデル応答
失敗したセッションを開きました。ツール呼び出しは問題なく見えました: get_response_time(endpoint="/users")。モデルは正しい引数で正しいツールを選択していました。
それからツール結果を展開しました。
{"value": 47, "p95": 89, "samples": 1240}
そこにありました。メトリクスパイプラインは値をミリ秒で返していました。モデルは秒であると仮定していました。単位を疑問に思うことなく、確信に満ちたハルシネーションにより、47は「47秒」になっていました。ツールは正しかったのです。モデルが間違っていました。私のシステムプロンプトには単位に関する指示がなく、ツール応答にも単位の注釈がありませんでした。
デバッガーを開いてから12分。私は2日間もシステムプロンプトを責め続けていたのです。
修正は6行で完了
私は2つのことを変更しました。MCPサーバーで、応答の形式を更新しました。
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
次に、システムプロンプトに1文追加しました。「ツールの結果は単位を明示的に返します。注意して読んでください。」
同じ/usersプロンプトをさらに3回実行しました。左パネルには3つの異なるセッションが表示されました。3つとも正確に「エンドポイントは約47ミリ秒で応答しています」と返し、モデルの推論にはミリ秒からパーセンタイルまでの内訳が含まれていました。トークンコストは、失敗した実行と比較して18パーセント低くなりました。これはおそらく、モデルが自身の誤った仮定に関する修復的な文章を生成しなかったためでしょう。
同じプロンプトをClaude Opus 4.7で別のセッションで並行して実行しました。結果は同じでしたが、コストは2倍で、やや冗長でした。どのモデルを本番環境に投入すべきか分かりました。
これが私がこのツールに敬意を抱いた部分です。どんなまともなデバッガーでもバグを見つけることはできます。そうではなく、左パネルにターン数、ステップ数、時間、トークン、費用といった要約メトリクスとともに、同一の設定で実行されたモデル比較です。私は6ヶ月間、この比較をGoogleシートで行っていました。今では3クリックで済みます。
私が誤解していたこと
安易な見方をすれば、AI Agent Debuggerはロギングツールだと思われがちです。しかし、そうではありません。ロギングツールは「何が起こったか」を示しますが、デバッガーはモデルとツールが「実際に何をやり取りしたか」を示し、これは異なるレイヤーです。
もしあなたがエージェントを書いていて、私がしていたようにモデルの出力を読んで失敗の原因を推測しているのであれば、私はこう反論したいです。あなたはエージェントをデバッグしているのではなく、エージェントに関するあなたの仮説をデバッグしているのです。これらは異なることであり、修正にたどり着くのはそのうちの一つだけです。
私が6ヶ月間も理解しようとしなかったのは、エージェントがモデル、プロンプト、ツール、ツール応答の間の閉じたシステムであるということでした。バグは常にこれら4つのうちの1つに存在します。これらすべてを同時に見ることができれば、12分でバグを見つけることができます。できなければ、1週間も追いかけることになるでしょう。
デバッガーが明らかにしたもう一つの予期せぬことは、私自身のエージェントにおける非決定性でした。修正後に同じプロンプトを5回実行して確認しました。3回の実行ではget_response_timeが1回呼び出されました。2回の実行では2回呼び出され、2回目はエンドポイントのパスが大文字と小文字が異なるものでした。私のツールスキーマは大文字と小文字を区別していました。失敗したテストケースがすべて小文字を使用していたため、私はそれに気づいていませんでした。これは、気づかずにリリースしてしまう可能性があった2つ目のバグでした。
今後の私の活用において最も役立つ機能は、複数回実行分析です。実行ボタンを5回クリックします。セッションパネルを見てください。複数の実行で異なる点があれば、そこがエージェントが脆弱である場所です。
実際に試してみる：完全なセットアップ手順
もしバグハンティング中に私が使用していたのと同じセットアップを試したいなら、新規インストールからデバッグセッションの実行までの手順を以下に示します。5つの画面を順に説明します。
ステップ1：新しいエージェントデバッグセッションの作成
Apidogを開き、上部のタブバーにあるAI Agent Debuggerをクリックします。ページの上部にはモデルと実行ステータスが設定されます。
- 左側でモデルプロバイダーを選択します（OpenAI、Anthropicなど）
- 中央で特定のモデルを選択します。例:
gpt-5.5 - プロバイダーを選択するとベースURLは自動的に入力され、手動での入力は不要です
- セッションを開始するにはRunをクリックします
ステップ2：プロンプトの設定
Promptsタブには2つの入力エリアがあります。
- システムプロンプト: エージェントの役割、目標、制約、ツール使用規則を定義します
- ユーザープロンプト: このセッションのテスト入力です。例：「Apidogとは何ですか？」
両方が設定されたら、右上のRunをクリックします。各実行後にインプットボックスを自動的にクリアしたい場合は、Clear after Sendにチェックを入れてください。
ステップ3：ツールの設定
Toolsタブには、エージェントが実行時に呼び出すことができるすべてのツールがリスト表示されます。タブ上の数字は、現在利用可能または設定されているツールの数です。
組み込みツールはデバッガーに同梱されています。必要に応じてオン/オフを切り替えます。
| ツール | 機能 |
|---|---|
bash |
永続的なシェルセッションでコマンドを実行する |
web_fetch |
ウェブコンテンツを取得し、Markdown、テキスト、またはHTMLに変換する |
read |
テキスト、画像、またはPDFファイルを読み込む |
edit |
ファイルに正確な文字列置換を適用する |
write |
ファイルを作成または上書きする |
grep |
正規表現でファイル内容を検索する |
glob |
グロブパターンを使用してファイルを検索する |
kill_shell |
現在のシェルセッションをリセットする |
MCPツールは、MCPサーバーを介して外部システムやカスタム機能を追加します。接続方法は3つあります。
- STDIO: ローカルMCPサーバープロセスを起動する
- HTTP: Streamable HTTPをサポートするMCPサーバーに接続する
- SSE: Server-Sent Eventsに基づくMCPサーバーに接続する
認証が必要なMCPサーバーは、リクエストヘッダーまたはOAuth 2.0フローを受け入れます。接続に成功したら、サーバーがエージェントに公開するツールを選択します。
ステップ4：スキル、認証、モデルパラメータの設定
3つの小さなタブがセットアップを補完します。
- スキル: エージェントのための再利用可能なワークフロー。固定されたプロジェクトワークフロー、一般的なタスク操作仕様、システムプロンプト内の反復的な長文の削減に役立ちます。スキルは実行時に必要に応じてロードされます。
- 認証: モデルサービスまたはMCPサービスに必要な認証情報。
- 設定: 温度 (Temperature)、最大トークン数 (Max Tokens)、Top Pなどのモデル実行時パラメータ。サポートされるパラメータはプロバイダーによって異なるため、ご使用のモデルが実際に受け入れるものを確認してください。
ステップ5：3つのパネルを読む
Runをクリックすると、作成したばかりのセッションが左パネルに表示されます。各セッションは1行のサマリーを表示します。
Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5
- セッションパネル（左）: 要約メトリクス付きの各実行履歴
- ターンパネル（中央）: ユーザーとモデルの対話の各ラウンド。ラウンドをクリックすると、その実行詳細が右側にロードされます。
- トレースパネル（右）: システムプロンプトとユーザープロンプト、すべてのモデル呼び出し、モデルが公開している場合のモデルの思考プロセス、MCPツール呼び出しとカスタムスキル実行、ツール入力パラメータ、結果、消費時間、エラーメッセージ、最終出力など、エージェントの完全な実行チェーンが順序立てて表示されます。
ツール呼び出しが失敗したり、モデルが例外を返したりした場合、失敗したステップは入力と出力が表示された状態でトレースパネルに直接表示されます。ログを深く掘り下げる必要はありません。
ステップ6：モデルパフォーマンスの比較
同じプロンプト、同じツール設定、異なるモデル。各実行は新しいセッションを作成し、左パネルでそれらを並べて比較できます。
比較に役立つメトリクス:
- 同じタスクに対する実行ステップ数
- どちらのモデルがより正確にツールを選択するか
- どちらのモデルの応答時間が短いか
- どちらのモデルがトークン消費とコストをより予測可能に保つか
まとめ
2日間のデバッグが午後の数時間に凝縮され、私が学んだのはバグについての教訓ではありませんでした。ツールについての教訓でした。私が誤った修正を追い続けていた理由は、使用していたツールが必要なものを見せてくれなかったからです。モデルの出力とツールの出力はありましたが、それらを一緒に見るための共通のフレームがありませんでした。共通のフレームこそが重要な点なのです。
もしあなたが複数のエージェントを記述しており、まだApidogのAI Agent Debuggerを開いていないのであれば、次にリリースするエージェントには、モデルとツールの間に存在するバグがあるでしょう。あなたはそれに1週間を費やし、失敗した仮説のNotionページを作成することになるでしょう。そのバグは、デバッガーが初日にあなたに示したであろう場所に正確に存在します。
Apidogをダウンロードし、次に自信満々に間違った答えを出すエージェントで開いてみてください。12分です。47ミリ秒であり、47秒ではありません。
MCPトランスポートのセットアップやプランの利用可能性を含む全機能リファレンスは、Apidog AI Agent Debugger: 利用可能性、カバレッジ、およびセットアップに記載されています。