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 GATEWAY Schema 校验 权限与策略 执行与审计
SYSTEM 返回真实结果
可信工具调用 = 合法参数 × 允许权限 × 代码执行 × 可审计结果
Tool Contract
每个工具至少定义六个边界 01 名称与用途 工具解决哪个单一问题,避免万能工具和语义重叠。
02 输入 Schema 字段、类型、枚举、必填项和格式约束由代码验证。
03 权限范围 当前用户、Agent 和运行环境是否允许调用。
04 副作用等级 查询、写入、付款、删除分别采用不同审批策略。
05 超时与重试 只对幂等动作安全重试,写操作必须使用幂等键。
06 返回契约 成功、业务失败、技术失败和部分结果必须可区分。
Bad → Good 01
不能让模型“自导自演”工具结果 核心结论:模型既提出调用又编造执行结果,会绕过权限、业务规则和审计。
BAD 模型直接生成:“订单有效,退款资格已确认。”
没有真实 order_status 没有 refund_eligibility 记录 无法证明调用顺序 GOOD 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/basic main.py src/tool_loop.py tests/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.
Tool Failure
失败不是一律重试,而是分类处理 参数错误 缺 order_id 或格式不合法。 动作:要求模型修正一次
权限拒绝 Agent 没有退款批准权限。 动作:停止并记录
业务失败 订单不满足退款条件。 动作:返回业务原因
技术失败 超时、限流、依赖不可用。 动作:幂等重试或降级
工程落地 不要把异常文本原样交给模型自由解释;先转换成结构化错误类型和可披露信息。
理论 02
RAG 的目标不是“搜到文档”,而是让结论有依据 核心结论:召回只是候选证据生成;只有相关、权威、时效正确且能支持结论的片段才能进入回答。
01 Query Rewrite 补齐业务语义
→ 02 Retrieve & Rerank 找对证据
→ 03 Ground & 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 不知道时,系统必须允许它说不知道 核心结论:强迫模型始终给出答案,会把检索失败伪装成确定结论。
GOOD {
"evidence_status": "partial",
"answer": "需要核查订单状态",
"citations": ["runbook-01"],
"needs_handoff": true
} 不确定是一种正式状态
Advanced Python
Production Tool Loop + RAG Pipeline 核心结论:进阶项目把工具注册表、查询改写、混合信号、重排、引用和人工转接放进一条可测试链路。
Question Order ID Policy Corpus
ORCHESTRATOR Tool Registry Rewrite + Search Rerank + Ground Audit Trace
Tool Results Cited Answer Human Handoff
python3 main.py compare
Advanced Eval
同时验证动作正确和证据正确 案例
关键风险
断言
门禁
未知工具
越过注册表
必须拒绝
PASS
退款承诺
调用顺序缺失
status → eligibility
PASS
弱相关文档
无证据回答
handoff
PASS
有效政策
引用丢失
citations ≥ 1
PASS
安全边界
工具与知识库都要做最小权限 工具治理 按 Agent 和用户配置白名单 写操作二次确认 敏感字段脱敏 幂等键与审计日志
知识治理 按用户权限过滤文档 记录来源和生效时间 隔离不可信内容 阻断提示注入片段
可观测性
一次回答要能还原完整决策过程 检索 Trace 原始 query、改写 query、候选文档、分数、重排结果和过滤原因。
工具 Trace 调用提议、参数校验、权限决策、执行耗时、结构化结果和错误类型。
回答 Trace Prompt 版本、模型版本、引用映射、证据状态、成本和人工转接。
反馈 Trace 用户评价、人工修正和事故样例进入后续评测集。
工程落地 Trace 不是为了保存模型思维过程,而是保存系统可以合法观察和复现的输入、动作与结果。
课堂实战
先证明系统会拒绝,再证明系统会回答 20 min Basic 构造未知工具和非法参数,确认 Gateway 阻断。
35 min Advanced 加入一条冲突政策,调整检索与 handoff 规则。
15 min Eval 把失败路径写成回归案例并运行发布门禁。
验收
上线前,检查八个关键问题 01 模型是否只有提议权?
02 工具参数是否由代码校验?
03 写操作是否有权限与确认?
04 循环是否有次数和成本边界?
05 检索是否检查来源与时效?
06 关键结论是否都有引用?
07 证据不足是否会 handoff?
08 动作与引用是否可回放?
Lesson 02 · Takeaway
让模型决定下一步可能做什么。让系统决定什么真的可以做。 NEXT · Lesson 03 构建真正能完成任务的 Agent Loop