Apidog AIエージェントデバッガーで嘘つきエージェントを解決！

火曜の午後。デバッグセッションが12ターン目に突入し、エージェントは自信満々に、当社の /users エンドポイントが47秒で応答していると教えてくれました。実際の数字は47ミリ秒でした。

今すぐApidogを試す

私はこのバグを2日間追い続けていました。MCPサーバーに print 文を追加するたびに、エージェントの答えは微妙に変わり、何か進展があるように見えました。システムプロンプトを書き直すたびに、応答はもっともらしくなりましたが、どれも正しくありませんでした。

その日の午後まで私がやっていなかったことは、実際の実行トレースを開き、モデルとツールの間で何がやり取りされているかを確認することでした。それこそがApidogのAI Agent Debuggerの用途です。私は3週間前にインストールしていましたが、その存在を忘れていました。バグを見つけるのにかかった時間は12分でした。

以下では、何が起きていたのか、どこを見ればよかったのか、そして同じ手順をどう再現するかを整理します。

私が追いかけていたバグ

構成はシンプルでした。

• GPT-5.5ベースのエージェント
• 週末に書いたMCPサーバー
• メトリクスパイプラインに問い合わせる get_response_time(endpoint) ツール
• 40語程度の短いシステムプロンプト
• ユーザープロンプト: 「/usersエンドポイントの速度はどれくらいですか？」

エージェントは素早く答えました。自信満々でした。しかし、毎回違う形で間違っていました。

例:

• 「エンドポイントは47秒で応答しています」
• 「約0.05秒」
• 「パフォーマンスは許容範囲内です」

私はいつものデバッグをしていました。

• MCPサーバーにロギングを追加する
• モデルの応答をトークン単位で読む
• システムプロンプトを比較する
• 失敗した仮説をNotionにまとめる
• そして、呪詛の言葉を吐く

ただし、エージェントのバグは最初に見る場所にはめったにありません。原因は次のどこかにあります。

1. システムプロンプト
2. モデルの選択
3. ツール定義
4. モデルがツールに渡したパラメータ
5. ツールが返したデータ
6. モデルがそのデータをどう解釈したか

コンソールログだけでは、このうち一部しか見えません。

トレースパネルで確認すべきもの

ApidogのAI Agent Debuggerは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回とも同じでした。

エンドポイントは約47ミリ秒で応答しています。

モデルの推論には、ミリ秒とパーセンタイルの内訳も含まれていました。トークンコストは、失敗していた実行と比べて18%低くなりました。おそらく、モデルが誤った仮定を補正するための余分な文章を生成しなかったためです。

同じプロンプトをClaude Opus 4.7でも別セッションで並行実行しました。結果は同じでしたが、コストは2倍で、応答もやや冗長でした。これで、本番環境に投入すべきモデルの判断材料が得られました。

ここで便利だったのは、左パネルに次のメトリクスが並ぶことです。

• ターン数
• ステップ数
• 実行時間
• トークン数
• 費用
• 使用モデル

私はこの比較を6ヶ月間Googleスプレッドシートで行っていました。今では3クリックで済みます。

私が誤解していたこと

AI Agent Debuggerは単なるロギングツールではありません。

ログは「何が起こったか」を表示します。一方で、デバッガーは「モデルとツールが実際に何をやり取りしたか」を表示します。この2つは別のレイヤーです。

もしエージェントを書いていて、モデルの最終出力だけを読んで失敗原因を推測しているなら、それはエージェントのデバッグではありません。エージェントに関する自分の仮説をデバッグしているだけです。

エージェントは、以下の4つで構成される閉じたシステムです。

1. モデル
2. プロンプト
3. ツール
4. ツールレスポンス

バグは常にこのどこかにあります。4つを同時に見られれば12分で見つかります。見られなければ、1週間追いかけることになります。

もう1つ、デバッガーで見つかったのは非決定性です。

修正後に同じプロンプトを5回実行しました。

• 3回: get_response_time が1回呼び出された
• 2回: get_response_time が2回呼び出された
• 2回目の呼び出しでは、エンドポイントのパスの大文字小文字が異なっていた

私のツールスキーマは大文字小文字を区別していました。失敗したテストケースがすべて小文字だったため、私はそれに気づいていませんでした。

これは、リリース前に見つけられていなければ本番に入っていた2つ目のバグです。

今後もっとも使う機能は、複数回実行分析です。

手順はシンプルです。

1. 同じプロンプトでRunを5回押す
2. セッションパネルを見る
3. 実行ごとの差分を確認する
4. 差分が出た箇所を重点的に修正する

複数回実行で結果が揺れる場所は、エージェントが脆弱な場所です。

実際に試す: セットアップ手順

ここからは、同じようにAI Agent Debuggerでデバッグセッションを実行する手順です。

ステップ1: 新しいエージェントデバッグセッションを作成する

Apidogを開き、上部のタブバーにある AI Agent Debugger をクリックします。

ページ上部でモデルと実行設定を選択します。

1. 左側でモデルプロバイダーを選択します 例: OpenAI、Anthropicなど
2. 中央でモデルを選択します 例: gpt-5.5
3. プロバイダーを選択すると、ベースURLは自動入力されます
4. セッションを開始するには 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ツールは、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 をクリックすると、作成したセッションが左パネルに表示されます。

各セッションには、次のようなサマリーが表示されます。

Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5

確認するパネルは3つです。

セッションパネル（左）

実行履歴と要約メトリクスを確認します。

見るべき項目:

• ターン数
• ステップ数
• 実行時間
• トークン数
• コスト
• 使用モデル

ターンパネル（中央）

ユーザーとモデルの対話ラウンドを確認します。

ラウンドをクリックすると、その実行詳細が右側にロードされます。

トレースパネル（右）

エージェントの完全な実行チェーンを順番に確認します。

主に見るべき項目:

• システムプロンプト
• ユーザープロンプト
• すべてのモデル呼び出し
• モデルが公開している場合の思考プロセス
• MCPツール呼び出し
• カスタムスキル実行
• ツール入力パラメータ
• ツール結果
• 消費時間
• エラーメッセージ
• 最終出力

ツール呼び出しが失敗した場合や、モデルが例外を返した場合、失敗したステップは入力と出力付きでトレースパネルに表示されます。ログを深掘りする前に、まずここを確認します。

ステップ6: モデルパフォーマンスを比較する

同じプロンプト、同じツール設定で、モデルだけを変えて実行します。

各実行は新しいセッションとして作成されるため、左パネルで比較できます。

比較するときは、次の点を見ます。

• 同じタスクに対する実行ステップ数
• どちらのモデルが正確にツールを選択するか
• どちらのモデルの応答時間が短いか
• どちらのモデルがトークン消費を予測可能に保つか
• どちらのモデルがコストを抑えられるか
• 同じ入力で結果がどの程度安定するか

モデル比較は、最終出力だけでは判断しない方が安全です。ツール呼び出し、引数、ツール結果の解釈まで含めて確認します。

まとめ

2日間のデバッグで学んだのは、バグそのものよりも、見るべきレイヤーについてでした。

私が誤った修正を追い続けていた理由は、使用していたツールが必要な情報を同時に見せてくれなかったからです。

モデルの出力はありました。ツールの出力もありました。しかし、それらを1つの流れとして見るための共通フレームがありませんでした。

エージェントをデバッグするときは、次の4つを同時に見ます。

1. モデルに渡したプロンプト
2. モデルが選んだツール
3. ツールに渡したパラメータ
4. ツール結果をモデルがどう解釈したか

もし複数のエージェントを書いていて、まだApidogのAI Agent Debuggerを開いていないなら、次にリリースするエージェントにも、モデルとツールの間に潜むバグがあるかもしれません。

Apidogをダウンロードし、次にエージェントが自信満々に間違った答えを返したときに開いてみてください。

12分です。47ミリ秒であり、47秒ではありません。

MCPトランスポートのセットアップやプランの利用可能性を含む全機能リファレンスは、Apidog AI Agent Debugger: 利用可能性、カバレッジ、およびセットアップに記載されています。