工具调用——LLM 跟世界互动的协议

Agent 跟 Chatbot 的根本区别

LLM 自己什么都不能做。

我们在 0.1 章看过——它只会续写文字。不能开文件、不能跑命令、不能上网、不能调 API。它的能力被锁在"文本"这一个维度。

但 Cursor 能改你的代码、ChatGPT Code Interpreter 能跑 Python、Devin 能完成项目级任务——这些产品里的 LLM 怎么"做事"？

答案就一个机制——tool calling（工具调用）。这是 LLM 跟世界互动的协议。所有 Agent 产品的能力——本质都是这个协议的应用。

一、Tool Calling 的核心机制——LLM 用"特殊文字"间接操作

LLM 还是只能输出文字。这件事永远不会变——这是 LLM 的本质。

tool calling 的精妙在于——让 LLM 输出一段"有约定结构的文字"——产品后端解析这段文字、把它翻译成实际操作。

具体怎么工作？我们看个例子。

产品后端在调 LLM 时，多塞一个 tools 字段告诉它"有哪些工具可用"：

"tools": [
  {
    "name": "read_file",
    "description": "Read a file from the filesystem",
    "parameters": {
      "type": "object",
      "properties": {
        "path": {"type": "string"}
      },
      "required": ["path"]
    }
  }
]

每个工具有三个核心字段：

• name——工具叫什么
• description——工具是干嘛的（这是给 LLM 看的"使用说明"）
• parameters——工具的参数 schema（JSON Schema 格式）

LLM 看到这个 tools 清单——它在生成响应时多了一种输出选项——可以输出"我想调用 read_file 工具"。

这个"想调用"的输出长这样：

{
  "type": "tool_use",
  "id": "call_001",
  "name": "read_file",
  "arguments": {"path": "/Users/lee/main.py"}
}

仍然是文字（JSON 字符串）——但有约定结构。产品后端能解析这段文字——识别出 LLM 想调用 read_file 工具、路径是 /Users/lee/main.py。

然后产品后端真的去读这个文件——拿到内容——把内容塞回 LLM 的下一次请求里：

{
  "type": "tool_result",
  "tool_use_id": "call_001",
  "content": "[main.py 的实际内容...]"
}

LLM 看到这段——继续思考。它可能再调一个工具、可能给出最终回复。

这是 tool calling 的完整循环——

LLM 看到 tools → 想要工具 → 输出 tool_use
        ↓
产品后端 → 真的执行 → 拿到结果
        ↓
塞回 LLM → LLM 看到结果 → 继续思考
        ↓
... 循环 ...
        ↓
LLM 不再想要工具 → 输出最终文字

LLM 通过这个循环间接操作世界——它生成的文字被解析成动作、动作的结果被塞回让它继续生成——直到任务完成。

二、Tool calling 协议是 2023 年才标准化的

这个机制看似简单——但它在历史上是个真实的里程碑。

2022 年之前——没有 tool calling 协议。开发者想让 LLM "做事"——只能用prompt hack——在 prompt 里教 LLM "如果你想做 X，请按以下格式输出"：

If you need to query the database, output:
<query>SELECT * FROM users</query>

然后开发者写正则从 LLM 输出里解析。

这种 prompt hack 几个根本问题：

问题 1：LLM 经常忘了用约定格式。你教它"用 <query> 标签"——它可能就忘了——输出"我要查询用户表"——你的正则识别不出来。

问题 2：LLM 可能"幻觉"出不存在的标签。它有时候输出 <select> 或 <sql> 而不是 <query>——格式不稳定。

问题 3：解析复杂。LLM 输出文字 + 标签混在一起——你要从中提取结构化数据——正则越写越复杂。

问题 4：没有 schema 验证。LLM 输出的"参数"可能格式错——你执行时才发现——错了再让 LLM 重试。

整个体验是fragile——能 work 但很脆。Auto-GPT、BabyAGI 这种早期 Agent 在这种 prompt hack 上跑——经常出错。

2023 年 6 月，OpenAI 推出 Function Calling——第一个原生 tool calling 协议。

OpenAI 的做法是——在训练时就教模型识别"用户的 prompt 里有 functions 描述时——应该输出结构化 function call"。

不是让模型"凭记忆"输出特定格式——是让模型底层理解 function calling 是个特殊任务——按训练时学到的方式精确输出。

这是个里程碑——AI Agent 工程从"prompt 黑魔法"走向"协议工程"。

之后 Anthropic（2023 年下半年）、Google（2024 年初）都跟进了类似机制。各家细节不同——但核心都一样——LLM 训练时学过结构化输出——产品后端可靠地解析。

现在所有主流 LLM 都支持 tool calling——成为 Agent 时代的基础设施。

三、Tool 是 Agent 能力的边界

理解 tool calling 后——一个深层判断浮现：Agent 的能力上限——就是它的 tool 集。

ChatGPT 网页加了 Code Interpreter 之后——能跑 Python——能做数据分析——但它仍然不能改你电脑上的文件——因为它的 tool 集里没有 "edit_file"。

Cursor 能改你的代码——因为它有 edit_file 工具。但它仍然不能自动 commit + push——因为它的 tool 集里通常没有 git operations。

opencode 能跑 bash 命令——因为它有 bash 工具。但 bash 工具的实现里如果设了 2 分钟 timeout——LLM 就不能跑 1 小时的 build——这是 tool 实现的限制。

设计 Agent 时——tool 集决定能力范围。

这件事有两个产品视角：

视角 1：Tool 集太小——能力受限。

如果你的 Agent 只有 read + write + bash——它能做 80% 的代码任务。

但它做不了：

• 发邮件（没有 email tool）
• 查数据库（没有 db tool）
• 部署应用（没有 deploy tool）
• 调用第三方 API（没有 http_request tool）

每加一个 tool——能力加一档。

视角 2：Tool 集太大——LLM 选择困难。

如果你的 Agent 有 50 个 tools——LLM 决策时面对 50 个选项——经常选错。

研究表明——LLM 对 10-20 个工具的选择准确率最高——超过 30 个开始衰减。

最佳实践是——10-20 个核心 tool——覆盖产品主要场景——简洁就是力量。

opencode 用了 15 个 tool——是个合理范围。我们在第 3 篇详细看每个 tool 的设计。

四、Tool description 是给 LLM 看的"说明书"

每个 tool 的 description 是个关键字段——它告诉 LLM "什么时候用这个工具"。

写好 tool description 是 prompt engineering 的核心技能之一。

我们看 opencode 的 read tool description（节选）：

Reads a file from the filesystem. You can access any file directly by using this tool.

Usage:
- The file_path parameter must be an absolute path, not a relative path
- By default, it reads up to 2000 lines starting from the beginning of the file
- Any lines longer than 2000 characters will be truncated

Notes:
- ALWAYS prefer reading a file in its entirety unless you are dealing with very long files
- Call this tool in parallel when you know there are multiple files you want to read
- Avoid reading tiny repeated slices (30 line chunks) — when in doubt, read more not less

注意几个细节——

细节 1：开头一句话总结。"Reads a file"——LLM 立刻知道这是干嘛的。

细节 2：Usage 列约束。"必须用 absolute path"——LLM 知道要怎么填参数。

细节 3：Notes 列偏好。"宁多读不要少读"——LLM 知道该怎么选择 limit 参数。

这些 description 不是 API 文档——是给 LLM 的工作指引。写得好——LLM 用得正确——产品质量高。写得差——LLM 经常用错——产品 bug 多。

我们在 3.3 章会详细拆 opencode 15 个 tool 的 description——分析为什么这么写、能学到什么。

五、Tool calling 改变了 AI 产品的设计可能性

让我们退一步看历史。

2022 年之前——AI 产品基本都是 Chatbot 形态。LLM 跟用户聊——给建议、给代码、给方案——但不做事。

2023 年开始——Tool calling 让 Agent 形态可能。AI 产品不只是给建议——是真的去做。

这不是单纯能力升级——是产品形态的质的飞跃。

Chatbot 形态产品的价值定位——"帮你思考"。给你信息、灵感、答案——让你决定怎么用。

Agent 形态产品的价值定位——"替你做事"。理解你的意图、自己拆解、自己执行、给你结果。

两种形态对用户的承诺完全不同——一个是"我陪你聊"——一个是"我替你干"。

价值梯度也不同——

• Chatbot 替代搜索引擎——值 $10-20/月
• Agent 替代实习生——值 $100-500/月

这就是 Cursor、Devin、opencode 这些 Agent 产品的价值想象——它们不是"更好的 ChatGPT"——它们是新的产品品类——价值锚不一样。

设计 AI 产品时要想清楚——你做的是 Chatbot 还是 Agent——两者的设计思路、定价、用户期望都不一样。

六、Tool calling 也带来新的风险

能力 = 风险。Agent 能做事——也能做坏事。

ChatGPT 给你"删除 .DS_Store"的脚本——错了也只是你贴到终端发现不对——再贴个新的。代价低。

Cursor 自动改你的代码——如果错了——可能改坏了你的项目——撤销要 git revert——代价中等。

opencode 自动跑 npm run deploy——如果错了——可能部署了 bug 到生产——代价高。

完全自动化的 Agent 跑大任务——如果错了——可能花掉用户几百美元的 API 费用——还破坏数据。代价灾难。

这就是 Agent 设计的核心难题——让 AI 做事的同时不让它做坏事。

opencode 的应对是Permission 系统——危险操作（rm、deploy、git push）默认要用户审批。第 7 篇专门讲 Permission——这是 Agent 安全的核心机制。

设计你的 Agent 产品时——把 tool 的"危险度"分级——危险的强制审批——低风险的自动执行——这是基本原则。

七、看 Agent 时该看 tool 集

最后给你一个判断 Agent 产品的实用方法——看它的 tool 集。

每个 Agent 产品都有一个核心 tool 集。这个集合直接告诉你它能做什么。

opencode 的 tool 集（15 个）：

• 文件操作：read、write、edit、multiedit、glob、grep、list
• 系统操作：bash
• 网络操作：webfetch、websearch
• Agent 协作：task、todowrite
• 知识增强：skill
• 用户交互：question
• 代码分析：lsp

从这个清单看——opencode 是个编程任务 Agent——核心能力围绕代码项目。

Cursor 的 tool 集（粗略）：

• 文件操作：edit、create_file
• 搜索：semantic_search
• 终端：run_terminal
• 浏览器：fetch_pages

从这个清单看——Cursor 是个编辑器集成 Agent——核心能力围绕 IDE 体验。

Devin 的 tool 集（推测）：

• 浏览器自动化（重）
• 终端
• 文件编辑
• 调用外部 API

从这个清单看——Devin 是个通用任务 Agent——能做比编程更广的事。

这种"从 tool 集反推产品定位"的判断——是看任何 AI 产品的基础。

把这本书读完——你看任何 AI 产品都能立刻判断它的能力、定位、风险。

最后一章 0.6——我们介绍 opencode 这个贯穿全书的案例——它的形态、架构、为什么选它。