几乎每个深度使用过大模型 Agent 的开发者都遇到过这种让人头疼的场面你让模型去查一家公司的财务指标再跟行业均值比一比最后给个结论。结果它要么跳过查询直接凭“记忆”编了一个数要么查完第一个数据后第二个要求就忘了要么工具调用了一堆路径却完全错误最后答非所问。问题往往不在单个模型能力上而在“多跳推理 工具调用 信息检索 策略约束”这条完整链路上。我们缺少的正是一个能把这条链路系统化评测的框架。VAKRA 就是针对这个缺口提出的评测思路它把 APIs、Retrieval、Multi-Hop Reasoning 和 Tool-Use Policies 放到同一条测试流水线上让我们不只关心模型“答得对不对”更关心它“会不会调用工具、按什么策略调用、调用错了会怎样”。这篇文章会先讲清楚 VAKRA 到底在测什么、为什么这类评测比传统问答评测更难再以一个可运行的最小 Python 示例演示如何构造一个多跳工具调用任务、如何在代码里落地工具使用策略最后给出链路调优和工程落地的建议。如果你正在做 Agent 开发、RAG 应用或模型评测体系这篇文章可以帮你建立一套更贴近真实生产的评测视角。1. 为什么需要 VAKRAAgent 评测的缺口先看一组常见评测的边界。传统大模型基准比如 MMLU、GSM8K测的是知识储备和单步数学推理它们基本不涉及外部工具RAG 类基准侧重检索质量看召回片段是否相关Agent 类基准则考察工具调用但多数任务停留在“调用一次工具”的层面。真实业务场景很少这么简单。一个金融分析 Agent 的典型任务可能是先在公司知识库里检索最新的财报发布日期再调用财报接口拿营业收入和营业成本计算毛利率然后从行业报告里检索平均毛利率最后综合判断公司竞争力。整个过程至少包含四次工具或检索动作而且每一步的结果都会影响下一步的选择。如果模型在第三步把营收和成本搞反最终判断就是错的如果模型跳过检索直接回答答案可能一本正经地胡说八道。VAKRA 的价值在于它把这四件事统一进一个评测框架Multi-Hop Reasoning考察模型能否用多个已知信息逐步推导而不是一步到位的“记忆检索”。APIs考察模型是否理解工具的语义、参数格式以及多步调用之间的依赖关系。Retrieval考察模型能否在上下文不可信的片段中筛选正确信息并决定下一步检索什么。Tool-Use Policies考察模型是否遵守调用规则例如最多调用几次、哪些工具必须用、哪些关键词禁止进入上下文、超出预算时如何终止。如果只看表面很容易误以为 VAKRA 只是又一个 Agent 排行榜。但更准确的判断是它把评测重心从“结果正确”扩展到了“过程合规”。在业务系统里结果正确但调用链混乱的 Agent后期几乎无法排查调用链清晰但结果差一点的 Agent反而可以通过调整提示词或约束逐步优化。这种“过程 结果”双重评测的思路对工程落地更重要。这篇文章适合三类读者正在做 RAG 应用的开发者想评估自己 Agent 链路是否合格的算法工程师以及准备搭建评测集、为模型选型提供依据的技术负责人。2. VAKRA 的核心概念与适用场景把标题拆开看VAKRA 评测的不是一个单点能力而是四个能力的组合。先逐个理解。概念通俗解释评测关注点Multi-Hop Reasoning需要多步推理才能回答的问题中间信息的顺序、依赖关系、跨文档整合APIs模型可以调用的外部函数或接口工具选择、参数格式、返回结果解析Retrieval从外部知识库中搜索相关片段检索时机、检索词质量、检索结果筛选Tool-Use Policies支配工具调用行为的一组规则调用次数、调用顺序、白名单、安全约束Multi-Hop Reasoning 不是简单的“问一个问题答一个答案”。它要求模型把多个信息片段串联起来。这种串联有两种常见模式顺序多跳和并行多跳。顺序多跳是第 N 步依赖第 N-1 步的结果比如先查营收再算毛利率并行多跳是多个独立信息可以同时取回比如同时检索两家公司的财报最后再比较。VAKRA 这类评测通常两种都会覆盖。Retrieval 在这里不是独立步骤而是推理链的一部分。模型需要自己决定“我现在缺什么信息”“我用什么关键词去检索”“检索回来的片段里哪部分是可信的”。传统 RAG 评测只关心片段是否相关但 VAKRA 评测更关心模型能不能把检索结果正确拼进推理链。检索时机太早或太晚都会导致链路质量下降。Tool-Use Policies 是最容易被忽略、也最容易出问题的部分。策略不是提示词里的“请谨慎调用工具”而是可执行的规则允许调用哪些工具、禁止哪些参数值、最大调用次数、敏感词过滤、超时处理、必须要调用的工具列表。很多 Agent 在 demo 里跑得很好一到生产环境就失控根本原因是策略定义不完整。比如没有限制最大调用次数模型陷入循环没有校验参数模型把过期日期传进去了没有黑名单模型把“内部资料”放进了检索词。从场景上看VAKRA 这类评测最适配的是需要“决策 - 查询 - 再决策”的复杂任务比如金融分析、医疗问答、运维诊断、科研文献综述。像“今天天气怎么样”这种单次 API 调用场景用不上那么多跳而“帮我诊断一下这个服务为什么慢”这类故障排查场景天然就是多跳推理加多工具调用的组合。3. 从任务设计看 VAKRA 的评测逻辑理解一个评测基准最好的方式是看它的任务设计。一个完整的 VAKRA 风格任务至少包含以下要素question一个需要多步推理才能回答的问题。retrieval_targets可能要用到的知识库或文档集合。tools允许模型调用的 API 列表每个工具要有名称、描述、参数说明。policy工具使用策略包括调用上限、白名单、必调工具、禁止词、输出格式。expected_chain期望的调用链或判分规则。下面是一个任务定义的示例它模拟了一个需要“查财报 算指标 检索行业均值”的多跳问题。{ task_id: t001, question: 根据诺德公司的财报数据和已知的行业平均毛利率42%判断诺德公司2024年毛利率是否高于行业平均。, retrieval_targets: [诺德公司2024年年报, 锐新行业研究报告], tools: [ { name: lookup_financial_data, description: 查询公司财报中的指定指标, parameters: [company, metric] }, { name: calc_gross_margin, description: 根据营收和营业成本计算毛利率, parameters: [revenue, cost] }, { name: search_document, description: 从知识库检索相关文档片段, parameters: [query] } ], policy: { max_tool_calls: 4, must_use: [lookup_financial_data], forbidden_keywords: [公司内部资料], answer_format: 简短结论最多100字 }, expected_chain: [ lookup_financial_data, calc_gross_margin, search_document ] }这个 JSON 看起来简单但已经把评测逻辑讲清楚了。答案对错只是其中一项。VAKRA 更关注模型的过程是否符合预期。在 expected_chain 中第一步必须是 lookup_financial_data而不是 search_document。因为题目明确说“财报数据”和“行业平均毛利率”已知正确的方式是先取财报而不是先搜文档。模型如果在第一步就选择检索说明它对工具职责的理解是混乱的。policy 里的 max_tool_calls 是防呆设计。如果模型反复调用同一个工具调用次数超过 4 次评测系统就会判失败并认为模型的规划能力不足。must_use 保证了模型不能偷懒跳过关键查询。forbidden_keywords 则模拟了安全约束任何包含敏感词的输入都不允许进入工具调用参数这是工具使用策略中常见的安全边界。这种设计带来的最大变化是错误定位的粒度。传统评测只会告诉你“这道题错了”VAKRA 风格的任务设计可以告诉你“错在第三跳该用计算工具却用了检索工具”。对于 Agent 开发链路这种定位能力极其宝贵。4. 环境准备与最小评测实践如果你手上暂时没有 VAKRA 的官方代码仓库完全可以先按它的思路搭建一个最小评测环境。这里我们用 Python 模拟一个不依赖真实外部 API 的演示系统目的是把多跳推理和工具策略的流程完整跑通。环境方面建议 Python 3.9 以上版本无需额外框架。如果后续要接入真实 LLM再根据模型厂商的 SDK 调整。这里展示的是评测流程本身所以用了确定性规则代替大模型决策方便读者对照理解每一步。# 创建项目目录 mkdir vakra-demo cd vakra-demo # 创建虚拟环境 python -m venv venv source venv/bin/activate # Windows 下用 venv\Scripts\activate # 无第三方依赖标准库即可运行 python --version先定义一个模拟的工具注册表。这里把三个工具写成普通函数并放在一个字典里模拟真实 Agent 的工具注册机制。# 文件路径vakra-demo/tool_registry.py import re from typing import Callable, Dict def search_document(query: str) - str: 模拟知识库检索返回固定文档片段。 docs { 行业平均毛利率: 锐新行业研究报告显示2024年行业平均毛利率为42%。, 诺德公司营收: 诺德公司2024年报显示营业收入为58.6亿元。, 诺德公司营业成本: 诺德公司2024年报显示营业成本为44.1亿元。, } return docs.get(query, 未检索到相关信息) def calc_gross_margin(revenue: float, cost: float) - float: 计算毛利率。 return round((revenue - cost) / revenue * 100, 2) def lookup_financial_data(company: str, metric: str) - str: 查询财报指标模拟 API 返回。 data { (诺德公司, 营收): 58.6亿元, (诺德公司, 营业成本): 44.1亿元, } return data.get((company, metric), 无数据) TOOL_REGISTRY: Dict[str, Callable] { search_document: search_document, calc_gross_margin: calc_gross_margin, lookup_financial_data: lookup_financial_data, }这里真正容易踩坑的地方是工具参数的类型。calc_gross_margin 的入参是浮点数而 lookup_financial_data 返回的是字符串。真实项目里如果模型把“58.6亿元”原样传给浮点参数工具调用会直接报错。所以工具层需要做解析和容错不能把字符串裸传给数值计算函数。下面定义策略类。策略是 Agent 调用工具前的守门人每一次调用都要经过它允许。# 文件路径vakra-demo/policy.py from typing import Dict, List class ToolPolicy: def __init__( self, tool_registry: Dict, max_tool_calls: int 4, forbidden_keywords: List[str] None ): self.tool_registry tool_registry self.max_tool_calls max_tool_calls self.forbidden_keywords forbidden_keywords or [] self.call_count 0 def check(self, tool_name: str, args: Dict) - bool: if self.call_count self.max_tool_calls: print( f[policy] 达到最大调用次数 {self.max_tool_calls} f拒绝调用 {tool_name} ) return False if tool_name not in self.tool_registry: print(f[policy] 工具 {tool_name} 不在白名单拒绝调用) return False for key, value in args.items(): if any(kw in str(value) for kw in self.forbidden_keywords): print(f[policy] 参数 {key}{value} 包含敏感词拒绝调用) return False self.call_count 1 print( f[policy] 允许调用 {tool_name}累计 {self.call_count}/{self.max_tool_calls} ) return True这个策略类实现了三个常见约束最大调用次数、工具白名单、敏感词过滤。在真实评测中还可以扩展出“必须调用的工具”“禁止连续调用同一工具”“单次调用超时”等规则。策略越细越能测出 Agent 在复杂约束下的表现。5. 核心流程拆解一个多跳工具调用示例现在把上面的模块组装成一个可运行的 Agent 主流程。这个流程明确拆成四跳两跳查数据、一跳算指标、一跳检索行业数据。# 文件路径vakra-demo/agent_demo.py import re from tool_registry import TOOL_REGISTRY from policy import ToolPolicy def agent_loop(question: str) - str: policy ToolPolicy( tool_registryTOOL_REGISTRY, max_tool_calls4, forbidden_keywords[公司内部资料] ) revenue 0.0 cost 0.0 gross_margin None industry_avg None print(f[agent] 开始处理问题{question}\n) # 第一跳查询营收 if policy.check( lookup_financial_data, {company: 诺德公司, metric: 营收} ): result lookup_financial_data(诺德公司, 营收) revenue float(re.search(r(\d\.?\d*)亿元, result).group(1)) print(f[agent] 第1跳结果营收 {result}) # 第二跳查询营业成本 if policy.check( lookup_financial_data, {company: 诺德公司, metric: 营业成本} ): result lookup_financial_data(诺德公司, 营业成本) cost float(re.search(r(\d\.?\d*)亿元, result).group(1)) print(f[agent] 第2跳结果营业成本 {result}) # 第三跳计算毛利率 if policy.check( calc_gross_margin, {revenue: revenue, cost: cost} ): gross_margin calc_gross_margin(revenue, cost) print(f[agent] 第3跳结果诺德公司毛利率 {gross_margin}%) # 第四跳检索行业平均毛利率 if policy.check( search_document, {query: 行业平均毛利率} ): industry_doc search_document(行业平均毛利率) industry_avg float(re.search(r(\d\.?\d*)%, industry_doc).group(1)) print(f[agent] 第4跳结果行业平均毛利率 {industry_avg}%) print() if gross_margin is not None and industry_avg is not None: comparison 高于 if gross_margin industry_avg else 低于 conclusion ( f诺德公司2024年毛利率为{gross_margin}% f{comparison}行业平均毛利率{industry_avg}%。 ) else: conclusion 信息不完整无法得出可靠结论。 print(f[agent] 最终结论{conclusion}) return conclusion if __name__ __main__: agent_loop( 根据诺德公司的财报数据和已知的行业平均毛利率 判断诺德公司2024年毛利率是否高于行业平均。 )这个示例的每一步都有明确意图。第一跳和第二跳是基础数据准备第三跳是推理计算第四跳是补充外部信息。前三跳如果失败比如营收没查到后面的计算和比较就无从谈起这就是顺序多跳依赖的典型表现。有一点要特别说明这里用正则解析工具返回结果在真实项目里是一个需要谨慎设计的环节。工具返回的数据往往有不同格式可能是 JSON、CSV 或纯文本。Agent 的开发框架通常会把结构化输出解析成字典而不是让模型直接处理字符串。这里为了展示链路逻辑故意简化了解析过程。实际生产环境建议工具统一返回 JSON并在工具层完成类型转换。从策略角度看这个 Agent 的调用次数是 4 次正好踩在 max_tool_calls4 的上限。如果哪个环节需要多一次重试策略就会拒绝下一次调用最终结论会变成“信息不完整”。在真实评测里这种边界情况恰恰是 VAKRA 想测的模型在资源受限时是选择继续消耗额外资源还是基于已有信息给出带条件的回答。6. 运行结果与效果验证直接把 demo 跑起来看完整输出。python agent_demo.py预期输出如下[agent] 开始处理问题根据诺德公司的财报数据和已知的行业平均毛利率判断诺德公司2024年毛利率是否高于行业平均。 [policy] 允许调用 lookup_financial_data累计 1/4 [agent] 第1跳结果营收 58.6亿元 [policy] 允许调用 lookup_financial_data累计 2/4 [agent] 第2跳结果营业成本 44.1亿元 [policy] 允许调用 calc_gross_margin累计 3/4 [agent] 第3跳结果诺德公司毛利率 24.74% [policy] 允许调用 search_document累计 4/4 [agent] 第4跳结果行业平均毛利率 42.0% [agent] 最终结论诺德公司2024年毛利率为24.74%低于行业平均毛利率42.0%。如何判断运行成功看三个信号。第一策略日志里展示了 4 次调用都通过了白名单和敏感词检查没有出现“拒绝调用”的拦截。第二Agent 日志的每一跳结果都符合预期营收、成本、毛利率、行业均值的数据没有明显异常。第三最终结论基于完整链路得出并且正确判断出“低于行业平均”。如果输出不符合预期第一步应该看策略日志。如果出现“拒绝调用”说明 Agent 的调用次数或参数触发了策略限制。如果缺少某一跳的日志比如没有第3跳说明上一个条件判断失败需要检查正则解析是否匹配到内容。把这个流程对应到 VAKRA 评测里一个合格的 Agent 评测结果应该同时满足两个维度最终答案正确且调用链与 expected_chain 一致。在上面这个示例里调用链是 lookup_financial_data - lookup_financial_data - calc_gross_margin - search_document与 expected 的“查数据 - 算指标 - 检索行业”语义一致评测就通过。如果模型一上来调用 search_document哪怕最后结论碰巧对了评测也会判定为过程不合格。7. 常见问题与排查方法在构建类似评测链路时下面几类问题出现频率最高。问题现象可能原因排查方式解决方案模型跳过检索直接回答提示词没有强调必须调用工具或评测任务设计时未设置 must_use 策略查看模型输出前缀确认是否生成了工具调用在 policy 中增加 must_use 配置对未调用工具的结果直接判失败重复调用同一个工具模型没有记忆前序调用结果或上下文被截断检查工具调用历史是否完整传入模型上下文增加上下文管理记录已完成的工具调用和返回结果上下文被检索片段撑爆检索返回多个长文档导致超过模型窗口长度观察 token 使用量和报错信息设置检索片段的长度上限对结果做摘要或截断工具参数格式错误工具定义缺少参数类型说明或模型未按 schema 输出查看工具调用日志中的参数值工具定义补充参数类型和示例并在工具层做参数校验策略约束未生效策略代码没有挂在 Agent 主循环上只写在系统提示词里打印策略 check 的调用日志把策略检查前置到工具分发层任何调用都必须经过策略检查工具调用报认证或密钥错误外部 API 的认证配置不正确常见于数据库连接或云服务接口查看异常堆栈和连接配置检查连接串的 SSL 与密钥参数。以 MySQL 为例报错 Public Key Retrieval is not allowed 时通常是因为驱动默认不允许向服务器请求公钥需要确认驱动版本、连接参数和安全策略后决定如何配置最后一项值得多说几句。很多 Agent 调用外部工具时问题不是模型不会选工具而是工具本身没配好。比如访问数据库时需要做公钥交换但安全策略禁用了自动获取公钥于是工具调用一直失败。这类问题表面上和模型能力无关但会直接影响评测结果。在搭建 VAKRA 风格评测时建议先把工具层的连通性验证跑通再让模型去调用否则很容易把工具故障误判成模型能力不足。8. 工程实践与 Agent 设计建议评测框架最终要服务于生产。基于 VAKRA 的评测思路下面这些工程经验值得借鉴。8.1 工具定义要窄而明确不要给 Agent 一个“万能工具”。工具越宽泛模型误用的概率越高。比如把“get_company_financial_data(company, metric)”设计成一个限定公司和指标的窄接口比给一个“execute_sql_query(sql)”的万能接口可靠得多。万能接口虽然灵活但很容易让模型生成有安全风险的 SQL。VAKRA 评测中工具语义清晰度会直接反映在策略合规率上。8.2 策略检查必须在工具分发层而不是提示词层提示词里的“请谨慎调用”是软约束模型可能不遵守。策略代码必须硬编码在工具分发路径上任何工具调用都要经过白名单、次数上限、参数校验这三道关卡。这样即使模型规划出错系统也能兜底保证评测和生产环境的安全边界。8.3 建立多跳追踪日志每一步工具调用都要留下结构化日志内容包括调用顺序、参数、返回结果、耗时、策略是否放行。日志是用来定位链路问题的唯一依据。没有日志评测中发现某道题答错你只能猜是模型的问题还是检索的问题。有了日志一眼就能看出是哪一跳出了错。{ trace_id: a01f8c, step: 3, tool: calc_gross_margin, args: {revenue: 58.6, cost: 44.1}, result: 24.74, policy_allowed: true }8.4 评测集要包含负样本很多人建评测集只收集“预期链路正确”的样本这远远不够。真正有价值的评测集至少要包含三类负样本应当调用工具但模型没有调用的应当按顺序调用但模型跳步的以及应当拒绝调用但模型强行调用的。VAKRA 强调工具使用策略本质上就是要把“合规性”纳入评测。没有负样本你无法测出策略约束有没有生效。8.5 安全与最小权限原则给 Agent 的工具权限遵循最小权限原则。评测环境可以用完整数据集但生产环境只授予满足任务的最小范围。比如只读数据库账号、IP 白名单、敏感字段脱敏。工具策略里的 forbidden_keywords 就是安全边界的一种体现。真实项目里要结合公司安全规范定义哪些内容不能进入模型上下文哪些字段不允许被工具读取。8.6 控制成本和资源上限多跳推理的代价是多次 API 调用。评测时如果不限制调用次数一个难一点的题目可能触发几十次调用成本和耗时都会失控。建议设置与任务复杂度匹配的 max_tool_calls并在评测结果里记录“实际调用次数/允许调用次数”这一指标用它考察模型的路径效率。9. 总结与后续学习方向VAKRA 这类评测真正改变的不是题目难度而是评测视角从“模型会不会说话”转向“模型会不会干活、懂不懂规矩”。一个能正确回答百科知识但盲目调用工具、不遵守调用策略的 Agent在生产环境里反而是隐患。通过把 Multi-Hop Reasoning、APIs、Retrieval、Tool-Use Policies 放在同一条评测链路上团队可以更快定位 Agent 的能力短板而不是把时间浪费在猜错因上。如果你正在搭建自己的 Agent 评测体系我建议先做三件事一是按第 3 节的任务格式整理出十条覆盖多跳推理和策略约束的评测样例二是用第 5 节的最小示例跑通链路确认策略检查和工具分发没有漏洞三是把日志规范提前定义好保证每一跳都可追溯。等这套最小框架稳定后再接入真实模型、真实 API逐步替换模拟数据。后续值得继续深入的方向包括更精细的调用策略评测、Agent 错误恢复能力评估、以及如何在评测中引入自动化裁判。但无论工具链怎么演进核心思路不变Agent 的价值不在于它能调用多少工具而在于它能不能在正确的约束下把工具用对、把链路走完。