KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA
Tool Calling：从“模型想调用”，到“程序安全执行” — keel 龙骨
Tool Calling 的参考信息：Tool Calling：从“模型想调用”，到“程序安全执行”
在 Harness 的一次运行里，模型只能提出“下一步可能需要这个工具”。真正困难的部分发生在之后：程序怎样描述工具、校验参数、判断权限、执行动作、返回结果，并在失败或副作用出现时保持可控。
下面始终使用同一个事件诊断场景：先查询事件，再根据证据回答；掌握只读调用后，再增加创建工单和通知负责人这类有副作用的工具。这样每个新概念都能落回同一条运行轨迹。
一张图先看清工具子系统
flowchart LR
A[Model ToolCall] --> B[内部协议转换]
B --> C[Registry 白名单]
C --> D[输入 schema]
D --> E[业务与权限策略]
E --> F[Executor]
F --> G[ToolResult]
G --> H[Harness 下一轮]
模型只负责提出候选请求。工具调用子系统负责把候选变成可审计的执行结果；Harness 决定整次运行如何继续和停止。
走完这条路径，你应能解释什么
- Python Function、HTTP API 和 Agent Tool 的层级关系；
ToolCall、ToolResult、ToolError为什么要有内部协议；- 输入 schema、业务校验和权限校验各自解决什么问题；
- Registry 为什么必须是白名单，而不是动态函数查找；
- 工具元数据落到数据库之后，静态的一行怎样变成可调用的 function；
- 输出校验为什么和输入校验同样重要；
- 工具错误、超时、结果未知和业务失败怎样区分；
- 幂等键怎样保护写工具不重复产生业务效果；
- 并行调用和流式调用为什么需要额外的关联与收束；
- 哪些工具可以自动执行，哪些工具必须等待审批；
- 工具子系统如何回到 Harness 的状态、事件和停止条件。
学习路线
| 章节 | 先解决的问题 | 主要实验 |
|---|---|---|
| 01. 函数为什么不能直接交给模型？ | 建立 Function、ToolCall、ToolResult 的边界 | 手动构造一次调用 |
| 02. 先让 Ollama 产生一次工具请求 | 观察供应商消息和内部协议的转换 | 真实只读查询 |
| 03. 一个工具契约究竟包含什么？ | 连接 schema、输出、effect、可靠性和授权 | 契约草图 |
| 04. 数据库里的一行静态记录，怎样变成可调用的 function？ | 理解 recipe、限定名 import 与动态生成转发器 | 静态行还原实验 |
| 05. Registry 和 Executor 怎样形成白名单？ | 把坏请求挡在函数之外 | 确定性拒绝实验 |
| 06. 工具结果为什么要回到下一轮？ | 理解 role、call_id 和多轮循环 | 真实工具循环 |
| 07. 工具失败时为什么不能急着重试？ | 处理 timeout、outcome unknown 和幂等 | 重复创建实验 |
| 08. 多个工具和流式调用怎样不乱？ | 处理关联、部分成功和增量累积 | 并行/流式实验 |
| 09. 副作用工具怎样进入审批边界？ | 让策略保护现实动作 | approval_required 实验 |
| 10. 把工具子系统放回 Harness | 完成架构映射和扩展练习 | 增加服务负责人工具 |
先做确定性实验，再接入模型
python -m pip install -r courses/foundation/tool-calling/course/project/requirements.txt
python courses/foundation/tool-calling/course/project/examples/02_validated_dispatch.py
python courses/foundation/tool-calling/course/project/examples/04_idempotency.py
python courses/foundation/tool-calling/course/project/examples/08_offline_loop.py
python courses/foundation/tool-calling/course/project/examples/09_offline_advanced.py
python -m unittest discover -s courses/foundation/tool-calling/course/project/tests -v
08 与 09 用脚本化的假模型代替 Ollama，覆盖循环、并行、审批和流式分片——没有本地模型也能看全五种停止状态。
先运行下面的确定性实验，再运行真实模型：
ollama serve
ollama pull qwen3:8b
$env:OLLAMA_MODEL = "qwen3:8b"
python courses/foundation/tool-calling/course/project/examples/01_single_tool.py
python courses/foundation/tool-calling/course/project/examples/03_tool_loop.py
先掌握单次循环，再运行并行和流式示例。真实模型用来观察选择质量；白名单、参数校验、幂等和审批必须用固定测试验证。
官方协议依据：Ollama Tool Calling。
当一个工具调用被拆给多个专业执行者时，任务所有权、并行汇聚和 Agent 间权限由多 Agent 协作课程继续展开。