企业官网建设流程全解析

Agno Evals Cookbook 实战指南：Accuracy、Agent-as-Judge、Performance 与 Reliability 四大评估模式

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno

本文以 Evals Cookbook 为主线，系统讲解 Agno 评测体系中五类可运行的评估模式——准确性（Accuracy）、LLM 裁判（Agent-as-Judge）、性能（Performance）、工具调用可靠性（Reliability）与套件化批量运行（Suite），并结合libs/agno/agno/eval/下的源码实现，说明每类评估类的字段、默认行为与典型用法。读完本文，你可以直接复制 Cookbook 中的示例脚本，对自建 Agent/Team 完成从单次打分到 CI 批量门禁的完整评估闭环。

目录结构：五类评估模式总览

cookbook/09_evals/目录收纳了 Agno 全部可运行的评估示例。按其根 README 的官方目录说明，各子目录职责如下：

此外，该 README 还登记了两个根级文档RESTRUCTURE_PLAN.md与RESTRUCTURE_PROMPT.md，分别用于说明目录重组计划与文件处置、重组任务的实施提示词。

这五类示例对应的底层实现全部位于 libs/agno/agno/eval/ 模块中，共 7 个文件：accuracy.py、agent_as_judge.py、performance.py、reliability.py、suite.py、base.py与utils.py。下文逐类展开。

Accuracy：对照标准答案的事实准确性评估

Accuracy 模式回答的问题是：Agent 给出的回答，和期望的标准答案是否一致？

子目录 accuracy/ 下的文件清单（见其 README）：

• accuracy_basic.py—— 同步与异步两种计算器准确性评估；
• accuracy_9_11_bigger_or_9_99.py—— 数值比较类准确性评估；
• accuracy_team.py—— Team 语言路由准确性评估；
• accuracy_with_given_answer.py—— 对已有输出字符串打分（无需重新跑 Agent）；
• accuracy_with_tools.py—— 带工具 Agent 的准确性评估；
• db_logging.py—— 结果写入 PostgreSQL 的准确性评估；
• evaluator_agent.py—— 使用自定义 evaluator agent 的准确性评估；
• accuracy_eval_metrics.py—— 将评估模型指标按eval_modeldetail key 累加到 Agentrun_output。

基本用法

accuracy_basic.py 给出了最典型的同步/异步双例：

from agno.agent import Agent from agno.eval.accuracy import AccuracyEval, AccuracyResult from agno.models.openai import OpenAIChat from agno.tools.calculator import CalculatorTools evaluation = AccuracyEval( name="Calculator Evaluation", model=OpenAIChat(id="o4-mini"), # 评估器模型 agent=Agent( model=OpenAIChat(id="gpt-5.6-luna"), tools=[CalculatorTools()], ), input="What is 10*5 then to the power of 2? do it step by step", expected_output="2500", additional_guidelines="Agent output should include the steps and the final answer.", num_iterations=1, ) result: Optional[AccuracyResult] = evaluation.run(print_results=True) assert result is not None and result.avg_score >= 8

异步版本只需改为await async_evaluation.arun(print_results=True)，并把num_iterations调大以观察多次运行的avg_score。

源码层字段说明

从源码结构看，AccuracyEval 是一个@dataclass，核心字段如下：

• input/expected_output：均为Union[str, Callable]，即输入和标准答案都支持函数动态生成；
• agent/team：二选一，分别评估 Agent 或 Team；
• num_iterations：迭代次数，默认 1，多次运行的均值即avg_score；
• model：评估器模型。从源码看，若未指定，默认回退到OpenAIChat(id="o4-mini")，并要求已安装openai包（见 get_evaluator_agent）；
• evaluator_agent：直接传入完整自定义评估 Agent，优先于model/additional_guidelines等字段生效；
• additional_guidelines：字符串或字符串列表，会被拼接为“## Additional Guidelines”段落注入评估器提示词；
• print_summary/print_results：是否打印汇总表与明细；show_spinner控制进度 spinner，嵌入运行器（如 suite）时会被关闭以避免控制台噪音；
• file_path_to_save_results：结果落盘路径，支持{name}与{run_id}占位符；
• db：指定数据库后评估结果持久化；debug_mode默认读取环境变量AGNO_DEBUG。

运行结束后，print_results会以表格形式渲染Accuracy Score x/10与Accuracy Reason两行（见 accuracy.py 渲染逻辑），result.score为 0-10 分制的单轮得分。

Agent-as-Judge：用模型给开放式输出打质量分

当问题没有唯一标准答案时（如“解释 API 是什么”），Agent-as-Judge 模式用一个裁判模型按你给定的criteria对输出质量打分。子目录 agent_as_judge/ 的文件清单（见其 README）覆盖：

• agent_as_judge_basic.py—— 同步/异步数值打分并持久化结果；
• agent_as_judge_post_hook.py/agent_as_judge_team_post_hook.py—— Agent/Team 的 post-hook 评估；
• agent_as_judge_batch.py—— 批量 Case 评估并输出汇总；
• agent_as_judge_binary.py—— PASS/FAIL 二元判定；
• agent_as_judge_custom_evaluator.py—— 自定义裁判 Agent；
• agent_as_judge_team.py—— 评估 Team 生成的响应；
• agent_as_judge_with_guidelines.py/agent_as_judge_with_tools.py—— 附加评分指南、评估带工具 Agent；
• agent_as_judge_eval_metrics.py—— 通过 post-hook 将评估模型指标记录到eval_modeldetail key。

基本用法：带阈值回调与数据库持久化

agent_as_judge_basic.py 展示了完整链路——先跑业务 Agent，再对响应打分，最后从数据库回查评估运行记录：

def on_evaluation_failure(evaluation: AgentAsJudgeEvaluation): """评估分低于阈值时触发的回调。""" print(f"Evaluation failed - Score: {evaluation.score}/10") print(f"Reason: {evaluation.reason[:100]}...") sync_db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai") sync_agent = Agent( model=OpenAIChat(id="gpt-5.6-luna"), instructions="You are a technical writer. Explain concepts clearly and concisely.", db=sync_db, ) sync_evaluation = AgentAsJudgeEval( name="Explanation Quality", criteria="Explanation should be clear, beginner-friendly, and use simple language", scoring_strategy="numeric", threshold=7, on_fail=on_evaluation_failure, db=sync_db, ) sync_response = sync_agent.run("Explain what an API is") sync_evaluation.run( input="Explain what an API is", output=str(sync_response.content), print_results=True, print_summary=True, ) sync_eval_runs = sync_db.get_eval_runs() # 回查已持久化的评估运行

该示例的几个关键点：

1. scoring_strategy="numeric"表示 0-10 数值打分；agent_as_judge_binary.py则演示 PASS/FAIL 二元策略；
2. threshold是失败阈值，低于它即触发on_fail回调，回调入参 AgentAsJudgeEvaluation 携带score与reason字段，便于接入告警或 CI 门禁；
3. db同时挂给业务 Agent 和评估器时，评估运行会落库，可通过db.get_eval_runs()取回，示例中异步版用AsyncSqliteDb(db_file="tmp/agent_as_judge_async.db")演示了同一能力的 SQLite 异步实现；
4. 异步流程为await agent.arun(...)后await evaluation.arun(input=..., output=..., print_results=True, print_summary=True)。

从源码结构看，AgentAsJudgeEval 与AccuracyEval同属BaseEval体系（见 base.py），因此同样具备db、telemetry、结果打印等通用能力；两者的分工是：Accuracy 对照标准答案，Agent-as-Judge 对照质量准则。

Performance：运行时与内存基准

performance/ 目录的基准用例清单（见其 README）：

子目录 performance/comparison/ 则把基准对象换成其他框架的 Agent 实例化过程，包含autogen_instantiation.py、crewai_instantiation.py、langgraph_instantiation.py、openai_agents_instantiation.py、pydantic_ai_instantiation.py、smolagents_instantiation.py六个示例，用于横向比较不同框架的启动成本。对应的底层实现见 libs/agno/agno/eval/performance.py。

Reliability：验证期望的工具调用是否真的发生

Reliability 模式不关心回答措辞，只验证一件事：Agent 是否按预期调用了正确的工具。子目录 reliability/ 的文件清单（见其 README）：

• db_logging.py—— 结果写入 PostgreSQL 的可靠性评估；
• reliability_async.py—— 异步可靠性评估流程；
• single_tool_calls/calculator.py—— 单一期望计算器工具调用的可靠性；
• multiple_tool_calls/calculator.py—— 多工具计算器调用链的可靠性；
• team/ai_news.py—— Team 委派与联网搜索工具调用链的可靠性。

对应实现为 ReliabilityEval。这一模式的典型断言方式，在 suite_basic.py 中也有体现：Case支持expected_tool_calls=("factorial",)字段，即声明该用例必须调用factorial工具。

Suite：多 Case 批量运行、标签筛选与 CI 集成

suite/ 是把单点评估升级为评估套件的一层：把多个Case聚合成一次运行，提供标签选择、按名筛选、JSON 报告与 CI 退出码。其 README 说明的两个示例为：

• suite_basic.py—— 两个 Case（judge 打分 + reliability 工具调用检查）走内置cli()运行；
• suite_team_scoring.py—— Team 场景：leader 委派给 calculator 成员与 writer 成员，reliability 能看到成员的工具调用，每个回答再由 1-10 数值 judge 打分。

CLI 用法（可直接复制）

python cookbook/09_evals/suite/suite_basic.py # 运行全部 Case python cookbook/09_evals/suite/suite_basic.py --list # 只列出 Case，不执行 python cookbook/09_evals/suite/suite_basic.py --tag smoke # 只跑打了 smoke 标签的子集 python cookbook/09_evals/suite/suite_basic.py --name factorial_uses_calculator python cookbook/09_evals/suite/suite_basic.py --json-output tmp/evals.json python cookbook/09_evals/suite/suite_basic.py -v # 每个 Case 打印完整运行面板

最小可运行的 Suite 示例

suite_basic.py 全文要点：

from agno.agent import Agent from agno.eval import Case, cli from agno.models.openai import OpenAIResponses from agno.tools.calculator import CalculatorTools agent = Agent( id="math-tutor", model=OpenAIResponses(id="gpt-5.5"), tools=[CalculatorTools()], instructions="Use the calculator tools for any arithmetic.", ) CASES = ( Case( name="factorial_uses_calculator", agent=agent, input="What is 10! (ten factorial)?", tags=("smoke",), # 供 --tag smoke 筛选 criteria="States that 10! equals 3628800.", # judge 打分准则 expected_tool_calls=("factorial",), # reliability 检查 ), Case( name="explains_compound_interest", agent=agent, input="Explain compound interest in one short paragraph.", criteria="Explains that interest is earned on both the principal " "and previously earned interest.", ), ) if __name__ == "__main__": sys.exit(cli(CASES)) # 退出码即 CI 门禁信号

Case把两类检查合并在一条声明里：criteria触发 Agent-as-Judge 打分，expected_tool_calls触发 Reliability 工具调用校验——这正是前文两个模式的组合使用。

对于 CI 工作流或程序化嵌入场景，README 明确建议不走控制台路径：调用run_cases(CASES)或await arun_cases(CASES)，然后读取SuiteResult.to_dict()生成报告；该编程入口不做任何控制台 I/O，适合嵌入流水线或测试框架。

运行前提与工程建议

• 默认评估器依赖：Accuracy 与 Agent-as-Judge 在未显式指定评估模型时，源码会回退到OpenAIChat(id="o4-mini")并要求安装openai包（见 accuracy.py）；
• 数据库为可选项：db字段在 Accuracy、Agent-as-Judge、Reliability 示例中均可选挂接（PostgreSQL / SQLite 等），挂接后评估运行可通过get_eval_runs()回查，便于离线复盘与趋势跟踪；
• 调试开关：各评估类的debug_mode默认读取AGNO_DEBUG环境变量，无需改代码即可打开调试日志；
• 遥测：telemetry默认为True，记录最小遥测用于改进评估功能；
• 组合策略：单点回归用 Accuracy（有标准答案）或 Agent-as-Judge（开放式问题）；上线门禁用 Suite 聚合多种Case，以退出码驱动 CI，并以--json-output落盘报告。

以上所有示例均可在cookbook/09_evals/对应子目录中直接找到并运行，配套测试记录见各子目录的TEST_LOG.md与根级 TEST_LOG.md。

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno