mcpField
A
ag2-evaluation

ag2-evaluation

github.com/ag2ai测试与质量1260 次安装13 周前更新
代码仓库

关于 ag2-evaluation

ag2-evaluation 是用于评估 AG2 Agent 的技能，面向测试、基准评测和回归检查。它通过数据集与评分器运行任务，也可对已有追踪记录评分并比较运行结果。

主要功能

  1. 01定义评估数据集与评分器
  2. 02运行 Agent 并重建追踪
  3. 03内置及自定义评分器
  4. 04保存运行结果并检查回归
  5. 05评估已有追踪记录

适用场景

  1. 01建立 Agent 回归测试门禁
  2. 02衡量回答正确性与工具调用
  3. 03跟踪不同版本的评估指标
  4. 04对生产遥测追踪进行评分

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ag2ai/ag2-skills --skill ag2-evaluation

安装后在 Claude Code 中输入/ag2-evaluation确认已加载。

详细介绍

评估 — 运行、评分并跟踪 Agent

适用场景

  • 评估、测试或基准测试 AG2 Agent，或构建回归测试 / CI 门禁
  • 按正确性、工具使用情况、成本或主观质量为回答评分
  • 跨版本跟踪指标（此更改带来了改进还是回归？）

若要并排比较两个或更多版本，或在排行榜上进行比较，请使用 ag2-eval-comparison。

安装

pip install "ag2[openai,tracing]"

run_agent 会根据 OpenTelemetry spans 重建每个任务的跟踪记录，因此需要安装 tracing 附加项。交付代码前请运行此安装命令。如果无法运行命令，请写明确切的 pip install 命令。

工作流程 — 数据集、Agent、评分器、run_agent

import asyncio
from ag2 import Agent
from ag2.config import OpenAIConfig
from ag2.eval import Suite, run_agent
from ag2.eval.scorers import final_answer_matches

suite = Suite.from_list([
    {"task_id": "france", "inputs": {"input": "Capital of France?"}, "reference_outputs": {"answer": "Paris"}},
    {"task_id": "japan",  "inputs": {"input": "Capital of Japan?"},  "reference_outputs": {"answer": "Tokyo"}},
])
agent = Agent("geographer", prompt="Answer with the capital city.", config=OpenAIConfig(model="gpt-4o-mini"))

async def main():
    result = await run_agent(
        suite, agent=agent,
        scorers=[final_answer_matches(field="answer", matcher="contains")],
        store_dir="./runs",
    )
    print(result.summary())                            # the scorecard
    print(result.pass_rate("final_answer_matches"))    # 1.0

asyncio.run(main())

inputs["input"] 是提示词；reference_outputs 是标准答案（一个 dict——仅检查跟踪记录时可省略）。每个评分器都是一列，通过其 key 查找。

评分器

一个评分器只提出一个问题。其返回类型决定了聚合方式：

返回值聚合方式访问器
bool通过率result.pass_rate(key)
int / float均值 / p50 / p95result.score_stats(key)
str值计数result.value_counts(key)

预置评分器（ag2.eval.scorers）：final_answer_matches(field=, matcher="contains"|"casefold"|"exact")、tool_called(name)、no_tool_errors()、token_budget(n)、failure_attribution(...)、agent_judge(...)。

自定义评分器——装饰一个函数，并通过名称声明其所需内容（outputs、trace、reference_outputs、inputs、task）：

from ag2.eval import scorer

@scorer
def answered_briefly(outputs) -> bool:
    return len(outputs["body"]) < 100      # outputs["body"] = final answer text

对于无法用 == 检查的质量，可使用 agent_judge 评分（请使用与待测 Agent 不同的模型）：

from ag2.eval.scorers import agent_judge
judge = agent_judge(OpenAIConfig(model="gpt-4o"), criterion="Helpful and accurate.", key="quality")

CI — 确定性运行，无需 API 密钥

将模型替换为 TestConfig 磁带（每个任务对应一条预设回复），使 CI 免费且可重复。model_config 是一个 dict[task_id, ModelConfig]——每个任务对应一条磁带——并会覆盖该任务中 Agent 自身的配置：

from ag2.testing import TestConfig

agent = Agent("geographer", prompt="Answer with the capital city.")   # an Agent instance, not a factory

canned = {"france": TestConfig("Paris"), "japan": TestConfig("Tokyo")}
result = await run_agent(suite, agent=agent, scorers=scorers, model_config=canned, store_dir="./runs")
assert result.pass_rate("final_answer_matches") == 1.0      # the gate

持久化、跟踪、评估现有跟踪记录

store_dir= 会为每次运行写入一个 JSON。重新加载过去的运行并比较差异以发现回归；也可以为已有的跟踪记录（例如生产遥测数据）评分，无需重新运行 Agent：

from ag2.eval import load_run, evaluate_traces, DirectoryTraceSource

assert not result.diff(load_run("./runs/<run_id>.json")).regressions   # scorers that flipped pass -> fail
graded = await evaluate_traces(DirectoryTraceSource("./traces"), scorers=scorers, store_dir="./runs")

常见问题

  • 缺少 tracing 附加项 — run_agent 无法重建跟踪记录。请安装 ag2[<provider>,tracing]。
  • 返回类型与聚合方式不匹配 — 通过 / 失败使用 bool，统计数据使用数字，类别使用 str；请通过评分器的 key 查找结果。
  • 回答模型与评分模型相同 — 会导致 agent_judge 出现偏差；请使用不同的评分模型。

深入了解

  • website/docs/user-guide/evaluation/ — getting-started、scorers（目录 + 自定义评分器 + 返回类型规则）、runs、persistence
  • ag2-eval-comparison — 排行榜（run_variants）+ 并排比较（run_pairwise）

评论

支持 Markdown