AI AGENT SYSTEMS · 02

工具边界与
生产级 RAG

让模型负责判断,让代码负责执行,让证据负责回答

理论 Tool Loop 与 Grounding 实战 Python Basic + Advanced
学习目标

完成本课后,你应该能设计两条可信链

核心结论:一套生产级问答系统既要证明数据来源可靠,也要证明外部动作真实、合规地发生。

Tool Loop解释模型提议与代码执行的边界,设计工具 Schema、权限、失败处理和停止条件。
RAG Pipeline设计 Query Rewrite、混合召回、Rerank、引用和证据不足 handoff。
工程验收用测试同时验证工具顺序、未知工具阻断、引用完整性和拒答行为。
生产治理为工具、知识和回答建立最小权限、Trace、成本与人工接管。
失败现场

模型说“我查过了”,但系统没有任何调用记录

核心结论:模型描述自己执行过工具,不代表工具真的被调用;没有审计记录的动作在生产上等于没有发生。

用户
请求
“订单导出失败两次,可以直接退款吗?”需要订单状态、退款资格和政策依据
模型
回答
“可以,我已经核查过,退款已批准。”没有调用订单系统,也没有权限批准退款
复盘
证据
Tool trace 为空,引用文档不存在一次回答同时发生工具幻觉和知识幻觉
方法论主线

生产回答必须通过两条可信链

核心结论:Tool Loop 证明“动作真的执行”,RAG Pipeline 证明“答案真的有依据”。

意图层Model Proposal模型提出工具名、参数和调用理由
执行层Tool Gateway代码校验 schema、权限、副作用和超时
知识层Retrieval改写、召回、融合和重排候选证据
回答层Grounding答案中的关键结论必须映射到引用
治理层Eval & Trace检查工具顺序、引用质量和拒答行为
工程落地模型没有工具执行权,也没有把弱相关文档自动升级为事实的权力。
理论 01

Tool Call 是执行建议,不是执行结果

核心结论:LLM 输出的 tool name 和 arguments 只是非可信输入,必须像外部 API 请求一样验证。

MODEL提出调用意图
TOOL GATEWAYSchema 校验权限与策略执行与审计
SYSTEM返回真实结果
可信工具调用 = 合法参数 × 允许权限 × 代码执行 × 可审计结果
Tool Contract

每个工具至少定义六个边界

01 名称与用途工具解决哪个单一问题,避免万能工具和语义重叠。
02 输入 Schema字段、类型、枚举、必填项和格式约束由代码验证。
03 权限范围当前用户、Agent 和运行环境是否允许调用。
04 副作用等级查询、写入、付款、删除分别采用不同审批策略。
05 超时与重试只对幂等动作安全重试,写操作必须使用幂等键。
06 返回契约成功、业务失败、技术失败和部分结果必须可区分。
Bad → Good 01

不能让模型“自导自演”工具结果

核心结论:模型既提出调用又编造执行结果,会绕过权限、业务规则和审计。

模型直接生成:“订单有效,退款资格已确认。”

  • 没有真实 order_status
  • 没有 refund_eligibility 记录
  • 无法证明调用顺序
proposal → validate
→ execute in code
→ append tool result
→ model summarizes
工具结果只能由代码产生
工程落地把每次提议、拒绝、执行、结果和耗时写入 trace,模型只能读取结果组织回答。
执行时序

标准 Tool Loop 是一个受控往返

核心结论:每一轮都要重新检查停止条件和调用预算,不能让模型无限调用。

1用户请求业务目标
2模型提议tool + args
3代码验证权限/参数
4执行工具真实结果
5总结/停止有界循环
工程落地设置 max_iterations、工具白名单、单步超时和总成本预算;达到边界就停止并转人工。
Basic Python

Safe Tool Loop:退款资格核查

核心结论:基础项目用最少代码展示“模型建议、注册表验证、代码执行、结果回填”。

projects/lesson-02/basicmain.pysrc/tool_loop.pytests/test_tool_loop.py
01 compare比较假装查询和真实调用
02 registry阻断未知工具与非法参数
03 unittest验证顺序、结果和拒绝行为
python3 main.py compare
Basic 运行结果

“查过了”必须能展开成证据链

lesson-02/basic · compare
BAD  > Refund is approved. I checked the order.

GOOD > proposed_calls: [order_status, refund_eligibility]
audit: [validated, executed_by:code]
can_promise_refund: true
answer: Submit the refund request.
2真实工具调用
0未知工具放行
3/3基础测试通过
Tool Failure

失败不是一律重试,而是分类处理

参数错误缺 order_id 或格式不合法。动作:要求模型修正一次
权限拒绝Agent 没有退款批准权限。动作:停止并记录
业务失败订单不满足退款条件。动作:返回业务原因
技术失败超时、限流、依赖不可用。动作:幂等重试或降级
工程落地不要把异常文本原样交给模型自由解释;先转换成结构化错误类型和可披露信息。
理论 02

RAG 的目标不是“搜到文档”,而是让结论有依据

核心结论:召回只是候选证据生成;只有相关、权威、时效正确且能支持结论的片段才能进入回答。

01Query Rewrite补齐业务语义
02Retrieve & Rerank找对证据
03Ground & Cite约束答案
Bad → Good 02

Top-1 相似,不代表足以回答

核心结论:语义相似度衡量“像不像”,不衡量文档是否权威、是否过期、是否完整支持问题。

QUESTION导出失败两次能否承诺退款?
WEAK HIT营销文档提到“退款体验”
错误直接批准相似词驱动答案
正确继续检索订单状态 + 正式政策
Retrieval Pipeline

生产检索是一条漏斗,不是一次向量查询

理解Rewrite解析实体、时间、事项和隐藏条件
召回Hybrid Search关键词保证精确实体,向量补充语义表达
融合RRF / Merge合并多路候选并去重
排序Rerank按问题与片段的真实支持度排序
过滤Authority Gate检查来源、时效、权限和最低证据阈值
Grounding Contract

引用不是装饰,而是答案的约束结构

answer只陈述证据支持的结论
citations定位文档与片段
evidence_statussufficient / partial / missing
conflicts暴露不同来源冲突
effective_date检查政策时效
needs_handoff证据不足进入人工
工程落地逐句检查关键主张是否至少有一个直接引用;没有引用的事实性句子必须删除或改为不确定表达。
Bad → Good 03

RAG 不知道时,系统必须允许它说不知道

核心结论:强迫模型始终给出答案,会把检索失败伪装成确定结论。

“根据公司政策,退款一定可以批准。”

  • 引用为空
  • 未检查订单状态
  • 把缺证据当肯定
{
 "evidence_status": "partial",
 "answer": "需要核查订单状态",
 "citations": ["runbook-01"],
 "needs_handoff": true
}
不确定是一种正式状态
Advanced Python

Production Tool Loop + RAG Pipeline

核心结论:进阶项目把工具注册表、查询改写、混合信号、重排、引用和人工转接放进一条可测试链路。

QuestionOrder IDPolicy Corpus
ORCHESTRATORTool RegistryRewrite + SearchRerank + GroundAudit Trace
Tool ResultsCited AnswerHuman Handoff
python3 main.py compare
Advanced Eval

同时验证动作正确和证据正确

案例
关键风险
断言
门禁
未知工具
越过注册表
必须拒绝
PASS
退款承诺
调用顺序缺失
status → eligibility
PASS
弱相关文档
无证据回答
handoff
PASS
有效政策
引用丢失
citations ≥ 1
PASS
安全边界

工具与知识库都要做最小权限

工具治理按 Agent 和用户配置白名单写操作二次确认敏感字段脱敏幂等键与审计日志
知识治理按用户权限过滤文档记录来源和生效时间隔离不可信内容阻断提示注入片段
可观测性

一次回答要能还原完整决策过程

检索 Trace原始 query、改写 query、候选文档、分数、重排结果和过滤原因。
工具 Trace调用提议、参数校验、权限决策、执行耗时、结构化结果和错误类型。
回答 TracePrompt 版本、模型版本、引用映射、证据状态、成本和人工转接。
反馈 Trace用户评价、人工修正和事故样例进入后续评测集。
工程落地Trace 不是为了保存模型思维过程,而是保存系统可以合法观察和复现的输入、动作与结果。
课堂实战

先证明系统会拒绝,再证明系统会回答

20 minBasic

构造未知工具和非法参数,确认 Gateway 阻断。

35 minAdvanced

加入一条冲突政策,调整检索与 handoff 规则。

15 minEval

把失败路径写成回归案例并运行发布门禁。

验收

上线前,检查八个关键问题

01 模型是否只有提议权?
02 工具参数是否由代码校验?
03 写操作是否有权限与确认?
04 循环是否有次数和成本边界?
05 检索是否检查来源与时效?
06 关键结论是否都有引用?
07 证据不足是否会 handoff?
08 动作与引用是否可回放?
Lesson 02 · Takeaway

让模型决定下一步可能做什么。
让系统决定什么真的可以做。

NEXT · Lesson 03 构建真正能完成任务的 Agent Loop