第2部分：让 Agent 长出“手脚” Tool Calling 到底是怎么回事？

上一部分我们已经把 Agent 最基础的骨架搭好了：

为什么需要 Agent
  ↓
Main Loop
  ↓
Agent State
  ↓
LLM Provider

现在开始进入第2部分：让 Agent 长出“手脚”。

如果 Agent 只能和用户聊天，它更像一个会思考的模型应用。

如果我们希望它真正：

• 读文件；
• 查数据库；
• 执行 Python；
• 跑 Shell；
• 搜索项目；
• 调接口；
• 修改代码；

就必须解决一个核心问题，模型到底怎么“调用工具”？

这一节我们会把这个过程彻底拆开。

你会看到，所谓 Tool Calling / Function Calling 并不神秘。

模型生成的可能只是：

{
  "name": "read_file",
  "arguments": {
    "path": "app.py"
  }
}

然后真正发生的是：

Harness 解析 Tool Call
   ↓
寻找 read_file
   ↓
校验 path
   ↓
真正执行 Python 函数
   ↓
拿到文件内容
   ↓
形成 Observation
   ↓
放回 Main Loop

这件事一旦看懂，后面的 Tool Registry、Tool Schema、Error Recovery、Middleware、安全审批都会顺理成章。

这一节阅读时，可以一直守住一句话：Tool Call 是请求，不是执行事实。 模型输出的工具名和参数，都要像外部 API 输入一样先检查；只有 Harness 真正调用函数以后，现实环境才发生变化。

下面四个对象名字相近，但位置不同，先把它们摆在一起，后面就不容易串线：

Tool Result 和 Observation 在简单示例里可能是同一段文本，真实系统里通常不是。Tool Result 可以保留异常类型、耗时、Artifact 引用等工程信息；Observation 则要控制长度、标明来源，并按照消息协议送回模型。

这一块名字最容易混。把它们并排放在一起看，会直观很多：有的负责“告诉模型有哪些工具”，有的负责“表达模型想做什么”，还有的负责“记录执行后到底发生了什么”。

如果这里没有分清，后面写代码时就很容易把调用意图、执行结果和回传内容混成同一个对象，工程上会越来越乱。

开场引入

很多人第一次看到 Tool Calling，会产生一种非常自然的错觉，“大模型已经会调用 Python 函数了。”

比如模型返回：

{
  "name": "read_file",
  "arguments": {
    "path": "app.py"
  }
}

界面上甚至可能直接显示：

Calling tool: read_file

于是看起来就像，模型自己去磁盘上读了文件。

但真实情况不是这样。

大模型本质上仍然只是在生成输出。

以前它生成的是：

“根据你的代码，我建议检查 app.py。”

现在它可以生成更结构化的输出：

{
  "name": "read_file",
  "arguments": {
    "path": "app.py"
  }
}

这两者最大的区别不是“模型获得了操作系统权限”，而是，第二种输出更容易被程序识别和执行。

真正打开文件的是我们的 Python 程序。

真正访问数据库的是数据库客户端。

真正执行 Shell 的是操作系统进程。

真正发 HTTP 请求的是网络库。

所以 Tool Calling 最准确的理解应该是，模型告诉 Harness：“我想调用这个工具，并且参数是这些。”

Harness 再决定：

• 这个工具存在吗？
• 当前 Agent 有权限吗？
• 参数完整吗？
• 参数类型对吗？
• 路径安全吗？
• 是否需要人工审批？
• 真正执行后结果是什么？

你会发现，这个边界非常重要。

如果我们误以为“模型自己会执行函数”，后面就很容易把安全边界搞错。

例如模型说：

delete_file("/etc/passwd")

它并没有真的删。

它只是提出了请求。

只要 Harness 不执行，这个动作就不会发生。

这也是为什么整个 Agent Harness 里，Tool Execution 是一个非常重要的安全闸门。

这一节我们会从最简单的函数调用开始，不依赖任何 Agent 框架，自己手写：

Tool Call
 ↓
解析
 ↓
查找函数
 ↓
参数校验
 ↓
执行
 ↓
Tool Result

然后再把它接回上一节的 Main Loop。

到这里，Agent 才第一次真正具备“和外部世界交互”的能力。

知识地图

这一节是第2部分的第一节。

前面 Agent 已经会“想”和“循环”，现在开始学会“做”。

再把它放回完整 Agent：