第6章 工具增强型Agent的评测体系本章你将学到为什么“最终输出正确”不等于“过程正确”在评测体系中新增工具调用审计维度构建包含工具调用链的黄金标准测试集用Trae生成扩展后的评测Agent和批量评测脚本跑通完整评测流程基于数据做一次迭代优化本章你将产出一套能同时评估“输出质量”和“工具使用质量”的评测系统以及一份包含工具调用审计的评测报告全部章节收录在专栏《AI应用工程化实战教程》之【智能体工具使用实战】6.1 评测的新挑战在第一部【AI智能体工程化实战】中评测的逻辑很清晰Agent输出一个JSON你把它的valid字段和黄金标准的gt_label做对比。一致就对了不一致就错了。评测Agent只看两样东西——业务Agent的输出和GT——然后给出match或不match。现在情况变了。你的数据分析助手Agent在一次任务中可能会经历这样的过程用户提问 → Agent调用 read_file → Agent调用 execute_python → Agent调用 write_file → Agent输出总结最终它生成了一份analysis_report.md也输出了总结文字。你打开报告一看——数据正确格式清晰结论合理。看起来不错。但你有想过这些问题吗它有没有在应该用execute_python的时候选择了自己“心算”它有没有把read_file的参数写错导致读了错误的文件只是恰好那个文件也有类似数据它有没有调了三次工具但其实一次就够了浪费API调用它有没有在某个工具调用失败后假装什么都没发生继续编造结果最终输出正确不代表过程正确。如果Agent第一次就读错了文件但恰好数据相似如果它跳过了计算步骤直接编造了数字你只看最终输出是发现不了的。这就是工具增强型Agent评测面临的新挑战你不仅要评“说了什么”还要评“做了什么”。6.2 工具调用审计维度参照第一部L1/L2/L3三层指标体系的设计思路我们在第二部的评测体系中新增一个工具调用审计模块。它在L2业务指标层面增加了一个全新的评估维度。6.2.1 新增错误类型代码在评测Agent的判定逻辑中原有的错误类型FP、FN、RE仍然有效——它们评的是最终输出。但我们需要新增一组专门针对工具调用的错误代码错误代码全称含义示例TWTool Wrong工具选择错误——应该用A工具却用了B或者应该用工具却直接回答需要计算平均值Agent没有调execute_python而是自己“估算”了一个数字PAParameter Error参数错误——工具选对了但参数传错了调用了read_file但path写成了score.csv而不是scores.csvEXExecution Error工具执行异常——工具选对了参数也对了但执行失败Agent没有正确处理沙盒返回了超时错误Agent却假装成功继续编造后续结果TCTool Call Missing缺少必要的工具调用——GT预期应该调用的工具Agent没有调用GT预期需要调execute_python进行计算但Agent跳过了这一步这四个代码和原有的OK、FP、FN、RE一起构成了扩展后的错误分类体系。6.2.2 审计的逻辑工具调用审计的核心逻辑是把Agent实际调用的工具序列和GT中标注的“预期工具调用序列”做比对。比对什么工具名称Agent调用的工具是否在预期列表中调用顺序工具的调用顺序是否合理这一步不强制完全一致但如果顺序明显错误——比如先写文件再读文件——应该标记关键参数对于决定性参数如文件路径是否与GT一致缺失调用GT预期必须发生的工具调用Agent是否跳过了多余调用Agent是否调用了不需要的工具浪费一个完整的工具调用审计结果包含{tool_audit:{overall:OK/TW/PA/EX/TC,expected_tools:[read_file,execute_python],actual_tools:[read_file,execute_python,write_file],match_details:[{step:1,expected:read_file,actual:read_file,match:true,param_match:true},{step:2,expected:execute_python,actual:execute_python,match:true,param_match:true}],issues:[]}}6.3 构建含工具调用链的GT测试集6.3.1 扩展GT结构第一部的GT是一条简单的标签有效或无效。第二部的GT需要扩展为包含两部分final_output预期的最终输出与第一部相同用于评估输出质量expected_tool_calls预期的工具调用序列每个调用包含工具名、关键参数、是否必须一个完整的GT条目结构如下{test_id:T001,user_request:请读取 scores.csv计算高数平均分保存报告为 高数分析.md,setup:{files:{scores.csv:已存在于项目根目录}},expected_tool_calls:[{tool_name:read_file,params:{path:scores.csv},required:true,note:读取成绩数据},{tool_name:execute_python,params_check:code 参数中应包含 df[高数].mean() 或类似的计算逻辑,required:true,note:计算高数平均分},{tool_name:write_file,params:{path:高数分析.md},required:true,note:保存分析报告}],expected_final_output:{should_contain:[高数平均分,高数分析.md],should_not_contain:[无法读取,没有数据],format:自然语言总结}}6.3.2 用Trae生成测试集在Trae对话面板中输入在项目>6.3.3 审查并校准GT生成测试集后打开data/test_cases.json你需要人工审查至少3条关键的GT条目审查T001正常场景预期的工具调用顺序是否合理有没有遗漏必要的调用审查文件不存在场景Agent的预期行为是“处理错误不崩溃”。GT中是否体现了这一点审查多文件读取场景工具调用顺序是否可能有两种合理路径如果是GT不应该定死唯一路径。一个重要的原则GT中expected_tool_calls的required: true/false标记要慎重。如果某个工具调用确实不可或缺标true如果只是推荐但不是必须的标false。过于严格的GT会导致评测失真——Agent用了另一种同样合理的方式却被扣分。6.4 用Trae生成扩展版评测Agent现在我们需要一个能同时评“输出”和“工具”的评测Agent。6.4.1 评测Agent的系统提示词在Trae对话面板中输入在项目>6.4.2 生成批量评测脚本在Trae对话面板中继续输入在项目>6.4.3 修改 agent.py 使其返回执行日志评测需要Agent的执行日志。我们需要修改agent.py中的run_agent函数让它在返回最终回答的同时也返回工具调用的完整记录。在Trae对话面板中输入请修改 agent.py 中的 run_agent 函数。 ## 修改要求 1. 函数签名改为 run_agent(user_query: str) - tuple[str, str] 返回(最终回答文本, 执行日志字符串) 2. 在函数内部维护一个 log_lines 列表记录每一步 - 用户请求 - 每一轮API调用模型是否返回了 tool_calls - 每个工具调用工具名、参数JSON格式、返回结果前200字符 - 最终回答 3. 日志格式示例 [用户请求] 请读取 scores.csv... [第1轮] 模型调用工具: read_file({path: scores.csv}) [工具返回] 学号,姓名,高数... [第2轮] 模型调用工具: execute_python({code: import pandas...}) [工具返回] 72.3 [第3轮] 模型最终回答: 高数平均分为72.3分... 4. 将 log_lines 用换行符拼接为字符串与最终回答一起返回 5. 同时更新脚本底部的测试入口适配新的返回值格式6.5 运行评测与分析所有组件就绪。现在跑通完整的评测流程。6.5.1 运行评测在Trae终端中执行python run_evaluation.py你会看到终端里逐个显示每个测试用例的执行过程和评测结果。运行完成后打开evaluation_report.json。6.5.2 解读评测报告评测报告的summary部分类似这样{summary:{total:8,avg_overall_score:78.5,avg_output_score:85.0,avg_tool_score:72.0,error_distribution:{OK:5,TW:1,PA:1,EX:1,TC:0}}}重点关注avg_tool_score——它往往低于avg_output_score。这说明Agent的最终输出看起来还行但工具使用过程存在问题。这正是只看最终输出发现不了的“水下冰山”。查看error_distributionTW工具选择错误最多Agent在判断“该用什么工具”时有问题。需要优化系统提示词中工具使用的指引或者优化工具描述让它更容易被正确选择。PA参数错误最多Agent选了正确的工具但参数传错了。检查工具描述中的parameters定义——参数名是否清晰description是否说明了参数格式EX执行异常最多工具执行失败但Agent没正确处理。可能是沙盒拦截了某些操作但Agent没有读取错误信息并调整。TC缺少工具调用最多Agent跳过了必要的工具调用。可能是在系统提示词中没有强调“必须先读文件再分析”。打开details列表找到得分最低的那个测试用例。仔细阅读它的tool_audit.match_details和issues理解Agent到底在哪个步骤出了问题。6.6 基于评测数据做一次迭代优化假设你的评测报告显示T003多文件对比分析场景的tool_audit.error_type是PA原因是Agent在读取第二个文件时路径写成了scores2.csv但实际文件是scores_2.csv。这个问题的根因可能是Agent在第一次read_file拿到第一个文件内容后没有仔细核对第二个文件的路径而是凭“感觉”写了一个类似的文件名。修改方向在系统提示词中增加对文件路径的强调。在Trae对话面板中输入请修改 agent.py 的系统提示词在工具使用指引中增加一条 在使用 read_file 工具时务必使用用户提供的精确文件路径。如果需要读取多个文件每读取一个文件前都要确认文件名。如果文件不存在仔细检查路径拼写修正后重试。修改完成后重新运行评测python run_evaluation.py对比两次evaluation_report.json中 PA 错误的数量变化。用Git记录这次迭代gitaddagent.py evaluator.py run_evaluation.py data/ evaluation_report.jsongitcommit-mv1.1: 扩展评测体系增加工具调用审计。修改系统提示词修复PA问题工具审计分从72提升至XX6.7 本章小结“最终输出正确”不等于“过程正确”。工具增强型Agent的评测必须同时评估输出质量和工具使用质量。新增四种工具调用错误代码TW工具选择错误、PA参数错误、EX执行异常处理不当、TC缺少必要工具调用。GT结构扩展从单一标签变为expected_tool_callsexpected_final_output。工具调用序列包含工具名、参数、是否必须。评测Agent也升级了从“比对最终输出”升级为“审计完整执行日志”。执行日志需要Agent主动记录每一步工具调用。迭代优化依然是闭环评测→归因→修改→再评测。与第一部的工程化方法论完全一致。下一章是第二部能力跃迁的顶点——你将让Agent自己给自己造工具。当它发现现有工具箱缺少某个功能时自动生成Python代码、保存为工具文件、注册到ToolManager、然后调用。课后练习打开evaluation_report.json找出tool_audit.error_type不是OK的测试用例。阅读它的issues和match_details分析Agent到底在哪个环节出了问题。如果你发现某个工具调用错误反复出现比如总是PA尝试定位根因——是工具描述不够清晰还是系统提示词中的使用指引有歧义修改后重新评测观察指标变化。进阶在评测体系中增加一个效率指标Agent实际使用的工具调用次数与GT中required调用次数的比值。如果Agent调了5次工具但GT只需要3次这个指标会反映“过度调用”问题。修改evaluator.py实现这个指标。进阶思考如果一个任务存在多种同样合理的工具调用路径比如可以先计算再筛选也可以先筛选再计算评测体系应该如何避免“路径唯一性偏见”写下你的设计思路。
