📗 第 6 章 · Tool use with the AI

所属课程：课程 004 Building with the the AI API
官方章节名：Tool use with the AI
课时数：13
CCAR-F 主命中领域：D1 27% ＋ D4 18%
归档日期：2026-10-15

📋 本章课时清单

🎯 本章考点提示

D1（27%）＋ D4（18%）核心，13 课时。tool schemas、message blocks、tool results、多轮、多工具、fine grained tool calling、text edit tool、web search tool。

⭐ 官方 What You'll Learn 第 6 条落这里。与 课程003 第 5 课《What is tool use?》重叠，但本章细到 schema 与 block 层，更深。

📖 逐课精译

课时 1 · Introducing tool use

类型：🎬 视频 ｜ lesson ID：287747 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• Tools allow the AI to access information from the outside world, extending its capabilities beyond what it learned during training.
• By default, the AI only knows information from its training data and can't access current events, real-time data, or external systems.
• Tool use solves this limitation by creating a structured way for the AI to request and receive fresh information.
• Initial Request: You send the AI a question along with instructions on how to get extra data from external sources.
• Final Response: You send the retrieved data back to the AI, which then generates a complete response using both the original question and the fresh data.
• 精译：
• 定位：工具让模型能获取外部世界的信息，突破训练数据的边界。默认情况下，模型只知道训练数据里的内容，无法获取时事、实时数据或外部系统的信息。工具使用为这一限制提供了一种结构化的方式：让模型请求并接收最新信息。
• 没有工具时的问题：用户问"旧金山的天气怎么样？"，模型只能回答"抱歉，我无法获取最新的天气信息"，体验很差。
• 工具使用的四步流程（考点）：
  1. 初始请求：你向模型发送问题，并附上如何从外部获取额外数据的说明。
  2. 工具请求：模型分析问题，判断需要更多信息，于是请求具体的数据（例如某地的天气）。
  3. 数据获取：你的服务端运行代码，从外部 API 或数据库取回所需数据。
  4. 最终回答：你把取回的数据送回模型，模型结合原问题与新数据生成完整回答。
• 天气示例：用户询问当前天气时，提示中包含如何获取天气数据的说明；模型识别出需要实时信息，请求特定地点的天气；服务端调用天气 API，把实时数据送回模型；模型把新数据与用户问题结合，给出准确的当前回答。
• 主要优势：获取训练时不存在的实时信息；连接数据库、API 与其他服务；基于最新信息动态回答；交互结构清晰，模型知道需要什么信息以及如何请求。
• 核心：工具使用把模型从静态知识库变成能处理实时数据的动态助手。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 1，见下方统计）
• 考点映射：映射表标 D1 1.1（Agentic 循环的 Observe 环节）与 D4 4.1（工具体系定位）⭐；本课是工具使用的总流程，四步流程即后续所有课时的骨架。
• ⚠️ 核对项：讲稿说"模型只知道训练数据"是对默认能力的概括；实际可用的外部能力取决于应用是否提供工具，以官方文档为准。
• ⚠️ 核对项：讲稿的天气示例是概念演示，并非某个具体 API 的调用方式；具体的工具模式与消息块见后续课时。

课时 2 · Project overview

类型：🎬 视频 ｜ lesson ID：287751 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• We're going to build a practical project that teaches the AI how to set reminders for future dates.
• The goal is straightforward: we want to be able to tell the AI "Set a reminder for my doctor's appointment. It's a week from Thursday" and have the AI respond with "OK, I will remind you."
• the AI doesn't always handle time-based addition well, especially when looking many days into the future.
• This project demonstrates a key principle of working with AI: when the model has limitations, we extend its capabilities through tools rather than trying to work around those limitations in our prompts.
• 精译：
• 项目目标：做一个能为未来日期设置提醒的功能。用户说"给我的医生预约设个提醒，就在下周四之后一周"，模型回复"好的，我会提醒你"。这看似简单，但暴露了模型的几处局限，需要用工具来解决。
• 三个局限（考点）：
  1. 时间感知有限：模型可能知道当前日期，但不知道确切时间。
  2. 日期计算不可靠：模型在做时间加减时不总是可靠，尤其是往后推很多天。
  3. 没有提醒能力：模型没有内置的提醒机制。
• 三个工具：① 获取当前日期时间，让模型精确知道此刻；② 为日期时间增加时长，给模型一个可靠的加法工具；③ 设置提醒，真正把提醒写入系统。
• 实施顺序：一次只做一个工具，先从最简单的开始。这样能先理解工具调用如何工作，再构建更复杂的功能。最终，模型能理解"一周后提醒我"这样的请求，组合这些工具算出确切时间并设置提醒。
• 核心原则（考点）：模型有局限时，应当通过工具扩展它的能力，而不是试图在提示词里绕过这些局限。这是本项目的主线思想。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 2，见下方统计）
• 考点映射：映射表标 D1 1.1（Agentic 循环中的工具调用）与 D4 4.3（工具边界定义）⭐；本课是项目设计课，把"局限→工具"的思路落到三个具体工具上。
• ⚠️ 核对项：讲稿说模型"知道当前日期"但"不知道确切时间"，这是对讲者所用模型能力的描述，不同模型与配置的实际能力以官方文档为准。
• ⚠️ 核对项：讲稿中的三个工具名（获取日期时间、增加时长、设置提醒）是本项目的设计，不是官方 SDK 提供的工具。

课时 3 · Tool functions

类型：🎬 视频 ｜ lesson ID：287756 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• A tool function is a plain Python function that gets executed automatically when the AI decides it needs extra information to help a user.
• Use descriptive names: Both your function name and parameter names should clearly indicate their purpose.
• Validate inputs: Check that required parameters aren't empty or invalid, and raise errors when they are.
• the AI can see error messages and might retry the function call with corrected parameters.
• Creating the function is just the first step. Next, you'll need to write a JSON schema that describes the function to the AI.
• 精译：
• 定义：工具函数（tool function）就是一个普通的 Python 函数。当模型判断需要额外信息来帮助用户时，它会被自动执行。例如用户问"现在几点？"，模型会调用日期时间工具获取当前时间。
• 最佳实践（考点）：
  1. 命名描述性强：函数名与参数名都应清楚表明其用途。
  2. 校验输入：检查必需参数是否为空或无效，无效时抛出错误。
  3. 错误信息要有意义：模型能看到错误信息，并可能据此用修正后的参数重试。
• 为什么校验很重要：模型会从错误中学习。若抛出"Location cannot be empty"这样清楚的错误，模型可能会带着有效的地点再次调用。
• 第一个工具函数（代码要点）：get_current_datetime(date_format="%Y-%m-%d %H:%M:%S")。先检查 date_format 是否为空，为空则抛出 ValueError；否则返回 datetime.now().strftime(date_format)。它使用 Python 的 datetime 模块，按传入的格式字符串格式化当前时间。
• 测试：默认格式输出类似 "2024-01-15 14:30:25"；传入 "%H:%M" 则只输出时分，如 "14:30"。
• 校验的意义：这段校验几乎不会触发，但它示范了一种模式：校验输入，并给出模型能够学习的有用错误信息。
• 下一步：写出描述该函数的 JSON 模式（schema），再把它接入聊天系统。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 3，见下方统计）
• 考点映射：映射表标 D4 4.3（工具边界定义：命名、校验、错误回传）⭐⭐ 与 4.4（工具调用错误处理）；本课是 4.3 与 4.4 的最佳实践课时。
• ⚠️ 核对项：讲稿中的 get_current_datetime 与三个工具名是本项目的示例函数，不是官方 SDK 的函数。
• ⚠️ 核对项：讲稿说"模型会从错误中学习"是对模型行为的概括，实际重试行为取决于模型与应用的处理方式，以官方文档为准。
• ⚠️ 核对项：讲稿中 datetime 的导入语句未出现在代码块中，编码时需自行 from datetime import datetime。

课时 4 · Tool schemas

类型：🎬 视频 ｜ lesson ID：287753 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• JSON Schema isn't specific to AI or tool calling - it's a widely-used data validation specification.
• The complete tool specification has three main parts: name, description, input_schema.
• Aim for 3-4 sentences explaining what the tool does. Describe when the AI should use it. Explain what kind of data it returns.
• Write a valid JSON schema spec for the purposes of tool calling for this function.
• 精译：
• 定位：工具模式（schema）是紧跟工具函数之后的一步，用来告诉模型函数接收哪些参数、该如何使用。它是模型读取的说明文档，决定模型何时、如何调用工具。
• JSON Schema 的来历：JSON Schema 不是 AI 专用的规范，而是多年来广泛使用的数据校验规范。AI 社区采用它，是因为它适合描述函数参数并校验数据。
• 完整的工具规范（考点）：三部分：name（清晰的名称，如 get_weather）；description（工具做什么、何时使用、返回什么）；input_schema（描述函数参数的 JSON Schema）。
• 写好描述的要点：约 3–4 句话说明工具做什么；说明模型何时应当使用它；说明它返回哪种数据；为每个参数提供详细描述。
• 用模型生成模式：把工具函数代码交给模型，附上官方的工具使用文档作为背景，请它按文档的最佳实践写出 JSON 模式。讲稿给出的提示语是："Write a valid JSON schema spec for the purposes of tool calling for this function. Follow the best practices listed in the attached documentation."
• 代码要点：schema 放在函数下方，命名遵循"函数名 + _schema"的模式，例如 get_current_datetime_schema。其中 input_schema 是 type: object，properties 下列出 date_format（类型 string、带描述与默认值），required 为空列表，因为该参数有默认值。
• 类型安全：可以从 anthropic.types 导入 ToolParam，用它包装 schema 字典，以便类型检查，避免与 API 配合时出现类型错误。讲稿说明这一步并非功能上必需，但能让代码更健壮。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 4，见下方统计）
• 考点映射：映射表标 D4 4.3（工具边界定义：schema 即描述契约）⭐⭐；同时涉及 D3 3.2（schema 约束输出）。本课是 4.3 的核心课时之一。
• ⚠️ 核对项：讲稿说"三部分"是 name、description、input_schema，这是讲稿的组织方式；官方文档中工具定义的字段名与结构以当前版本为准。
• ⚠️ 核对项：讲稿的 ToolParam 来自 anthropic.types，实际导入路径与用法以 SDK 当前版本为准。
• ⚠️ 核对项：讲稿说 required 为空列表是因为参数有默认值；这是讲稿的示例设计，并非 JSON Schema 的强制规则。

课时 5 · Handling message blocks

类型：🎬 视频 ｜ lesson ID：287757 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• When the AI decides to use a tool, it returns an assistant message with multiple blocks in the content list.
• Remember that the AI doesn't store conversation history - you need to manage it manually.
• When working with tool responses, you must preserve the entire content structure, including all blocks.
• The tools parameter takes a list of JSON schemas that describe the available functions the AI can call.
• 精译：
• 新的响应结构：使用工具时，模型的回复不再只是一个文本块，而是多块消息，其中同时包含文本与工具使用信息。
• 发起带工具的请求：在 API 调用中加入 tools 参数，它接收一个 JSON 模式列表，描述模型可以调用的函数。讲稿示例把 get_current_datetime_schema 放入 tools。
• 多块消息的两类块（考点）：① 文本块（Text Block），面向用户的说明，例如"我来帮你查一下当前时间"；② 工具使用块（ToolUse Block），给你的代码的指令，说明应调用哪个工具、用什么参数。
• ToolUse 块的内容：一个用于追踪调用的 ID；要调用的函数名（如 get_current_datetime）；以字典形式给出的输入参数；类型标记 "tool_use"。
• 会话历史要自己管理：模型不会保存对话历史，你需要手动维护。处理工具响应时，必须完整保留内容结构，包括所有块。
• 追加助手消息：把模型返回的 response.content 原样放入 role: "assistant" 的消息中。这样文本块与工具使用块都被保留，后续调用才能保持上下文。
• 完整的工具调用流程（考点）：① 把用户消息与工具模式一起发给模型；② 收到包含文本块与工具使用块的助手消息；③ 提取工具信息，执行实际函数；④ 把工具结果连同完整的对话历史发回模型；⑤ 收到模型的最终回答。每一步都要正确处理消息结构。
• 辅助函数的更新：如果你之前用 add_user_message() 与 add_assistant_message() 这类辅助函数，它们大多只支持单个文本块，需要改造为支持包含工具使用块的复杂内容。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 5，见下方统计）
• 考点映射：映射表标 D1 1.1（Agentic 循环的执行与观察）⭐ 与 D4 4.4（工具调用的结构化回传）；本课是多块消息与循环流程的主课时。
• ⚠️ 核对项：讲稿示例中的 messages.append(...)、client.messages.create(...) 的参数名（如 max_tokens、tools）以 SDK 当前版本为准；讲稿中的 model 变量需自行定义。
• ⚠️ 核对项：讲稿的 "tool_use" 与 ToolUse 块的字段名（ID、name、input）是讲稿的描述，实际字段以官方文档为准。
• ⚠️ 核对项：讲稿说"模型不保存对话历史"是对无状态 API 的概括，实际是否由应用维护历史以所用接口的文档为准。

课时 6 · Sending tool results

类型：🎬 视频 ｜ lesson ID：287752 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• After the AI requests a tool call, you need to execute the function and send the results back.
• Since your function expects keyword arguments rather than a dictionary, you use Python's unpacking syntax.
• tool_use_id - Must match the id of the ToolUse block that this ToolResult corresponds to.
• Each tool call gets a unique ID, and you must match these IDs when sending back results.
• When sending the follow-up request, you must still include the tool schema even though you're not expecting the AI to make another tool call.
• 精译：
• 定位：模型请求工具调用后，你要执行函数，并把结果送回去。这一步完成了工具使用的闭环。
• 取出参数：工具使用块的参数在 response.content[1].input 中，是一个字典。函数接收关键字参数，因此用解包语法调用：get_current_datetime(**response.content[1].input)。
• 工具结果块（考点）：放在 role: "user" 的消息里，包含三个属性：① tool_use_id，必须与对应工具使用块的 id 一致；② content，工具输出的字符串；③ is_error，出错时为 True。
• 多个工具调用：模型可能在一次回复中发出多个工具使用块。例如"10 + 10 和 30 + 30 分别是多少？"可能产生两个块。每个调用都有唯一 ID，回传结果时必须按 ID 匹配，这样即使结果顺序不同，模型也知道哪个结果对应哪个请求。
• 后续请求的消息历史：必须包含完整对话历史加上新的工具结果。讲稿示例把 tool_result 放进一条用户消息的内容列表中。此时历史包括：原始用户消息；带工具使用块的助手消息；带工具结果块的用户消息。
• 最终请求仍要带工具模式（考点）：即使这次不期望模型再调用工具，也必须在 tools 中继续提供模式。否则模型无法理解历史中提到的工具。
• 最终回答：模型会把工具结果整合成面向用户的自然语言回答，至此工具使用流程完成。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 6，见下方统计）
• 考点映射：映射表标 D4 4.4（工具调用错误处理：tool_use_id 匹配与 is_error 回传）⭐ 与 D1 1.1（执行-观察闭环）；本课是 4.4 的核心课时。
• ⚠️ 核对项：讲稿用 response.content[1] 取第二个块，这是示例中的固定位置写法；实际应按块的 type 查找工具使用块，因为块的顺序并不总是固定的。
• ⚠️ 核对项：讲稿中 tool_use_id、is_error、"tool_result" 等字段名以官方文档为准。
• ⚠️ 核对项：讲稿说"必须带工具模式"是讲稿的要求。官方文档中的具体规则以当前版本为准。

课时 7 · Multi-turn conversations with tools

类型：🎬 视频 ｜ lesson ID：287750 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• When building applications with multiple tools, you need to handle scenarios where the AI might need to call several tools in sequence to answer a single user question.
• This creates a multi-turn conversation pattern where the AI makes multiple tool requests before providing a final answer.
• To handle this pattern, you need a conversation loop that continues until the AI stops requesting tools.
• Your add_user_message and add_assistant_message functions currently assume you're always working with plain text.
• 精译：
• 场景：一个问题可能需要依次调用多个工具。例如"从今天算起第 103 天是哪一天？"，模型需要先获取当前日期，再把 103 天加上去。这形成了多轮工具调用：模型在给出最终回答前，会发出多次工具请求。应用需要自动处理这一过程。
• 多轮工具模式（考点）：① 用户提问；② 模型请求 get_current_datetime；③ 服务端调用函数并返回结果；④ 模型发现还需要信息，请求 add_duration_to_datetime；⑤ 服务端调用该函数并返回结果；⑥ 模型拿到足够信息，给出最终回答。
• 对话循环（代码要点）：run_conversation(messages) 中用 while True 循环：调用 chat(messages) 得到回复；把回复加入历史（add_assistant_message）；若回复不是工具请求，则 break；否则执行工具，把工具结果块作为用户消息加入历史，再进入下一轮。循环结束后返回完整的消息历史。讲稿中的判断条件写作伪代码，实际判断应依据回复中是否含有工具使用块。
• 先重构辅助函数：add_user_message 原先假设内容只是纯文本，需要改造为既能接收字符串，也能接收块列表或完整的 Message 对象。讲稿示例中，若 message 是 Message 类型，就取其 content，否则直接使用传入值。
• 重构 chat 函数：接收 tools 列表，并返回完整的消息对象，而不只是文本。tools 与 system 只在有值时才加入请求参数。
• 提取文本的辅助函数（代码要点）：text_from_message(message) 把消息中所有 type == "text" 的块的文本取出并用换行连接，用于在界面中展示最终回答。
• 重构的意义：辅助函数能处理不同的消息格式；chat 能传递工具模式；返回完整消息，保留所有块；提供提取文本的工具函数。这些是实现循环的基础。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 7，见下方统计）
• 考点映射：映射表标 D1 1.1（Agentic 循环的多轮执行）⭐⭐ 与 D4 4.4（工具结果回传与循环终止）；本课是 1.1 的循环机制主课时。
• ⚠️ 核对项：讲稿的 run_conversation、chat、add_user_message、add_assistant_message、run_tools 等是课程示例的辅助函数，不是官方 SDK 的函数。
• ⚠️ 核对项：讲稿的 while True 循环在没有上限的情况下可能无限循环。实际实现中通常需要设置最大轮数等终止条件，以官方文档与课时 8 的实现为准。
• ⚠️ 核对项：讲稿中 from anthropic.types import Message 的导入路径以 SDK 当前版本为准。

课时 8 · Implementing multiple turns

类型：🎬 视频 ｜ lesson ID：287758 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• Building a conversation system with tools requires implementing a loop that keeps calling the AI until it stops requesting tool usage.
• The key to knowing whether the AI wants to use a tool lies in the stop_reason field of the response message.
• Each tool use block must be answered with a corresponding tool result block. The connection between them is maintained through matching IDs.
• When a tool fails, we still need to provide a result block to the AI.
• 精译：
• 循环的终止条件（考点）：只要模型还在请求工具，就持续调用；模型不再请求工具，就表示已给出最终回答。判断依据是响应消息的 stop_reason 字段：当模型决定调用工具时，它被设为 "tool_use"。因此判断写作 if response.stop_reason != "tool_use": break。
• 对话循环（代码要点）：run_conversation(messages) 中，每轮调用 chat(messages, tools=[...])，把回复加入历史（add_assistant_message），用 text_from_message 打印文本；若 stop_reason 不是 "tool_use" 则结束；否则执行工具（run_tools），把结果作为用户消息加入历史，再进入下一轮。循环结束后返回完整历史。
• 处理多个工具调用：模型的回复内容是块列表，可能包含多个工具使用块。run_tools 用列表推导式筛选出 block.type == "tool_use" 的块，然后逐个处理。
• 工具结果块（考点）：每个工具使用块都必须对应一个工具结果块，两者通过 ID 匹配。结果块包含 type: "tool_result"、tool_use_id（即工具请求的 id）、content（用 json.dumps 序列化的输出）和 is_error（成功为 False）。
• 错误处理（考点）：工具执行失败时，仍然要给模型一个结果块。讲稿用 try/except 包裹执行：成功时构造正常结果块；异常时构造 content 为 f"Error: {e}"、is_error 为 True 的结果块。这样模型能看到错误并决定如何应对。
• 可扩展的路由：run_tool(tool_name, tool_input) 按工具名分发到对应的函数，并用 **tool_input 传入参数。新增工具只需在这里加一个分支，无需改动循环的核心逻辑。
• 完整流程：① 带着可用工具把用户消息发给模型；② 模型回复文本和/或工具请求；③ 执行所有请求的工具并生成结果块；④ 把结果作为用户消息送回；⑤ 重复，直到模型给出最终回答。
• 效果：模型可以在多轮中调用多个工具来完整回答复杂问题；历史保留完整上下文，让模型基于之前的工具结果继续推进。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 8，见下方统计）
• 考点映射：映射表标 D1 1.1（Agentic 循环的终止条件）⭐⭐ 与 D4 4.4（工具调用错误处理与结果回传）；本课是 1.1 循环终止与 4.4 错误回传的核心课时。
• ⚠️ 核对项：讲稿用 stop_reason == "tool_use" 作为循环判断，这是讲稿的写法；stop_reason 的所有取值与含义以官方文档为准。
• ⚠️ 核对项：讲稿的循环没有最大轮数限制。实际应用中需要加上上限，以防止异常情况下无限循环。
• ⚠️ 核对项：讲稿中 content 用 json.dumps(tool_output)，要求输出可被 JSON 序列化；若工具返回的不是可序列化对象，需要先转换。

课时 9 · Using multiple tools

类型：🎬 视频 ｜ lesson ID：287749 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• Adding multiple tools to your Claude implementation becomes straightforward once you have the core tool-handling infrastructure in place.
• The good news is that most of the implementation work is already done.
• The pattern is simple: check the tool name, call the corresponding function with the provided input, and return the result.
• Claude handles this by first explaining what it needs to do, then making the appropriate tool calls in sequence.
• 精译：
• 三个能力：获取当前日期时间（模型需要精确知道时间）；为日期时间增加时长（模型做日期加法不够可靠）；设置提醒（需要一个真正设置提醒的方式）。add_duration_to_datetime 与 set_reminder 的函数与模式已提供，本课只需接入。
• 把工具加入对话：在 run_conversation 中，chat(messages, tools=[...]) 的 tools 列表里加入三个模式：get_current_datetime_schema、add_duration_to_datetime_schema、set_reminder_schema。这样模型就知道有这三个工具可用。
• 路由（代码要点）：run_tool(tool_name, tool_input) 中，每个新工具增加一个 elif 分支，按名称调用对应函数，并用 **tool_input 传入参数，返回结果。
• 测试请求（考点）："Set a reminder for my doctors appointment. Its 177 days after Jan 1st, 2050."。这个请求强制模型先用 add_duration_to_datetime 算出日期，再用 set_reminder 设置提醒。模型会先说明打算做什么，再依次发出工具调用；讲稿中的对话显示模型算出的目标日期是 2050 年 6 月 27 日。
• 消息流（考点）：完整的消息历史包括：用户的请求；同时含文本块与工具使用块的助手消息；工具结果消息；后续的助手消息。这说明模型可以在一条消息里组合解释性文本与工具请求。
• 添加新工具的四步模式：① 实现工具函数；② 定义工具模式；③ 把模式加入 run_conversation 的 tools 列表；④ 在 run_tool 中增加一个分支。
• 意义：有了核心工具基础设施，扩展能力无需重构已有代码，每个新工具都能自然接入现有的对话与工具处理流程。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 9，见下方统计）
• 考点映射：映射表标 D1 1.3（单 Agent 挂多工具的判据）⭐ 与 D4 4.3（多工具的边界与路由）；本课是 1.3 与 4.3 的多工具实操课时。
• ⚠️ 核对项：讲稿中 add_duration_to_datetime、set_reminder 及其模式是本项目的示例函数，不是官方 SDK 的工具。
• ⚠️ 核对项：讲稿说模型"算出 2050 年 6 月 27 日"是示例对话的结果，实际输出取决于模型与实现，不是保证结果。
• ⚠️ 核对项：讲稿中 chat 与 run_tool 等是课程示例的辅助函数，不是官方 SDK 的函数。
• ⚠️ 核对项：讲稿的页面原文用的是 "Claude"，本库统一称"模型"（the AI），考试时以官方术语为准。

课时 10 · Fine grained tool calling

类型：🎬 视频 ｜ lesson ID：313160 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• Fine-grained tool calling does one main thing: it disables JSON validation on the API side.
• The API waits for complete top-level key-value pairs before sending anything.
• Critical: JSON validation is disabled - your code must handle invalid JSON.
• the AI might generate invalid JSON like "word_count": undefined instead of a proper number.
• 精译：
• 流式工具调用的新事件：流式输出中，除了常见的 ContentBlockDelta，工具参数还会产生 InputJsonEvent（讲稿代码中以 chunk.type == "input_json" 判断）。它有两个属性：partial_json，即部分工具参数的 JSON 片段；snapshot，即截至目前累积的完整 JSON。
• API 默认会缓冲并校验（考点）：API 不会立即发送每个生成的片段。它先缓冲，等到一个完整的顶层键值对出现，并按你的模式校验通过后，才把该键值对的所有缓冲片段一并发出，然后再处理下一个顶层键（例如 meta 对象）。这就是为什么流式输出中会出现"停顿后整段涌出"的现象。
• 细粒度工具调用（考点）：要更快、更细粒度的流式输出时，可以开启。它只做一件事：关闭 API 端的 JSON 校验。效果：片段一生成就返回；顶层键之间没有缓冲延迟；行为更接近传统流式；关键：JSON 校验被关闭，你的代码必须自己处理无效 JSON。
• 开启方式：调用时加上 fine_grained=True，讲稿示例是 run_conversation(messages, tools=[save_article_schema], fine_grained=True)。开启后，可能在整个 meta 对象完成之前就收到 word_count。
• 无效 JSON 的处理：开启细粒度模式后，模型可能生成无效 JSON，例如 "word_count": undefined。应用要优雅地处理，讲稿示例用 try: json.loads(chunk.snapshot)，捕获 json.JSONDecodeError 后继续。如果不开启，API 的校验会拦下这类错误，并可能把有问题的值包成字符串，从而与你期望的模式不符。
• 何时使用（考点）：需要向用户展示工具参数生成的实时进度；希望尽快开始处理部分结果；缓冲延迟明显影响体验；并且能够实现健壮的 JSON 错误处理。大多数应用用默认的带校验模式就足够。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 10，见下方统计）
• 考点映射：映射表标 D4 4.4（工具调用错误处理：无效 JSON 的回退）⭐⭐ 与 D5 5.3（流式与可观测性）；本课是 4.4 中流式与错误处理的核心课时。
• ⚠️ 核对项：讲稿说的 InputJsonEvent、chunk.type == "input_json"、partial_json、snapshot 是讲稿所示的事件与字段名，实际事件类型与字段以官方文档为准。
• ⚠️ 核对项：讲稿中的 fine_grained=True 是讲稿示例中 run_conversation 的参数，不一定是 API 的参数名；实际开启方式以官方文档为准。
• ⚠️ 核对项：讲稿中 undefined 是无效 JSON 的例子；实际模型输出的无效形式可能不同，应用的错误处理应覆盖各种解析失败。

课时 11 · The text edit tool

类型：🎬 视频 ｜ lesson ID：287760 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• the AI comes with one built-in tool that you don't need to create from scratch: the text editor tool.
• Here's where things get a bit confusing: while the tool schema is built into the AI, you still need to provide the actual implementation.
• the AI sees this small schema and automatically expands it into the full text editor tool specification behind the scenes.
• Open the ./main.py file and write out a function to calculate pi to the 5th digit. Then create a ./test.py file to test your implementation.
• 精译：
• 定位：文本编辑工具（text editor tool）是模型内置的工具，无需从零编写模式。它让模型像在标准文本编辑器里一样，操作文件和目录。
• 能力清单（考点）：查看文件或目录内容；查看文件中指定行范围；替换文本；创建新文件；在指定行插入文本；撤销最近的编辑。讲稿称它让模型"几乎可以直接当软件工程师"。
• 关键区别：模式内置，实现要自己写（考点）：模型已经内置了这个工具的模式，知道如何发出文件操作请求，但你仍然需要写出真正执行这些操作的函数。与其他工具不同，其他工具你要写 JSON 模式和函数实现两部分；文本编辑工具只需要自己实现函数，负责处理模型请求的创建文件、读取目录、替换文本等操作。
• 模式版本（代码要点）：请求中仍需附上一个小的模式桩（stub），其内容依模型版本而定。讲稿示例 get_text_edit_schema(model)：对 claude-3-7-sonnet 系列返回 type: "text_editor_20250124"，对 claude-3-5-sonnet 系列返回 type: "text_editor_20241022"，name 都是 "str_replace_editor"。模型看到这个小模式后，会在后台自动展开为完整的文本编辑工具规范。
• 实例一：让模型"打开 ./main.py 并总结内容"。模型会先用文本编辑工具查看文件，读取内容，然后给出摘要。
• 实例二：让模型"打开 ./main.py，写一个计算圆周率到第 5 位的函数，再创建 ./test.py 来测试实现"。模型会查看现有的 main.py，用新实现替换其内容（含圆周率函数），并创建带有单元测试的 test.py。
• 为什么要用它（考点）：适用于需要用程序编辑文件的应用；适用于没有完整代码编辑器的环境；希望把文件编辑能力直接集成到自己的 AI 应用里。它让你可以在自己的应用里复现一个带 AI 的代码编辑器的大部分功能，并对模型与文件系统的交互做细粒度控制。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 11，见下方统计）
• 考点映射：映射表标 D4 4.3（有副作用工具的边界设计）⭐ 与 D2 2.2（运行模式与交互权限：修改文件需审批）；本课是内置工具与自实现函数的边界课时。
• ⚠️ 核对项：讲稿说的内置工具模式版本号（text_editor_20250124、text_editor_20241022）与 str_replace_editor 名称，会随版本变化；讲稿提醒要以官方文档的工具版本字符串为准，链接见讲稿开头。
• ⚠️ 核对项：讲稿的 get_text_edit_schema(model) 按模型名前缀判断版本，是讲稿的写法；实际支持的模型与对应版本以官方文档为准。
• ⚠️ 核对项：讲稿的撤销功能、行范围查看等能力列表是讲稿的概括，具体的命令集合与参数以官方文档为准。

课时 12 · The web search tool

类型：🎬 视频 ｜ lesson ID：287755 ｜ 官方直链

• 精译状态：✅ 已精译（2026-10-27，用户粘贴讲稿）
• 官方原句：
• Important note: Your organization must enable the Web Search tool in the settings console before using it.
• Unlike other tools where you need to provide the implementation, the AI handles the entire search process automatically - you just need to provide a simple schema to enable it.
• The max_uses field limits how many searches the AI can perform.
• You can limit searches to specific domains using the allowed_domains field.
• 精译：
• 前置条件：使用网页搜索前，组织必须在控制台的隐私设置中启用该工具。这是账户级别的设置，不是代码能改变的。
• 与其他工具的区别（考点）：网页搜索是模型内置的服务端工具。其他工具你要写模式和函数实现；网页搜索只需要一个模式对象，搜索的整个过程由 the AI 自动完成，你不需要实现任何搜索函数。
• 模式（代码要点）：{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}。max_uses 限制单次请求中模型最多可以搜索的次数，防止后续搜索造成过多的 API 调用。一次搜索会返回多条结果，但模型可能认为需要再搜。
• 响应中的块（考点）：文本块，模型对自己所做事情的说明；ServerToolUseBlock，显示模型实际使用的搜索查询；WebSearchToolResultBlock，包含搜索结果；WebSearchResultBlock，单条结果，带标题与 URL；引用块（Citation），支持模型陈述的原文。引用会包含模型用来支撑回答的具体文字，以及来源 URL。
• 限定域名：用 allowed_domains 字段把搜索限制在指定域名内。讲稿示例 "allowed_domains": ["nih.gov"]，适合医学或运动建议这类需要权威来源的问题，确保得到循证信息，而不是普通博客内容。
• 渲染建议（UI）：文本块作为正文显示；网页搜索结果以来源列表的形式放在顶部；引用内联显示，包括来源域名、页面标题、URL 与引用的原文。这样用户能看出模型是如何得出答案的，也能核对来源，从而建立对回答的信任。
• 适用场景：时事与近期进展；训练数据中没有的专门信息；事实核查与寻找权威来源；需要最新信息的研究任务。
• 使用方式：把模式放进请求的 tools 数组即可，模型会自行判断何时需要搜索。
• 本章新生词：已回灌 30-单词表/04- 第 6 章速查分组（课时 12，见下方统计）
• 考点映射：映射表标 D4 4.3（内置工具的边界）⭐ 与 D5 5.2（外部信息的可信度与引用）；本课是内置服务端工具的主课时，同时涉及引用机制（与第 8 章 Citations 相呼应）。
• ⚠️ 核对项：讲稿的 web_search_20250305 是版本化的工具类型名，会随版本变化，以官方文档当前版本为准。
• ⚠️ 核对项：讲稿中的控制台地址与隐私设置位置是讲稿所示，以官方控制台的实际界面为准。
• ⚠️ 核对项：讲稿说明 max_uses 与 allowed_domains 的行为，具体的默认值、字段约束与可用块类型以官方文档为准。

课时 13 · Quiz on tool use with the AI

类型：📝 测验 ｜ lesson ID：289122 ｜ 官方直链

• 精译状态：⏸ 暂不补（测验，仅视频无题目文字稿；决定 2026-10-27，用户确认）
• 官方原句：待补
• 精译：待补（题目与选项提供后按第 11 章测验的体例收录）
• 本章新生词：待补（回灌 30-单词表/04-）

✅ 本章进度

• [x] 抓取本章讲稿/字幕（课时 1–12 用户粘贴）
• [x] 逐课精译（12/13 课时；课时 13 为测验，待题目）
• [x] 生词回灌 30-单词表/04-（第 6 章分组，课时 1–12）
• [ ] 章节测验（课时 13，仅视频无题目文字稿，暂不补）

🔗 关联

• 上级：课程 004 README
• 导读：01-课程导读与大纲全景
• 生词表：30-单词表/04-（已建 · 第 6 章分组 课时 1–12）
• 登录 SOP：40-认证事务/08-Partner SSO