評価・トレース・デバッグのエージェント運用

エージェントは 「動いた」だけではダメ。本番運用では「正しく動いたか」「いつ・どこで失敗したか」を継続的に把握する必要があります。

エージェント評価の3軸

評価データセットの構築

# 評価ケースの設計

評価ケース：
- 入力: ユーザー要求
- 期待: 実行されるべきツール呼び出しの順序
- 期待出力: 最終的な応答
- 合格基準: 完全一致 / 部分一致 / 主観評価

例：
case_001:
  input: "先週注文した商品の配送状況を教えて"
  expected_tools:
    - get_user_orders(date_range="last_week")
    - check_shipping_status(order_id="...")
  expected_output_pattern: "配送中|配達済み|未発送"
  pass_criteria: "正しい注文IDで配送状況確認した"

自動評価の実装

def evaluate_test_case(case, agent):
    result = agent.run(case.input)

    scores = {
        "task_completion": evaluate_completion(result, case),
        "tool_correctness": evaluate_tools(result.tool_calls, case.expected_tools),
        "output_quality": evaluate_output(result.final_output, case.expected_output_pattern),
        "efficiency": result.total_turns / case.max_turns,
        "cost": result.total_tokens * cost_per_token,
    }

    return scores

# LLM-as-Judge による品質評価
def llm_judge(actual, expected):
    return call_claude(
        system="あなたは評価者です。実際の出力と期待出力を比較し、0.0〜1.0で採点してください。",
        user=f"期待: {expected}n実際: {actual}n採点と理由を出力。"
    )

トレースの記録

本番では、すべての実行を 詳細にトレース。

# トレース構造

@dataclass
class AgentTrace:
    session_id: str
    user_id: str
    started_at: datetime
    ended_at: datetime
    goal: str
    final_status: str  # success/failed/timeout

    iterations: List[IterationTrace]
    total_tokens: int
    total_cost_usd: float
    final_output: str

@dataclass
class IterationTrace:
    iteration_number: int
    started_at: datetime
    duration_ms: int

    # プランナー
    plan_reasoning: str
    plan_decision: str  # ツール呼び出し or 完了

    # ツール実行
    tool_call: Optional[ToolCall]
    tool_result: Optional[Any]
    tool_duration_ms: int

    # コスト
    input_tokens: int
    output_tokens: int
    cost_usd: float

分散トレース（OpenTelemetry連携）

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def agent_loop(goal, tools):
    with tracer.start_as_current_span("agent.run", attributes={"goal": goal}):
        for i in range(max_iter):
            with tracer.start_as_current_span(f"iteration.{i}"):
                with tracer.start_as_current_span("planner.call"):
                    plan = call_claude(...)

                with tracer.start_as_current_span("tool.execute", attributes={
                    "tool.name": plan.tool_name,
                    "tool.args": json.dumps(plan.tool_args),
                }):
                    result = execute_tool(plan)

                if result.error:
                    span.set_status(StatusCode.ERROR)

ダッシュボードの設計

本番障害時のデバッグ手順

# Step 1: 影響範囲の特定
SELECT
    COUNT(*) as failed_sessions,
    error_type
FROM agent_traces
WHERE started_at > NOW() - INTERVAL '1 hour'
  AND final_status = 'failed'
GROUP BY error_type
ORDER BY failed_sessions DESC;

# Step 2: 共通点の抽出
- 失敗セッションのインプット類似性
- 使用していたツール
- モデルバージョン

# Step 3: 1セッションの詳細確認
SELECT * FROM iteration_traces
WHERE session_id = 'failed_session_id'
ORDER BY iteration_number;

# Step 4: 仮説検証
- ローカルで同じインプットを再現
- ツール呼び出しの結果を検証
- システムプロンプト・ツール定義の変更履歴確認

失敗からの学習

# 失敗ケースを評価データセットに追加

def add_to_eval_dataset(failed_session):
    case = {
        "input": failed_session.goal,
        "actual_outcome": failed_session.final_output,
        "actual_tools": failed_session.tool_calls,
        "expected": "（人間が補正）",
        "category": "regression_test",
    }
    eval_dataset.append(case)

# 修正後、リグレッションテストとして実行
# 同じ失敗が再発しないか確認

運用上の重要指標

このレッスンのまとめ

「評価データセット → 自動評価 → トレース記録 → ダッシュボード → 障害デバッグ → 学習」のサイクルでエージェントを継続改善できます。本コース「Claudeエージェント実装：深掘り編」はこれで修了です。次は「MCPで Claude を業務システムと統合する」または「本番運用」コースへ。