📘 第 5 课：What is tool use?（什么是工具调用）

所属课程：the AI Platform 101（课程 003） 官方课时定位：Section 2「Teaching your Agent」— Lesson 5 / 共 12 课时 ID：486255 ｜ 官方地址：https://anthropic.skilljar.com/claude-platform-101/486255 形式：Video（视频课 + 文稿） 针对认证：CCAR-P（架构师 Professional） 整理日期：2026-10-14 ⚠️ 语料来源：官方 Skilljar 课程正文（用户提供，需登录）。CC BY-NC-SA 4.0，仅供个人学习。 ⭐⭐ 本课权重提示：领域 3（19%，全考纲最大）的主战场。官方在这里给出了三条可直接命题的论断：① AI 不执行工具，你的代码执行；② description 含糊是智能体失灵的头号原因；③ stop_reason: "tool_use" 是信号。此外课末的 「执行 ↔ 委托」光谱是本课的结构性贡献，直接对应领域 1 的架构模式选择。

🎯 本课学习目标

⚠️ 本课官方未提供 What you'll learn 区块。以下按文稿结构反推：

1. 能说清为什么需要工具（AI 自己碰不到你的系统）。
2. ⭐⭐ 能背出「AI 不执行工具，你的代码执行」及其三步流程。
3. 能写出工具定义的三要素 JSON Schema，并说清 description 的作用。
4. 能实现多工具分发（switch on tool name）并知道加一个工具要动哪两处。
5. ⭐ 能说出 Tool Runner 解决了什么（免写 schema + 免手写循环），以及它在哪三种语言的 SDK 里。
6. ⭐⭐ 能画出本课末的「执行 ↔ 委托」光谱。

📖 一、视频导读：为什么需要工具

官方原句： Your existing workflows rely on a lot of different technologies — project management software, databases, files. the AI can't just check these things itself. Instead, it relies on tools, which give the AI access to external data and actions.

精译：你现有的工作流依赖很多不同的技术 —— 项目管理软件、数据库、文件。AI 没法自己去查这些东西。 它转而依赖工具，而工具让 AI 获得对外部数据与动作的访问能力。

⭐ the AI can't just check these things itself —— 这是工具的存在理由。 呼应第 4 课：the AI has no way to know the weather on its own。两句是同一条限制：模型的知识止于训练数据，实时/私有数据必须靠工具。 对应考纲：领域 5「识别 LLM 系统的风险、局限与失效模式（知识截止）」。

⭐ 「外部数据」与「动作」的二分

⭐ 这个二分是安全考点的根：「读」型工具与「写」型工具的风险等级完全不同。 呼应课程 002 的 least privilege 与 capability bloat —— 只给角色需要的那一类，写权限尤其要单独审。

🔧 二、⭐ 工具是什么（What a tool is）

官方原句： Simply put, a tool is a function you define and expose to the AI.* You describe what it does and what inputs it takes, and the AI decides when to call it.***

精译：简单说，工具就是一个你定义并暴露给 AI 的函数。 你描述它做什么、接受什么输入，而 AI 决定何时调用它。

⭐⭐ 本课第一论断（官方要求「内化」）

官方原句： Here's the key thing to internalize: the AI doesn't execute the tool — your code does. The flow looks like this: 1. the AI requests a tool call. 2. Your code executes the function. 3. The result goes back to the AI, and it keeps going.**

精译： 这里是需要你内化的关键一点：AI 并不执行工具 —— 是你的代码在执行。流程是这样的： 1. AI 请求一次工具调用。 2. 你的代码执行那个函数。 3. 结果回到 AI，它继续往下走。

⭐⭐ 注意官方用了 internalize（内化）这个词 —— 这是本课唯一一个被官方点名要求「内化」的点，几乎必然命题。

❌ 常见误解	✅ 官方口径
AI 调用工具、AI 执行工具	AI 只请求；你的代码执行
工具是平台提供的能力	工具是你写的函数（平台另有一类 built-in tools，见第 7 课）

⭐⭐ 这直接呼应第 4 课那句 *You own the loop and the tools. the AI owns the reasoning.* —— 本课把它细化到了执行层： * AI 拥有：何时调、调哪个、传什么参数（推理） * 你拥有：tools 数组、schema、以及真正跑起来的那段代码（run_tool / runTool）

安全含义（领域 3 + 领域 5）：攻击面与权限边界落在你写的执行体里，不在模型里。"AI 干的"不是免责理由 —— 这与课程 002 的 "AI wrote it" explains nothing and excuses nothing 是同一立场。

📐 三、⭐⭐ 工具怎么定义（How tools are defined）

官方原句： Tools are JSON schemas with three parts: a name, a description, and an input schema.* You pass them to the AI in the request body as a tools array*.

⭐⭐ 本课第二论断：description 是「头号原因」

官方原句： The description is what the AI reads to decide whether to call the tool.* If you write a vague description, you get bad tool use. This is the number one reason agents misfire or don't grab the tools that are available to them. Be specific.***

精译： description 就是 AI 读来决定是否调用这个工具的东西。 如果你写得含糊，你就会得到糟糕的工具使用。这是智能体失灵、或者抓不住手边可用工具的头号原因。 写具体。

⭐⭐ 这是全课最可能出现「根因题」的地方： 题干：智能体有工具却不调用 / 调错工具 / 工具明显该用却没用。 正解：description 写得含糊，不够具体 —— 改写 description，明确「何时用」并覆盖触发关键词。 陷阱选项：换更大的模型、增加工具数量、提高 max_tokens、加 system 提示词 —— 都不对根因。

⭐⭐ 这与课程 002《AI Fluency》的 Skill 触发考点完全同构： 002 说 Skill 装了不触发 → 改 description 字段； 本课说工具有了不调用 / 乱调用 → 改 description。 两门课在这一点上是同一个机制：description = 语义路由的判据。这是本次备考中跨课程最强的一处呼应，务必合并记忆。

官方工具定义示例（保持原样）

{
  "name": "lookup_building_code",
  "description": "Look up a specific building code section by its identifier. Returns the full text of that code section.",
  "input_schema": {
    "type": "object",
    "properties": {
      "section": {
        "type": "string",
        "description": "The building code section to look up"
      }
    },
    "required": ["section"]
  }
}

⭐ 注意这段 description 的写法（官方给的正面范例）： * "Look up a specific building code section by its identifier" —— 说清做什么与按什么查； * "Returns the full text of that code section." —— ⭐ 连返回值都说清了。 这就是 Be specific. 的具体形态：动作 + 依据 + 返回。

调用时的信号与回传

On the first turn, the AI comes back with stop_reason: "tool_use" — that's our signal. Our loop calls lookup_building_code with the parameter the AI requested, then feeds the result back as a tool result — a user message containing a tool_result block tied to the tool call's id**

精译：第一轮，AI 回来的是 stop_reason: "tool_use" —— 这就是我们的信号。我们的循环用 AI 请求的参数调用 lookup_building_code，然后把结果作为 tool result 喂回去 —— 一条包含 tool_result block 的 user 消息，该 block 绑到那次工具调用的 id 上。

⭐⭐ stop_reason: "tool_use" — that's our signal（这就是我们的信号）—— 官方在 Recap 里再次重复了这个措辞，是必背的程序性知识。 ⭐ 再次确认第 4 课的两个实现细节：tool_result 放在 user 消息里，且必须绑 tool_use_id。本课是第二次出现，复现即重点。

🎯 四、多工具：让 AI 自己挑（Multiple tools）

官方原句：One tool is useful, but the interesting part is giving the AI multiple tools and watching it pick which one to use, in what order.

精译：一个工具是有用的，但有意思的部分是给 AI 多个工具，然后看它挑用哪一个、按什么顺序用。

场景与两个工具

you're packing for a three-day trip to Denver, and you want both today's weather and the forecast for the next few days. So we declare two tools instead of one:

⭐⭐ 这两个 description 是「如何区分相似工具」的教科书范例： 两个工具的入参完全相同（都是 city），唯一区分点就是 description 里的 today 与 next few days。 考点：题干问「两个工具参数相同，AI 靠什么区分」→ description。 反向陷阱：若两个工具 description 重叠（比如都写 "Get weather for a city"），AI 就会选错或漏选 —— 这正是 vague description 导致 misfire 的机制。

官方代码（TypeScript，保持原样）

function runTool(name, input) {
  switch (name) {
    case "get_weather":
      return getWeather(input.city);
    case "get_forecast":
      return getForecast(input.city);
  }
}

while (true) {
  const response = await client.messages.create({
    model: "current-model-fast",
    max_tokens: 1024,
    messages,
    tools,
  });

  if (response.stop_reason !== "tool_use") {
    // the AI is done — this is the final answer
    break;
  }

  messages.push({ role: "assistant", content: response.content });

  const toolResults = response.content
    .filter((block) => block.type === "tool_use")
    .map((block) => ({
      type: "tool_result",
      tool_use_id: block.id,
      content: runTool(block.name, block.input),
    }));

  messages.push({ role: "user", content: toolResults });
}

⚠️ 抓取件说明：model: "current-model-fast" 为环境替换残留（按第 3 课映射 = Sonnet 档）。不要背这个字符串。

⭐ 加一个工具要动两处（官方原话）

Want a third tool? Add it to the array, add a case to the switch, and you're done.

精译：想要第三个工具？把它加进数组，在 switch 里加一个 case，就完事了。

⭐ 这两处正好对应「AI 拥有推理 / 你拥有执行」的分工 —— 缺任何一处，工具都不完整：只加数组 → AI 会请求但代码不认识；只加 case → 代码能跑但 AI 不知道有这工具。

⚠️ 两处写法的差异（分析，非官方论断）

💡 我的分析（非官方口径，记录备查）：第 5 课写法更省事，但会把 max_tokens 截断等非完成状态也当成「结束」。第 4 课写法更严谨。 备考建议：题目若问「循环应在什么条件下终止」，官方 Recap 的口径是 stop when the stop reason is end_turn —— 按第 4 课答。

运行结果与官方解读

Run this, and you'll see the AI call get_weather and then get_forecast — sometimes in the same turn, sometimes one after the other. Then it answers: pack layers, expect snow flurries today, warming through the week. Now notice how the AI chose. It read the descriptions, mapped your prompt to "today's weather" and "the next few days," and picked the right tool for each. That's why your tool descriptions really matter.

精译：跑起来你会看到 AI 调用 get_weather 然后 get_forecast —— 有时在同一轮里，有时一前一后。然后它回答：带多层衣物，今天有阵雪，本周转暖。 现在注意 AI 是怎么选的。它读了 description，把你的提问映射到了「今天的天气」和「未来几天」，并为每个选对了工具。这就是为什么你的工具 description 真的很重要。

⭐ sometimes in the same turn, sometimes one after the other —— 官方承认调用顺序与并行度由 AI 决定，不是固定编排。 这正是 agentic 与 workflow 的分界（领域 1）：workflow 是你写死顺序；agentic 是 AI 决定顺序。呼应第 4 课 without a human in the middle。 ⭐ It read the descriptions —— 官方第三次强调 description 的机制作用。

⚙️ 五、⭐⭐ Tool Runner：省掉样板代码（skip the boilerplate）

官方先数了两个「红旗」

You've probably already spotted two red flags with what we just wrote: * That's a lot of code for two simple lookups. * In a real codebase, you don't want to handwrite JSON schemas for every function you have. It's like writing your code twice.

精译： * 为了两个简单的查询，写了这么多代码。 * 在真实代码库里，你不会想为每个函数手写 JSON schema。这就像把你的代码写两遍。

⭐⭐ It's like writing your code twice.（这就像把你的代码写两遍。） —— 本课最形象的一句话，也是 Tool Runner 的存在理由。 对应考纲领域 7「开发者生产力与运维赋能（7%）」 —— 这是性价比最高的 4 分里最典型的一道题。

Tool Runner 的三个要点

官方原句： It ships in the the AI SDK for TypeScript, Python, and Ruby.* The runner takes your actual functions, reads the types and docs to build the schema for you, and handles the entire tool use / tool result loop internally*.

⭐ reads the types and docs —— 意味着你的类型注解与文档字符串（docstring / JSDoc）会被读去生成 schema。 推论（我的分析）：写工具函数时把 docstring 写好，就等于在写 description。这与 Be specific. 是同一条要求，只是落点从 JSON 移到了函数注释。

官方代码（保持原样）

// The same two lookups we ran by hand — just plain TypeScript functions
function getWeather(city: string) {
  // ...existing lookup
}

function getForecast(city: string) {
  // ...existing lookup
}

const runner = client.beta.messages.toolRunner({
  model: "current-model-fast",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content:
        "I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
    },
  ],
  tools: [getWeather, getForecast],
});

// Returns the final assistant message after all the tool ping-pong has settled
const finalMessage = await runner.untilDone();

⚠️ 注意命名空间：官方写法是 client.beta.messages.toolRunner —— 位于 beta 下。 ⭐ tools: [getWeather, getForecast] —— 直接传函数本身，不再传 JSON schema 对象。这是 Tool Runner 的标志性写法。

⭐ 官方列的四条「省掉了什么」

⭐ once everything has settled（等一切安定） —— 官方用 settled 形容多次工具往返结束的状态。呼应第 12 课的 event stream：循环内部发生的事你看不见，只拿最终结果。 ⚠️ 代价提示（我的分析）：把循环交给 runner = 放弃对每一轮的可见性与干预点。这正是课末那条「执行 ↔ 委托」光谱要讨论的权衡。

⭐ 呼应课程页 About 的承诺

About 原句：...then collapse that hand-written loop with the SDK's Tool Runner once you understand what it does for you.

⭐⭐ once you understand what it does for you（在你理解它替你做了什么之后） —— 官方明确反对一上来就用 Tool Runner：先手写一遍循环（第 4 课），再用 runner 折叠（第 5 课）。 这是官方的教学顺序，也是一个考点：题干问「团队该直接采用 Tool Runner 还是先手写循环」→ 官方立场是先理解，再折叠（因为出问题时你得知道循环里发生了什么）。

🏭 六、真实工具是包在你已有代码外面的一层

官方原句： In real life, your tools wouldn't be hardcoded weather data. They'd wrap actual functions you already have in your application. Take a compliance review agent: its tools are thin wrappers around lookup_building_code and search_building_code functions that already exist in the codebase. With the tool runner, you pass those functions in directly, and the agent cites specific code sections in every finding it writes — no schema writing required.

精译：现实中，你的工具不会是硬编码的天气数据。它们会包住你应用里已经存在的真实函数。 以一个合规审查智能体为例：它的工具只是包在 lookup_building_code 与 search_building_code 这两个代码库里已经存在的函数外面的薄薄一层。有了 tool runner，你直接把这些函数传进去，而智能体在它写的每一条发现里都会引用具体的规范条款 —— 无需写任何 schema。

⭐⭐ 两个架构信号： 1. thin wrappers（薄封装） —— 官方主张工具层不承载业务逻辑，业务在函数里。这是可测性的关键：薄封装 = 好测、好审计。 2. cites specific code sections（引用具体条款） —— 工具带回的原文证据让输出可溯源。 这与课程 002 的 Diligence 完全同构：002 说合规义务要映射到具名的控制项、负责人与证据物；本课的平台层对应物就是「每条发现都引用规范条款」。证据来自工具，责任仍在人。 呼应考纲：领域 3（可溯源集成）+ 领域 5（治理与证据）+ 领域 6（文档化与交接）。

🔑 七、核心要点（Recap）· 官方七条

1. Tools give the AI access to your systems. A tool is a function you define and expose; the AI decides when to call it, and your code executes it. 工具让 AI 访问你的系统。工具是你定义并暴露的一个函数；AI 决定何时调用它，而你的代码执行它。
2. Tools are JSON schemas with a name, a description, and an input schema, passed in the request as a tools array. 工具是带 name、description、input schema 三部分的 JSON schema，在请求中以 tools 数组传入。
3. ⭐⭐ Write specific descriptions. Vague descriptions are the number one reason agents misfire. 写具体的 description。含糊的 description 是智能体失灵的头号原因。
4. ⭐ stop_reason: "tool_use" is your signal to run the tool and feed the result back as a tool result. stop_reason: "tool_use" 是你的信号：去运行工具，并把结果作为 tool result 喂回去。
5. For multiple tools, dispatch on the tool name. Adding a tool means adding to the array and adding a case. 多工具时按工具名分发。加一个工具 = 往数组里加一项 + 加一个 case。
6. ⭐ The SDK's tool runner (TypeScript, Python, Ruby) builds schemas from your actual functions and handles the whole loop — or you can run the loop yourself. SDK 的 tool runner（TypeScript、Python、Ruby）从你的真实函数生成 schema 并处理整个循环 —— 或者你也可以自己跑这个循环。
7. ⭐⭐ You execute, or you delegate the loop. At the far end of that spectrum, managed agents delegate the whole agent to the AI provider. 你要么自己执行，要么把循环委托出去。在这条光谱的远端，托管智能体把整个智能体都委托给了平台。

�光 八、⭐⭐ 课末光谱：执行 ↔ 委托（本课的结构性贡献）

官方第 7 条给出了一个三档光谱，这与第 3 课的「模型档位」、第 1 课的「平台三层」一样，是需要整体记忆的骨架：

⭐⭐ 记忆锚：自己执行 → 委托循环 → 委托整个智能体。 每往右一档，你少写一样东西，也少看见一样东西。

⭐⭐ 与课程 002 的三协作模式对照（跨课程最强呼应之一）：

本课光谱	课程 002 的三协作模式	共同点
自己跑循环	Augmentation（你和 AI 一起做）	人在每一步
Tool Runner	（介于 Augmentation 与 Automation 之间）	人守工具实现
Managed agents	接近 Automation / Agency（AI 做，你检查；或边界内自主）	人只定边界与验收

⭐ 注意两个框架的判据不同：002 按「人的位置」分（之前/之中/之后）；本课按「谁拥有执行与循环」分。考试时看题干问的是哪一种。

⭐⭐ 贯穿两门课的那条线： * 002：Delegating implementation is usually safe. Delegating judgment is usually not. * 003 本课：委托「循环」是安全的（Tool Runner），委托「工具实现」则把攻击面也交出去了。 * 003 第 4 课：You own the loop and the tools. the AI owns the reasoning. 三者合起来：推理与循环可以逐步委托；判断力与工具实现权不能交出去。

🧠 本课 → CCAR-P 考点映射

🔤 本课新生词（已回灌 30-单词表/03，2026-10-14）

✅ 本课进度

• [x] 全文精译与架构师级拆解（2026-10-14）
• [x] ⭐⭐ 记录「AI 不执行工具，你的代码执行」及其与第 4 课责任划分的衔接
• [x] ⭐⭐ 记录 description = 头号失灵原因，并与 002 的 Skill 触发考点合并
• [x] ⭐ 记录多工具分发与「加工具动两处」
• [x] ⭐⭐ 记录 Tool Runner 三语言、免写 schema / 免写循环，及 beta 命名空间
• [x] ⭐⭐ 记录课末「执行 ↔ 委托」光谱三档表及与 002 三协作模式的对照
• [x] 记录两处终止写法差异（第 4 课 vs 第 5 课）并给出备考口径
• [x] 英文原文已存：20-English-05-What-is-tool-use.md
• [x] 生词回灌 30-单词表/03-考试核心生词与术语表.md（2026-10-14 建表，301 条入速查区，⭐⭐ 28 条精讲）
• [ ] 官方未提供 What you'll learn 区块 —— 若后续页面补全，需回填

🔗 关联

• 本课英文原文：20-English-05-What-is-tool-use.md ✅ 已存
• 前一课：06-第4课-The-agent-loop-explained.md（循环本体；stop_reason / tool_use_id）
• 后一课：第 6 课 What is thinking?；第 7 课 Built-in tools（平台提供的工具，与「你定义的工具」对照）
• 呼应课程 002：least privilege / capability bloat；Skill 的 description 触发；三协作模式；Delegating implementation is usually safe
• 课程大纲：01-课程导读与大纲全景
• 考纲：00-CCAR-P备考蓝图

⚠️ 语料说明：英文原文中的 model: "current-model-fast" 为抓取/环境替换残留（按第 3 课映射对应 Sonnet 档），已在代码段下方说明；其余英文引句与代码均为官方原句，未作改动。