Google ADK 提议为工具调用记录授权依据
Google ADK Python 社区提出为工具调用持久化授权、拒绝和审批记录,并已提交 PR #8224 供审查。提案将执行轨迹与授权证据分开记录,后者包含调用主体、认证方式及策略来源和版本等字段。
AI 深度解读
一次 Agent 调用出了事故,日志里能看到工具名、参数和返回值,排查还是可能卡在三个问题上:谁授权的、按哪版策略授权的、实际执行的参数是不是当时批准的那一组?google/adk-python 的 issue #6099 围绕这些问题讨论了 79 条评论,随后有了可供维护者审阅的 PR #8224。
作者提炼出的方案,是给每次工具调用留一份可核对的授权记录,再用执行回执核验保存下来的结果。对接过 AI 工具调用的程序员,可以把它当成一次接口设计审查:现有日志里,哪些字段真能追溯到授权,哪些只够帮助排查?
一次调用的授权依据,该记在哪?
决策台账(decision ledger)记录框架在分发工具调用时掌握的授权事实。执行链路(trace)和会话事件可以告诉你哪个工具跑了、什么时候跑的。要查这次调用凭什么能跑,还得找到授权主体、审批和策略版本。两种记录可以通过调用 ID 关联起来。
讨论把字段按来源分成三类:
- 框架能确认的字段包括工具名、调用或步骤 ID、授权主体(principal)、授权模式、策略来源及版本、确认 ID、决策状态和时间戳。
- 从调用计算出来的字段包括规范化参数的摘要,以及有结果时的结果摘要。这里的「摘要」是用于核验内容的哈希值。先约定参数怎样转成字节,相同参数才能在复核时算出相同的值。
- 模型给出的行动理由属于待核实的上下文。它可以帮助人工理解模型当时的判断,授权依据仍要从框架记录的主体、策略和确认信息里查。
这个区分对调试也有用。模型说「用户已经确认」时,排查者可以沿着确认 ID 找到对应记录,再核对它覆盖的工具调用。
为什么要显式保存「无法判定」,还得逐次核验?
首先,缺一条台账记录会带来歧义:这次本来就无需决策,还是本应记录的决策漏写了?前者可能是正常流程,后者需要追查。讨论提出,把「无法判定」(cannot-tell)存成明确的状态值,让查阅者知道系统当时就无法给出结论。
其次,批准工具名还不够。批准一次调用时,要对当时的规范化参数计算摘要。调用完成后,再记录结果摘要,并让结果指回对应的决策。这样复核者就能检查实际执行的参数是否与获批参数一致,也能把结果对应到具体那一次调用。
最后,一条模型响应里可能有多次工具调用。拒绝其中一次,无法推出其余调用的授权状态。即便界面把 40 次调用汇总成一个运行状态,审计仍应逐条查阅原始记录。
这些讨论进入了 PR #8224。docs/source-reads-6099.md 用五条记录列出检查领域、发现、严重程度及能否从固定提交复核,覆盖单次调用的完整性绑定、台账聚合、评估器来源绑定、不可逆操作的授权,以及审计字段与身份的绑定,并保留 cannot-tell 层级。配套的 docs/guides/decision-table-crosswalk.md 将授权决策表与测试用例对照。作者给出的证据来自对框架源码的独立阅读,相关判断固定到具体提交。按原文所述,PR 是否合入仍由维护者决定。
已经拿到执行回执,还需要授权记录吗?
需要回答的是两个时间点的问题。决策台账保存调用前的授权依据,执行回执(execution receipt)则让第三方事后检查输入和保存结果对应的记录。作者用 Brennan Zambo 创建的 AER-1 举例。按原文所列,草案版本为 draft-zambo-aer1-26,回执绑定已记录的输入和保存的结果,并对规范化后的回执字节计算 SHA-256 摘要。
AER-1 定义了五种结果值:verified、verification failed、rejected: unresolvable record、not checked、absent。后两项分别表示「未检查」和「记录缺失」,与 ADK 讨论的做法相通,都是把核验者需要区分的状态明确存下来。作者给出的公开测试集有 143 个测试向量和 146 项检查,文档记录了 1 个通过完整公开测试集的实现。结果内容是否正确,仍需单独验证。
作者还给出了 Zambo 的生产快照。一个 MCP 端点提供 153 个工具,默认开放 37 个。截至原文撰写当日上午,公开计数为 146,756 份回执,其中当天 796 份,另有 125,550 次工具调用、329,812 次软件包下载和 21 位持有通行证的已验证付费用户。作者还举了一次实时 BTC 价格查询,读者可以用公开验证页面重新计算那次回执的摘要。产品默认每个工具每天免费用 1 次,另含 3 次 continue 调用,每天可免费做 1 次收尾交接,pickup 始终免费。原文记录的一笔 Day Pass 订单为 $0.99,可解除限制 24 小时。
我的判断
这篇最有说服力的是逐次核对授权的理由。同一条响应里,各工具调用的参数、授权模式和审批情况都可能不同。若现有结构化日志能稳定保留逐次决策、策略版本、确认 ID 和参数摘要,可以先沿用同一套存储。排查时能否可靠地找到这组字段,比先决定建不建独立的表更重要。
源码阅读能支持作者对特定提交的字段判断,公开测试集能检验实现对已发布用例的符合程度。生产计数说明有人在用,也有记录可供抽查。至于引入台账后能缩短多少排查时间、要付出多少存储和维护成本、比扩展现有 trace 有多大收益,原文没有给对照数据。把两种记录都列为所有团队的标配,仍是作者的经验判断。
一般团队还得回答一个落地问题:谁有权限改记录?如果执行服务可以同时覆盖保存的结果和对应摘要,重算一致也很难提供独立证据。能否核验历史,取决于复核者拿到的原始记录及其存储权限。
能拿来做什么
- 给 Node 工具分发层补齐逐次授权记录,在调用发出前保存调用 ID、授权主体、策略版本、确认 ID 和决策状态,并把「无法判定」定义成明确值。
- 如果审批后的参数还会被默认值或中间件改写,在实际分发前核对最终参数的摘要。工具返回后,记录结果摘要,并用调用 ID 关联决策。
- 在前端运行详情里为每个工具调用单独显示授权和核验状态。运行概览可以保留,再用同一响应里部分调用获批、部分被拒的用例检查列表是否准确。