许多智能体行为只有在使用真实 LLM 时才会出现，例如智能体决定调用哪个工具、如何格式化响应或提示修改是否影响整个执行轨迹。LangChain 的 agentevals 包提供专门设计用于使用实时模型测试智能体轨迹的评估器。
本指南涵盖开源 LangChain agentevals 包，它与 LangSmith 集成以进行轨迹评估。
AgentEvals 允许您通过执行_轨迹匹配_或使用 _LLM 评判者_来评估智能体的轨迹（包括工具调用的确切消息序列）：

轨迹匹配

为给定输入硬编码参考轨迹，并通过逐步比较验证运行。非常适合测试您知道预期行为的明确定义的工作流程。当您对应该调用哪些工具以及以什么顺序调用有特定期望时使用。这种方法是确定性的、快速的且具有成本效益，因为它不需要额外的 LLM 调用。

LLM 作为评判者

使用 LLM 定性验证智能体的执行轨迹。“评判者”LLM 根据提示标准（可以包括参考轨迹）审查智能体的决策。更灵活，可以评估效率和适当性等细微方面，但需要 LLM 调用且不太确定性。当您想评估智能体轨迹的整体质量和合理性而不需要严格的工具调用或顺序要求时使用。

​
安装 AgentEvals

pip install agentevals
或者，直接克隆 AgentEvals 存储库。

​
轨迹匹配评估器

AgentEvals 在 Python 中提供 create_trajectory_match_evaluator 函数，在 TypeScript 中提供 createTrajectoryMatchEvaluator，以将智能体的轨迹与参考轨迹进行匹配。 您可以使用以下模式：
模式描述用例
strict以相同顺序精确匹配消息和工具调用测试特定序列（例如，授权前的策略查找）
unordered允许以任何顺序进行相同的工具调用当顺序无关紧要时验证信息检索
subset智能体仅调用参考中的工具（无额外）确保智能体不超出预期范围
superset智能体至少调用参考工具（允许额外）验证采取最低要求的操作

​
严格匹配

strict 模式确保轨迹以相同顺序包含具有相同工具调用的相同消息，尽管它允许消息内容有所不同。当您需要强制执行特定的操作序列时，这很有用，例如在授权操作之前需要策略查找。 
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("gpt-4o", tools=[get_weather])

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 模式允许以任何顺序进行相同的工具调用，当你想要验证正在调用正确的工具集但不关心顺序时，这很有用。例如，智能体可能需要检查城市的天气和事件，但顺序无关紧要。 
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}."

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

agent = create_agent("gpt-4o", 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 shows tools called in different order than actual execution
    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,
    )
    # {
    #     'key': 'trajectory_unordered_match',
    #     'score': True,
    # }
    assert evaluation["score"] is True

​
子集和超集匹配

superset 和 subset 模式关注调用哪些工具而不是工具调用的顺序，允许你控制智能体的工具调用必须与参考对齐的严格程度。
  • 当你想要验证在执行中调用了几个关键工具，但允许智能体调用其他工具时，使用 superset 模式。智能体的轨迹必须至少包括参考轨迹中的所有工具调用，并且可以包括超出参考的其他工具调用。
  • 使用 subset 模式通过验证智能体没有调用参考之外的任何无关或不必要的工具来确保智能体效率。智能体的轨迹必须仅包括出现在参考轨迹中的工具调用。
以下示例演示了 superset 模式，其中参考轨迹仅需要 get_weather 工具，但智能体可以调用其他工具： 
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}."

@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("gpt-4o", 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,
    )
    # {
    #     'key': 'trajectory_superset_match',
    #     'score': True,
    #     'comment': None,
    # }
    assert evaluation["score"] is True
你还可以通过设置 tool_args_match_mode（Python）或 toolArgsMatchMode（TypeScript）属性以及 tool_args_match_overrides（Python）或 toolArgsMatchOverrides（TypeScript）属性来自定义评估器如何考虑实际轨迹与参考轨迹中工具调用之间的相等性。默认情况下，只有对同一工具使用相同参数的工具调用才被视为相等。访问存储库以获取更多详细信息。

​
LLM 作为评判者评估器

本节涵盖来自 agentevals 包的特定于轨迹的 LLM 作为评判者评估器。有关 LangSmith 中的通用 LLM 作为评判者评估器，请参阅 LLM 作为评判者评估器。
你也可以使用 LLM 来评估智能体的执行路径。与轨迹匹配评估器不同，它不需要参考轨迹，但如果可用，可以提供参考轨迹。

​
无参考轨迹

from langchain.agents import create_agent
from langchain.tools import tool
from langchain.messages import HumanMessage, AIMessage, ToolMessage
from agentevals.trajectory.llm import create_trajectory_llm_as_judge, TRAJECTORY_ACCURACY_PROMPT


@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("gpt-4o", tools=[get_weather])

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"],
    )
    # {
    #     'key': 'trajectory_accuracy',
    #     'score': True,
    #     'comment': 'The provided agent trajectory is reasonable...'
    # }
    assert evaluation["score"] is True

​
有参考轨迹

如果你有参考轨迹，可以在提示中添加额外变量并传入参考轨迹。下面，我们使用预构建的 TRAJECTORY_ACCURACY_PROMPT_WITH_REFERENCE 提示并配置 reference_outputs 变量： 
evaluator = create_trajectory_llm_as_judge(
    model="openai:o3-mini",
    prompt=TRAJECTORY_ACCURACY_PROMPT_WITH_REFERENCE,
)
evaluation = judge_with_reference(
    outputs=result["messages"],
    reference_outputs=reference_trajectory,
)
有关 LLM 如何评估轨迹的更多可配置性，请访问存储库。

​
异步支持（Python）

所有 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
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.