AIエージェントデバッグのコツ：問題を素早く特定・解決する方法

AIエージェントのデバッグは、通常のプログラムデバッグと異なる難しさがあります。LLMの非決定性（同じ入力でも毎回違う出力）、複数ステップの処理、ツール呼び出しの組み合わせなど、問題の特定が困難です。本記事では、効率的なデバッグのテクニックを解説します。

AIエージェントデバッグの難しさ

通常のプログラムは同じ入力→同じ出力（決定論的）ですが、LLMは同じプロンプトでも毎回異なる出力を生成します（確率論的）。これがデバッグを難しくする主な理由です。

また、エージェントは「推論→ツール呼び出し→観察→再推論」を複数回繰り返すため、どのステップで問題が起きたかを特定するには詳細な実行ログが必要です。

デバッグの基本：詳細なロギング

効果的なデバッグの出発点は「詳細なログ記録」です。

import logging
import json
from datetime import datetime

class AgentLogger:
    def __init__(self, agent_name):
        self.logger = logging.getLogger(agent_name)
        self.session_id = datetime.now().strftime("%Y%m%d_%H%M%S")
    
    def log_llm_call(self, messages, model, response):
        self.logger.info({
            "event": "llm_call",
            "session_id": self.session_id,
            "model": model,
            "input_tokens": response.usage.prompt_tokens,
            "output_tokens": response.usage.completion_tokens,
            "cost_usd": self.calculate_cost(model, response.usage),
            "messages": messages,
            "response": response.choices[0].message.content
        })
    
    def log_tool_call(self, tool_name, params, result):
        self.logger.info({
            "event": "tool_call",
            "session_id": self.session_id,
            "tool": tool_name,
            "params": params,
            "result": str(result)[:500],  # 長すぎる場合は切り詰め
            "success": not isinstance(result, Exception)
        })

このログを見ることで、エージェントがどのように推論し、どのツールをどの順序で呼んだかが完全に追跡できます。

LangSmithを使った可視化デバッグ

LangChainを使っている場合、LangSmithはエージェントの実行をビジュアルに追跡できる最強のデバッグツールです。

セットアップ:

import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "your-langsmith-api-key"
os.environ["LANGCHAIN_PROJECT"] = "my-agent-debug"

これだけで、エージェントのすべての実行がLangSmith上でツリー形式で可視化されます。各ステップの入力・出力・所要時間・コストが一目でわかります。

問題の段階的な絞り込み

デバッグの手順は「大から小へ」の絞り込みです。

ステップ1：問題を再現させる

まず問題を安定して再現できるか確認します。毎回同じ問題が起きるなら設計上の問題、不規則なら確率論的な問題（LLMの確率的な動作）です。

ステップ2：最小再現ケースを作る

複雑なエージェントで問題が起きている場合、関係ないツールや処理を取り除いて最小構成で問題を再現します。

ステップ3：プロンプトの問題かコードの問題かを特定

プレイグラウンド（OpenAI Platform、Claude.ai等）でシステムプロンプトと同じ入力を試します。プレイグラウンドで問題が起きなければコード側の問題、起きるならプロンプト設計の問題です。

AIエージェントのエラートラブルシューティングとの連携

エラーが発生した際は、まずエラーの種類を特定し（APIエラー・ロジックエラー・品質問題）、それぞれの対処法を適用します。デバッグログはこの特定を助ける重要な情報源です。

プロンプトのABテスト

品質問題のデバッグには、プロンプトのABテストが有効です。

import random

def run_prompt_ab_test(task, prompt_a, prompt_b, n_runs=10):
    results_a = []
    results_b = []
    
    for _ in range(n_runs):
        # ランダムにどちらかのプロンプトを選択
        if random.random() < 0.5:
            result = run_with_prompt(task, prompt_a)
            results_a.append(evaluate_quality(result))
        else:
            result = run_with_prompt(task, prompt_b)
            results_b.append(evaluate_quality(result))
    
    return {
        "prompt_a_avg_score": sum(results_a) / len(results_a) if results_a else 0,
        "prompt_b_avg_score": sum(results_b) / len(results_b) if results_b else 0
    }

AIエージェントの出力品質を上げる方法で解説した品質評価と組み合わせることで、データに基づいたプロンプト改善ができます。

一般的なデバッグのヒント

Temperatureを0に設定: デバッグ中はLLMの出力を決定論的にするためtemperature=0に設定します。再現性が高まり、問題の特定がしやすくなります。

小さなテストセットを用意: 代表的な入力パターン10〜20件のテストセットを準備し、プロンプト変更後に全件テストします。

エラーを文書化する: 発生したエラー・原因・解決策を記録するエラー辞書を作成します。同じ問題が再発した時に素早く解決できます。

まとめ

AIエージェントのデバッグは、詳細なログ記録・ビジュアル化ツール（LangSmith等）・段階的な絞り込みの組み合わせで効率化できます。問題が起きた際に慌てずに「どのステップで問題が起きたか」を特定することが最初の一歩です。AIエージェントのループエラー対処法と合わせて、デバッグスキルを高めることで、安定したエージェント運用が実現します。