AI Agent 工具调用要能失败、重试和审计

先看工程边界，再谈模型能力

AI 工程最怕把能力说得太满，却没有说明工具、数据、权限、失败和审计在哪里发生。 一个系统能不能进入真实使用，不取决于一次回答有多漂亮，而取决于错误发生时能不能退回、复测和解释。

Agent 的可靠性不来自它说话像人，而来自每一次工具调用都可控、可失败、可追溯。

把 Agent 当成一个更会聊天的搜索框，会低估工具调用风险。

从现场问题开始

Agent 被允许调用查询、下载、发送、写库四类工具，如果没有权限和确认边界，它可能在回答问题时顺手执行了不该执行的动作。

schema 是第一道边界

工具参数要有类型、枚举、必填项和描述。自由文本参数越多，模型越容易把意图、对象和约束混在一起。

权限不能交给系统指令

某个用户能不能调用下载、删除、发送、写库工具，应由系统权限判断。系统指令只能提醒，不能替代后端鉴权。

失败是正常路径

工具超时、参数错误、目标不可达、权限不足、结果为空都应该有明确返回。Agent 要能解释失败，而不是继续编一个看似合理的答案。

高风险动作要人工确认

写库、发送、删除、外发、批量操作应进入确认流程。Agent 可以准备草稿和变更摘要，但不应绕过人工确认。

可复刻实验片段

{
 "tool": "knowledge.search",
 "arguments": {"query": "机器人任务失败原因", "limit": 5},
 "policy": {
 "required_role": "researcher",
 "write_operation": false,
 "human_confirm": false
 },
 "timeout_ms": 8000,
 "on_error": {"retry": 1, "fallback": "structured_failure"},
 "audit": {"trace_id": "agent-20260629-001", "user_id": "u-17"}
}

工程拆解要覆盖失败分支

工程文章如果只写成功路径，读者会误以为系统稳定性来自某个框架。真实系统恰好相反，稳定性来自对失败分支的提前承认。 工具调用审计表与失败分支清单 应该把超时、权限不足、样本为空、参数错误、人工确认和审计记录都列进去。 这样技术选型才不会变成单纯追热点。

工具 schema 是第一道工程边界

一个更稳的判断是先问三件事：系统到底处理了哪些对象，对象状态由谁确认，出现异常后有没有证据能回到原始材料。围绕 AI Agent 工具调用审计，最需要提前写清的对象包括：tool_name、schema、arguments、caller、permission_check、result、retry_count、trace_id、risk_level 和 human_confirmed。这些对象不一定都要做成复杂系统，但必须在数据结构、接口、表格或日志里有位置。

常见误区是把会调用工具等同于可进入业务。它看起来节省时间，实际上会把风险推迟到更难处理的阶段。到那时，开发人员已经按旧字段写完接口，业务人员已经按旧口径组织材料，运维人员只能面对一堆没有上下文的截图和文件夹。

权限必须在工具执行前完成

这张表不需要写进所有对外方案，但项目内部必须有人拿它逐项核。尤其是涉及高水平数字档案馆、数字档案室或智能应用的内容，不能把 AI、机器人、检索、展示当成替代基础能力的捷径。它们最多是增强层，基础仍然是归档、检测、资源、权限、安全、长期保存和人工复核。

失败、重试和取消都要进入日志

很多项目只保留成功样本，这是后期返工的来源。AI Agent 工具调用审计 至少要准备一组反例：权限不允许、状态不完整、对象不存在、日志缺失、校验失败、人工复核未通过。反例用于确认系统边界，避免错误路径被当作正常能力。

验收或自测时，可以把指标写得更硬一些：高风险工具必须先鉴权再执行；失败可分类；重试有上限；每次调用可按 trace_id 复盘。这类指标比“功能正常”“界面友好”更有价值，因为它能让项目团队知道问题出在数据、流程、接口、模型还是人员复核。

反例还应该进入后续运维。新增一批数据、调整一次规则、替换一个组件、升级一个模型，都要用旧反例复测。只要旧反例开始通过错误路径，说明系统边界已经被改坏。这个动作看似笨，但能避免很多演示顺利、上线失控的问题。

高风险动作不要交给模型单独决定

AI Agent 工具调用审计 最后要回到真实工作分工。开发人员确认 schema，安全人员确认权限，业务人员确认哪些动作必须人工确认。如果一件事只能由写代码的人解释，说明它还没有进入组织能力；如果一件事只能由业务人员口头确认，说明它还没有进入系统证据；如果一件事只能靠验收前补材料，说明平时运行没有沉淀。

领至科技在这类项目里更愿意先把证据链拉直，再讨论智能化程度。因为智能能力越强，越需要解释它依据了什么、排除了什么、谁复核过、出了错如何回滚。没有这些边界，所谓效率提升很容易变成风险加速。

工具调用日志要保存模型看不到的事实

Agent 调用工具时，模型只能看到部分上下文。真正能说明业务风险的，是服务端日志：谁发起请求，权限如何判断，工具参数是什么，执行结果是什么，失败是否重试，人工是否确认。

工具调用日志不能只保存自然语言摘要。至少要有结构化字段：trace_id、tool_name、arguments_hash、permission_result、started_at、finished_at、status、error_code、retry_count、human_confirmed。涉及敏感参数时，可以保存 hash 或脱敏值，但不能完全不留。

工具 schema 要限制动作范围

工具 schema 不只是给模型看的说明书，也是安全边界。比如下载工具只能接收 archive_id 和 purpose，不能让模型传任意文件路径；写库工具只能写候选表，不能直接写正式表；通知工具只能发给授权人员。

{
 "tool": "create_catalog_candidate",
 "allowed_table": "catalog_candidate",
 "requires_human_review": true,
 "arguments": {
 "archive_id": "A001",
 "field_name": "title",
 "candidate_value": "项目验收意见"
 }
}

工具设计越窄，Agent 越容易进入真实业务。宽泛工具看似灵活，实际上很难审计。

人工确认要绑定具体动作

“高风险动作需要人工确认”不能只写在说明里。确认应绑定具体工具、具体参数、具体执行结果。比如删除、发送、写正式库、导出敏感文件，都应在执行前或执行后进入确认队列。

确认记录要能回答：谁确认，确认了什么参数，看到哪些证据，确认后执行了哪个工具，结果是否成功。这样 Agent 即使参与复杂流程，也不会把最终责任交给模型。

工具调用要能降级

Agent 调用外部工具时，一定会遇到服务不可用、参数不合法、权限不足、人工未确认等情况。系统要设计降级路径：能否改为只读，能否转人工，能否保存待处理任务，能否安全失败。

没有降级路径的 Agent 很危险。它会在成功时显得聪明，在失败时把用户带进不可解释状态。工具越强，失败边界越要清楚。

项目里最容易漏掉的一页纸

这页纸的价值，是让不同角色在同一张桌上说同一种话。档案人员看到的是业务口径，开发人员看到的是字段和接口，运维人员看到的是日志和恢复，项目负责人看到的是风险和优先级。只要四类人还在各说各话，系统就很难真正稳定。

实际推进时，可以把这页纸做成三段。第一段写“本次处理的对象是什么”，不要用笼统名词。第二段写“哪些情况不能自动通过”，把失败分支列出来。第三段写“验收或复盘时看什么证据”，明确日志、表格、截图、原文、工单或报告的位置。

如果一篇文章读完以后，项目组能多出这样一页纸，它就不是泛泛观点。它会进入需求评审、接口联调、验收准备和运维交接。领至科技后续做数字档案馆、数字档案室、AI 检索、机器人和开源社区内容，也会尽量把观点压到这种能被复用的材料上。

判断成熟度，看它能不能被别人接手

一个能力是否成熟，不看演示人员讲得多熟，而看换一个人能不能接手。换一个档案人员，是否知道怎么抽查；换一个开发人员，是否知道字段从哪里来；换一个运维人员，是否知道异常去哪查；换一个负责人，是否知道下一笔预算该投在哪里。

接手能力来自文档、数据和日志。只有文档没有数据，系统会变成纸面合规；只有数据没有日志，异常无法复盘；只有日志没有业务解释，项目负责人看不懂风险。三者合在一起，才算进入可运营状态。

工具 schema 要限制动作范围

工具 schema 不只是给模型看的说明书，也是安全边界。比如下载工具只能接收 archive_id 和 purpose，不能让模型传任意文件路径；写库工具只能写候选表，不能直接写正式表；通知工具只能发给授权人员。

{
 "tool": "create_catalog_candidate",
 "allowed_table": "catalog_candidate",
 "requires_human_review": true,
 "arguments": {
 "archive_id": "A001",
 "field_name": "title",
 "candidate_value": "项目验收意见"
 }
}

工具设计越窄，Agent 越容易进入真实业务。宽泛工具看似灵活，实际上很难审计。

重试策略不能无限循环

工具调用失败后，Agent 可以重试，但重试次数、间隔和停止条件要写清楚。权限不足不应重试，参数错误应先修正参数，服务超时可以短暂重试，涉及写库或发送消息的动作要避免重复执行。

每次重试都应保留同一个 trace_id，并记录 retry_count。这样后续复盘时能看出是外部服务抖动、模型选错工具，还是系统把不可恢复错误当成可恢复错误。

还要给幂等性留位置。查询工具重复调用风险较低，写库、发送、删除、审批类工具必须带请求编号，避免网络抖动造成重复执行。Agent 工程里，很多事故来自“成功了但调用方没收到成功返回”。

人工确认页面也应显示请求编号。确认人需要看到工具名称、关键参数、影响范围和上一次调用状态，而不是只看到一句“是否继续”。这样确认才不是形式。

工具权限要跟用户身份绑定

Agent 能调用工具，不代表每个用户都能调用同一组工具。工具权限应和用户、角色、部门、任务目的绑定。普通用户可以查询，审核人员可以生成候选，管理员才可以调整配置。

服务端要做最终判断，不能只依赖模型指令。模型可以建议调用哪个工具，系统必须判断这个用户此刻是否有权执行。