评估（“evals”）通过评估 Agent 的执行轨迹（即其生成的消息序列和工具调用）来衡量 Agent 的表现。与用于验证基本正确性的集成测试不同，评估会根据参考答案或评分标准对 Agent 行为进行打分，因此在你修改提示词、工具或模型时，它们对于发现回归问题非常有用。 评估器（evaluator）是一个接收 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与参考轨迹具有相同的消息结构和工具调用，但工具调用顺序可以不同验证信息检索结果，而不关心调用顺序
subsetAgent 只能调用参考轨迹中的工具（不允许额外工具）确保 Agent 不超出预期范围
supersetAgent 至少调用参考轨迹中的工具（允许额外工具）验证已执行最低要求的操作
下面的示例共享同一个基础设置：一个带有 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):
    """获取城市天气信息。"""
    return f"{city} 当前 75 华氏度，晴天。"

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="旧金山天气怎么样？")]
    })

    reference_trajectory = [
        HumanMessage(content="旧金山天气怎么样？"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_weather", "args": {"city": "San Francisco"}}
        ]),
        ToolMessage(content="旧金山当前 75 华氏度，晴天。", tool_call_id="call_1"),
        AIMessage(content="旧金山当前天气为 75 华氏度，晴天。"),
    ]

    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):
    """获取城市活动信息。"""
    return f"{city} 今晚公园有一场音乐会。"

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="今天旧金山有什么活动？")]
    })

    reference_trajectory = [
        HumanMessage(content="今天旧金山有什么活动？"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_events", "args": {"city": "SF"}},
            {"id": "call_2", "name": "get_weather", "args": {"city": "SF"}},
        ]),
        ToolMessage(content="SF 今晚公园有一场音乐会。", tool_call_id="call_1"),
        ToolMessage(content="SF 当前 75 华氏度，晴天。", tool_call_id="call_2"),
        AIMessage(content="今天的 SF：75 华氏度、晴天，今晚公园有音乐会。"),
    ]

    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):
    """获取城市详细天气预报。"""
    return f"{city} 的详细天气预报：本周持续晴天。"

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="波士顿天气怎么样？")]
    })

    # 参考轨迹只要求调用 get_weather，但 Agent 可以调用额外工具
    reference_trajectory = [
        HumanMessage(content="波士顿天气怎么样？"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_weather", "args": {"city": "Boston"}},
        ]),
        ToolMessage(content="波士顿当前 75 华氏度，晴天。", tool_call_id="call_1"),
        AIMessage(content="波士顿当前天气为 75 华氏度，晴天。"),
    ]

    evaluation = evaluator(
        outputs=result["messages"],
        reference_outputs=reference_trajectory,
    )
    assert evaluation["score"] is True
你还可以设置 tool_args_match_mode 属性和/或 tool_args_match_overrides 属性，以自定义评估器判断实际轨迹与参考轨迹中的工具调用是否相等的方式。默认情况下，只有调用同一工具且参数完全相同的工具调用才会被视为相等。更多细节请参阅仓库文档。

​
LLM 作为评审器（LLM-as-judge）评估器

你可以使用 create_trajectory_llm_as_judge 函数，通过 LLM 来评估 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="西雅图天气怎么样？")]
    })

    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="天气怎么样？")]
    })

    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 函数。 
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="旧金山的天气怎么样？")]
    })

    reference_trajectory = [
        HumanMessage(content="旧金山的天气怎么样？"),
        AIMessage(content="", tool_calls=[
            {"id": "call_1", "name": "get_weather", "args": {"city": "SF"}},
        ]),
        ToolMessage(content="旧金山当前 75 华氏度，天气晴朗。", tool_call_id="call_1"),
        AIMessage(content="旧金山当前 75 华氏度，天气晴朗。"),
    ]

    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
创建一个 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 文档。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.