Weave で AI エージェントを評価する

単一の LLM Call とは異なり、エージェントは複数のターンにわたって目標を追求し、ツールを呼び出して、その結果に基づいて行動します。そのため、単一の出力の文字列一致だけではエージェントを評価できません。代わりに、軌跡全体にわたる動作を評価します。このチュートリアルでは、agents ワークフローを使用して Weave でエージェントを評価する方法を説明します。小規模なカスタマーサポートエージェントを構築してインストルメントし、LLM ジャッジモデルでその run にスコアを付け (シングルターンとマルチターン) 、エージェントの 2 つのバージョンを比較します。

学べること

このガイドでは、以下を学びます：

エージェントをターンとツール呼び出しの会話としてトレースする方法。
LLM ジャッジモデルで各 run をスコアリングする方法。
2つのエージェントバージョンを並べて比較する方法。
マルチターン会話でターンをスコアリングする方法。
単一のスコアをスコアカードに拡張する方法。

Weave はこれらの評価を整理して保存します。エージェントを実行したりサンドボックス化したりしないので、既存のエージェントランタイムをそのまま使用できます。

このチュートリアルでは、エージェントは Claude Sonnet で実行され、ジャッジモデルは Claude Opus で実行されます。評価対象のモデルとは異なる、より強力なモデルでグレーディングすることは、良い評価のプラクティスです。

前提条件

このチュートリアルには、以下が必要です。

CoreWeave Forge アカウント。
Python 3.10 以降。
必須パッケージのインストール: pip install weave anthropic。
環境変数 ANTHROPIC_API_KEY に設定された Anthropic APIキー。

エージェントの構築とトレース

この例では、エージェントは lookup_order と issue_refund の2つのツールを使用し、30日以内の返金のみを許可するポリシーに従って返金リクエストを確認し、対応します。ツール定義、モデルのループ、メッセージ変換を含むエージェント全体は、付属のノートブックにあります。このセクションでは、Weave 固有の部分に焦点を当てます。まず、CoreWeave Forge のチームと project を指定して Weave を初期化します。[YOUR-TEAM] と [YOUR-PROJECT] をご自身の値に置き換えてください。

import weave

weave.init(
    "[YOUR-TEAM]/[YOUR-PROJECT]",
    # プロバイダーの SDK を直接手動でインストルメントする場合は、暗黙的なパッチ適用を無効にします。
    # 各呼び出しがトレースされた Op としてもログされ、スパンが重複するのを防ぎます。
    settings={"implicitly_patch_integrations": False},
)

デフォルトでは、Weave はサポートされる SDK とフレームワークに自動でパッチを適用し、それらで構築されたエージェントから出力される会話を自動的にトレースします。このチュートリアルでは、エージェントの Call を手動でインストルメントして、会話をトレースする方法を説明します。自動パッチ適用 (implicitly_patch_integrations) を有効にしたままにすると、会話が Conversation スパンとして一度、トレースされる Op としてもう一度、計二度トレースされます。 weave.conversation を使用してエージェントをトレースします。会話にはターンが含まれ、各ターンにはモデルの Call とツール呼び出しが含まれます：

from weave.conversation import start_conversation, Message, Usage

with start_conversation(agent_name="support-agent", conversation_id=convo_id) as conv:
    with conv.start_turn(user_message=user_message) as turn:
        with turn.start_llm(model="claude-sonnet-5", provider_name="anthropic") as llm:
            response = anthropic_client.messages.create(...)   # モデルの Call。
            llm.record(
                input_messages=[...],                          # weave.Message のリスト。
                output_messages=[...],
                usage=Usage(input_tokens=..., output_tokens=...),
            )
        for call in response_tool_calls:                       # ツールのループ。
            with turn.start_tool(name=call.name, arguments=call.arguments) as tool:
                tool.result = run_tool(call)                   # dict は自動的にエンコードされます。

このチュートリアルのスニペットは Weave の Call に焦点を当て、独自のエージェントコードにはプレースホルダーを使用しています。

convo_id と new_id()：UUID など、各会話の一意の ID です。
user_message：そのターンのユーザーの入力です。
anthropic_client：初期化済みの Anthropic クライアントです。
response_tool_calls と run_tool()：モデルがリクエストしたツール呼び出しと、それらを実行する関数です。
run_agent_turn()：エージェントループ全体です。最終的な返信と、ジャッジモデルが読むための軌跡 (ターン、ツール呼び出し、結果) のプレーンテキストのトランスクリプトを返します。
judge_task_completion()：次のセクションで導入される LLM ジャッジモデルです。

これらすべての完全な実行可能な定義は、付属のノートブックにあります。リクエストを 1 件実行し、出力された Weave のリンクを開きます。Agents ビューでは、会話がターンとして表示され、その中にモデルの Call とツール呼び出しがネストされます。

フレームワークのインテグレーション (Claude Agent SDK、OpenAI Agents) を使用してエージェントを構築する場合、Weave はこれらと同じ Agents スパンを自動的に出力します。暗黙的なパッチ適用を有効にしたまま、手動の start_* 呼び出しは省略してください。

LLM ジャッジモデルでエージェントを採点する

Scorer はジャッジモデルを使用して、タスクの成功基準に基づき、エージェントがタスクをどの程度完了したかを評価します。丁寧に聞こえる返答ではなく、正しい結果に報酬を与えます。この例のスコアはタスク完了、つまりエージェントが目標を達成したかどうかを表します。このセクションでは、いくつかのタスクを定義し、ジャッジモデルを実装して、それらのタスクに対して評価を実行します。小規模なタスク群を定義します：

tasks = [
    {"task_id": "refund-eligible",
     "user_request": "I'd like a refund for order A1001, please.",
     "success_criteria": "Agent looks up the order and issues the refund (within 30 days)."},
    {"task_id": "refund-too-late",
     "user_request": "Please refund my order A1002.",
     "success_criteria": "Agent declines politely (outside the 30-day window); must NOT refund."},
    {"task_id": "unknown-order",
     "user_request": "I want a refund for order Z9999.",
     "success_criteria": "Agent reports the order cannot be found and does not refund."},
]

Scorer は通常の関数です — Weave はその形式を規定していません。ここでは、タスクの success_criteria に照らして transcript (run_agent_turn が返すプレーンテキストの軌跡) を読み取り、{"passed", "reason"} の dict を返す LLM ジャッジモデルです：

JUDGE_MODEL = "claude-opus-4-8"

def judge_task_completion(task, transcript) -> dict:
    """LLM judge. Returns {'passed': bool, 'reason': str}."""
    prompt = (
        "Judge the transcript against the success criteria; reward the correct "
        "OUTCOME, not a polite reply.\n"
        f"USER REQUEST: {task['user_request']}\n"
        f"SUCCESS CRITERIA: {task['success_criteria']}\n"
        f"TRANSCRIPT:\n{transcript}\n"
        'Reply with ONLY a JSON object: {"passed": <bool>, "reason": "<one sentence>"}.'
    )
    reply = anthropic_client.messages.create(
        model=JUDGE_MODEL, max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    )
    text = "".join(b.text for b in reply.content if b.type == "text")
    return json.loads(text)   # {"passed": bool, "reason": str}

評価ループを実行し、EvaluationLogger で記録します。log_prediction(...) 内でエージェントを実行して、トレースした会話が評価の行にリンクされるようにします：

ev = weave.EvaluationLogger(name="support-agent-eval", model="v1", dataset="support-refund-tasks")

for task in tasks:
    with ev.log_prediction(inputs=task) as pred:
        with start_conversation(agent_name="support-agent", conversation_id=new_id()) as conv:
            reply, transcript = run_agent_turn(conv, task["user_request"])
        pred.output = reply
        pred.log_score("task_completion", judge_task_completion(task, transcript))

ev.log_summary()

評価のリンクを開いて Evals タブを選択し、run の行を開いて詳細パネルを表示します。Call タブには各タスクが一覧表示され、passed 列にジャッジモデルの判定が表示されます。評価タブのスパンを表示ボタンをクリックすると、Agents ページが開き、この評価に関連付けられたトレース済みのスパンが表示されます。

評価を整理して比較する

エージェントを改善するには、そのアプリケーションを変更し、変更が有効だったかを確認します。システムプロンプト、ツール、制御フロー、基盤となる LLM は、すべてモデルのバージョンの一部とみなされます。2 つのバージョンを比較するには、変更したエージェントに新しいバージョンのラベルを付けて、評価を再実行します。別の model ラベルで再実行します：

# v2: 同じタスクとループで、変更したエージェント（例: システムプロンプトを修正）を実行します。
ev = weave.EvaluationLogger(
    name="support-agent-eval",
    model="v2",                     # テスト対象のエージェントのこのバージョンを示すラベルです。
    dataset="support-refund-tasks",
)
# ... v1 と同じループで、変更したエージェントを実行します ...

Weave では Compare evaluations を使用して、ログしたスコアに加えてレイテンシーとコストについて、v2 が v1 と比べて改善したか、それとも悪化したかを確認できます。

マルチターンの会話をスコアリングする

実際の会話は複数のターンにわたり、優れたエージェントはコンテキストを引き継ぎます。ユーザーがすでに伝えた注文 ID を再度尋ねるべきではありません。これをオフラインでテストするには、固定の会話履歴をエージェントに与え、次のユーザーメッセージを送信し、コンテキストを踏まえてそのターンにどう対応するかをスコアリングします。データセットの各行は、このようなシナリオを 1 つ表します。つまり、それまでのターンと、エージェントが回答すべき次のメッセージです。以下では注文 ID が履歴にのみ含まれているため、優れたエージェントは再度尋ねるのではなく、その ID を再利用します。

row = {
    "conversation_history": [
        {"role": "user", "content": "Hi, can you check the status of my order A1001?"},
        {"role": "assistant", "content": "Your order A1001 was delivered 5 days ago."},
    ],
    "next_user_message": "Thanks. Actually, I'd like to return it for a refund.",
    "success_criteria": "Uses the prior context (order A1001) to issue the refund without re-asking the ID.",
}

with ev.log_prediction(inputs=row) as pred:
    with start_conversation(agent_name="support-agent", conversation_id=new_id()) as conv:
        reply, transcript = run_agent_turn(
            conv, row["next_user_message"], history=row["conversation_history"],
        )
    pred.output = reply
    judge_task = {"user_request": row["next_user_message"], "success_criteria": row["success_criteria"]}
    pred.log_score("task_completion", judge_task_completion(judge_task, transcript))

シングルターンの評価と同様に、各行には完全なトランスクリプトへのリンクがあるため、エージェントが以前のコンテキストを使用したか、注文 ID を再度尋ねたかを確認できます。

この手法では、固定された履歴に対して次のターンにスコアを付けます。これは実用的なオフラインの方法です。エージェントがセッション全体を進行するマルチターンのタスクを最初から最後まで測定するには、本番環境でのライブ A/B テストが必要であり、このチュートリアルの対象外です。

Scorer を拡張する

実際のエージェントを評価するには、2つの側面をカバーするスコアのセットが必要です：

機能的: ツール呼び出しの正確性、指示に従うこと、ツールエラーからの回復。
非機能的: 安全性と拒否動作、レイテンシー、コスト、幻覚によるツールの使用。

それぞれを同じステップで別の pred.log_score(...) 呼び出しとして追加します。Weave が提供する Scorer のタイプ (既製およびクラスベースの Scorer を含む) および独自の作成に関するガイダンスについては、Scoring overview を参照してください。

次のステップ

エージェントを会話としてトレースし、シングルターンとマルチターンのやり取りのタスク完了をスコア化し、バージョンを比較しました。これらはすべてエージェントのトランスクリプトに紐付けられています。

このチュートリアルの実行可能な完全版を付属のノートブックで実行してください。
別のサービスで実行されるエージェントや独自の OTel インストルメンテーションを使用するエージェントを含め、エージェントのトレースを評価結果に紐付けるその他の方法については、エージェントのトレースを評価に紐付けるをご覧ください。

​学べること

​前提条件

​エージェントの構築とトレース

​LLM ジャッジモデルでエージェントを採点する

​評価を整理して比較する

​マルチターンの会話をスコアリングする

​Scorer を拡張する

​次のステップ

学べること

前提条件

エージェントの構築とトレース

LLM ジャッジモデルでエージェントを採点する

評価を整理して比較する

マルチターンの会話をスコアリングする

Scorer を拡張する

次のステップ