Agent 评估

评估（“evals”）通过评估 Agent 的执行轨迹（即其产生的消息和工具调用序列）来衡量其表现。与验证基本正确性的集成测试不同，评估会根据参考标准或评分标准对 Agent 行为进行评分，因此在更改提示、工具或模型时，它们对于捕获回归问题非常有用。评估器是一个函数，它接收 Agent 的输出（以及可选的参考输出）并返回一个分数：

def evaluator(*, outputs: dict, reference_outputs: dict):
    output_messages = outputs["messages"]
    reference_messages = reference_outputs["messages"]
    score = compare_messages(output_messages, reference_messages)
    return {"key": "evaluator_score", "score": score}

agentevals 包提供了用于 Agent 轨迹的预构建评估器。你可以通过执行轨迹匹配（确定性比较）或使用 LLM 评判（定性评估）来进行评估：

方法	何时使用
轨迹匹配	你知道预期的工具调用，并希望进行快速、确定性、无成本的检查
LLM 作为评判	你希望评估整体质量和推理，而没有严格的预期

安装 AgentEvals

pip install agentevals

或者，直接克隆 AgentEvals 仓库。

轨迹匹配评估器

AgentEvals 提供了 create_trajectory_match_evaluator 函数，用于将你的 Agent 轨迹与参考轨迹进行匹配。有四种模式：

模式	描述	使用场景
`strict`	消息结构和工具调用完全按相同顺序精确匹配（消息内容可以不同）	测试特定序列（例如，授权前进行策略查询）
`unordered`	与参考轨迹具有相同的消息结构和工具调用，但工具调用可以按任意顺序发生	验证信息检索，当顺序无关紧要时
`subset`	Agent 仅调用参考中的工具（没有额外工具）	确保 Agent 不超出预期范围
`superset`	Agent 至少调用了参考中的工具（允许额外工具）	验证采取了最低要求的操作

以下示例共享一个通用设置，即一个带有 get_weather 工具的 Agent：

from langchain.agents import create_agent
from langchain.tools import tool
from langchain.messages import HumanMessage, AIMessage, ToolMessage
from agentevals.trajectory.match import create_trajectory_match_evaluator


@tool
def get_weather(city: str):
    """Get weather information for a city."""
    return f"It's 75 degrees and sunny in {city}."

agent = create_agent("claude-sonnet-4-6", tools=[get_weather])

严格匹配

strict 模式确保轨迹包含完全相同的消息，顺序相同，工具调用也相同，但允许消息内容存在差异。当你需要强制执行特定的操作序列时（例如，要求在授权操作之前进行策略查询），这很有用。

evaluator = create_trajectory_match_evaluator(
    trajectory_match_mode="strict",
)

def test_weather_tool_called_strict():
    result = agent.invoke({
        "messages": [HumanMessage(content="What's the weather in San Francisco?")]
    })

    reference_trajectory = [
        HumanMessage(content="What's the weather in San Francisco?"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_weather", "args": {"city": "San Francisco"}}
        ]),
        ToolMessage(content="It's 75 degrees and sunny in San Francisco.", tool_call_id="call_1"),
        AIMessage(content="The weather in San Francisco is 75 degrees and sunny."),
    ]

    evaluation = evaluator(
        outputs=result["messages"],
        reference_outputs=reference_trajectory
    )
    # {
    #     'key': 'trajectory_strict_match',
    #     'score': True,
    #     'comment': None,
    # }
    assert evaluation["score"] is True

无序匹配

unordered 模式允许相同的工具调用以任意顺序出现。当你想验证是否检索到了特定信息但不在乎顺序时，这很有帮助。例如，一个 Agent 使用不同的工具调用来检查城市的天气和活动。

@tool
def get_events(city: str):
    """Get events happening in a city."""
    return f"Concert at the park in {city} tonight."

agent = create_agent("claude-sonnet-4-6", tools=[get_weather, get_events])

evaluator = create_trajectory_match_evaluator(
    trajectory_match_mode="unordered",
)

def test_multiple_tools_any_order():
    result = agent.invoke({
        "messages": [HumanMessage(content="What's happening in SF today?")]
    })

    reference_trajectory = [
        HumanMessage(content="What's happening in SF today?"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_events", "args": {"city": "SF"}},
            {"id": "call_2", "name": "get_weather", "args": {"city": "SF"}},
        ]),
        ToolMessage(content="Concert at the park in SF tonight.", tool_call_id="call_1"),
        ToolMessage(content="It's 75 degrees and sunny in SF.", tool_call_id="call_2"),
        AIMessage(content="Today in SF: 75 degrees and sunny with a concert at the park tonight."),
    ]

    evaluation = evaluator(
        outputs=result["messages"],
        reference_outputs=reference_trajectory,
    )
    assert evaluation["score"] is True

子集和超集匹配

superset 和 subset 模式匹配部分轨迹。superset 模式验证 Agent 至少调用了参考轨迹中的工具，允许额外的工具调用。subset 模式确保 Agent 没有调用参考轨迹之外的任何工具。

@tool
def get_detailed_forecast(city: str):
    """Get detailed weather forecast for a city."""
    return f"Detailed forecast for {city}: sunny all week."

agent = create_agent("claude-sonnet-4-6", tools=[get_weather, get_detailed_forecast])

evaluator = create_trajectory_match_evaluator(
    trajectory_match_mode="superset",
)

def test_agent_calls_required_tools_plus_extra():
    result = agent.invoke({
        "messages": [HumanMessage(content="What's the weather in Boston?")]
    })

    # Reference only requires get_weather, but agent may call additional tools
    reference_trajectory = [
        HumanMessage(content="What's the weather in Boston?"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_weather", "args": {"city": "Boston"}},
        ]),
        ToolMessage(content="It's 75 degrees and sunny in Boston.", tool_call_id="call_1"),
        AIMessage(content="The weather in Boston is 75 degrees and sunny."),
    ]

    evaluation = evaluator(
        outputs=result["messages"],
        reference_outputs=reference_trajectory,
    )
    assert evaluation["score"] is True

你还可以设置 tool_args_match_mode 属性和/或 tool_args_match_overrides 来自定义评估器如何考虑实际轨迹与参考轨迹中工具调用之间的相等性。默认情况下，只有对同一工具具有相同参数的工具调用才被视为相等。访问仓库了解更多详情。

LLM 作为评判的评估器

你可以使用 LLM 通过 create_trajectory_llm_as_judge 函数来评估 Agent 的执行路径。与轨迹匹配评估器不同，它不需要参考轨迹，但如果有的话可以提供。

无参考轨迹

from agentevals.trajectory.llm import create_trajectory_llm_as_judge, TRAJECTORY_ACCURACY_PROMPT

evaluator = create_trajectory_llm_as_judge(
    model="openai:o3-mini",
    prompt=TRAJECTORY_ACCURACY_PROMPT,
)

def test_trajectory_quality():
    result = agent.invoke({
        "messages": [HumanMessage(content="What's the weather in Seattle?")]
    })

    evaluation = evaluator(
        outputs=result["messages"],
    )
    assert evaluation["score"] is True

有参考轨迹

如果你有参考轨迹，请使用预构建的 TRAJECTORY_ACCURACY_PROMPT_WITH_REFERENCE 提示：

from agentevals.trajectory.llm import create_trajectory_llm_as_judge, TRAJECTORY_ACCURACY_PROMPT_WITH_REFERENCE

evaluator = create_trajectory_llm_as_judge(
    model="openai:o3-mini",
    prompt=TRAJECTORY_ACCURACY_PROMPT_WITH_REFERENCE,
)
evaluation = evaluator(
    outputs=result["messages"],
    reference_outputs=reference_trajectory,
)

要了解更多关于 LLM 如何评估轨迹的可配置性，请访问仓库。

异步支持

所有 agentevals 评估器都支持 Python asyncio。异步版本可通过在函数名中的 create_ 后添加 async 来使用。

异步评判和评估器示例

from agentevals.trajectory.llm import create_async_trajectory_llm_as_judge, TRAJECTORY_ACCURACY_PROMPT
from agentevals.trajectory.match import create_async_trajectory_match_evaluator

async_judge = create_async_trajectory_llm_as_judge(
    model="openai:o3-mini",
    prompt=TRAJECTORY_ACCURACY_PROMPT,
)

async_evaluator = create_async_trajectory_match_evaluator(
    trajectory_match_mode="strict",
)

async def test_async_evaluation():
    result = await agent.ainvoke({
        "messages": [HumanMessage(content="What's the weather?")]
    })

    evaluation = await async_judge(outputs=result["messages"])
    assert evaluation["score"] is True

在 LangSmith 中运行评估

为了跟踪随时间变化的实验，请将评估器结果记录到 LangSmith。首先，设置所需的环境变量：

export LANGSMITH_API_KEY="your_langsmith_api_key"
export LANGSMITH_TRACING="true"

LangSmith 提供两种主要方法来运行评估：pytest 集成和 evaluate 函数。

使用 pytest 集成

import pytest
from langsmith import testing as t
from agentevals.trajectory.llm import create_trajectory_llm_as_judge, TRAJECTORY_ACCURACY_PROMPT

trajectory_evaluator = create_trajectory_llm_as_judge(
    model="openai:o3-mini",
    prompt=TRAJECTORY_ACCURACY_PROMPT,
)

@pytest.mark.langsmith
def test_trajectory_accuracy():
    result = agent.invoke({
        "messages": [HumanMessage(content="What's the weather in SF?")]
    })

    reference_trajectory = [
        HumanMessage(content="What's the weather in SF?"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_weather", "args": {"city": "SF"}},
        ]),
        ToolMessage(content="It's 75 degrees and sunny in SF.", tool_call_id="call_1"),
        AIMessage(content="The weather in SF is 75 degrees and sunny."),
    ]

    t.log_inputs({})
    t.log_outputs({"messages": result["messages"]})
    t.log_reference_outputs({"messages": reference_trajectory})

    trajectory_evaluator(
        outputs=result["messages"],
        reference_outputs=reference_trajectory
    )

使用 pytest 运行评估：

pytest test_trajectory.py --langsmith-output

使用 evaluate 函数

创建一个 LangSmith 数据集并使用 evaluate 函数。数据集必须具有以下模式：

input: {"messages": [...]} 用于调用 Agent 的输入消息。
output: {"messages": [...]} Agent 输出中的预期消息历史记录。对于轨迹评估，你可以选择仅保留助手消息。

from langsmith import Client
from agentevals.trajectory.llm import create_trajectory_llm_as_judge, TRAJECTORY_ACCURACY_PROMPT

client = Client()

trajectory_evaluator = create_trajectory_llm_as_judge(
    model="openai:o3-mini",
    prompt=TRAJECTORY_ACCURACY_PROMPT,
)

def run_agent(inputs):
    return agent.invoke(inputs)["messages"]

experiment_results = client.evaluate(
    run_agent,
    data="your_dataset_name",
    evaluators=[trajectory_evaluator]
)

要了解更多关于评估你的 Agent 的信息，请参阅 LangSmith 文档。

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Deploy with LangSmith

安装 AgentEvals

轨迹匹配评估器

LLM 作为评判的评估器

异步支持

在 LangSmith 中运行评估

​安装 AgentEvals

​轨迹匹配评估器

​LLM 作为评判的评估器

​异步支持

​在 LangSmith 中运行评估

安装 AgentEvals

轨迹匹配评估器

LLM 作为评判的评估器

异步支持

在 LangSmith 中运行评估