📘 第 7 课：Built-in tools（内置工具）

所属课程：the AI Platform 101（课程 003） 官方课时定位：Section 3「Extending your Agent」— Lesson 7 / 共 12 课时 ID：486258 ｜ 官方地址：https://anthropic.skilljar.com/claude-platform-101/486258 形式：Video（视频课 + 文稿） 针对认证：CCAR-P（架构师 Professional） 整理日期：2026-10-14 ⚠️ 语料来源：官方 Skilljar 课程正文（用户提供，需登录）。CC BY-NC-SA 4.0，仅供个人学习。 ⭐⭐ 本课权重提示：工具三分法的定型课。官方在这里把工具分成了 custom / server / client 三类，并给了一个反直觉的事实（server tools 不需要 agent loop）与一条态度性判语（网上能查到不等于它是真的）。命中领域 3（19%）＋ 领域 5（14%）＋ 领域 4（16%）。

🎯 本课学习目标

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

1. 能区分 custom / server / client 三类工具：谁写 schema、谁执行、要不要循环。
2. ⭐⭐ 能背出三个 server tools 及各自作用。
3. ⭐⭐ 能说清 server tools 为什么不需要 agent loop。
4. 能认出新的 block 类型（server_tool_use 与工具结果 block）。
5. 能说出两个 client tools（memory / bash）及其特点。
6. ⭐⭐ 能复述官方那条验证态度的原句。

📖 一、视频导读：为什么要有内置工具

官方原句： You can build your own custom tools, but some capabilities are common enough that the AI provider ships them pre-built. You don't write the code. You don't host the sandbox. You just declare the tool, and the AI provider runs it.**

精译：你可以构建你自己的自定义工具，但有些能力足够通用，平台就把它们预置好一起发布了。你不用写代码。你不用托管沙箱。你只要声明这个工具，平台来运行它。

⭐⭐ 三个「不用」构成了内置工具的价值主张： You don't write the code. You don't host the sandbox. You just declare the tool.

呼应第 1 课三层架构：内置工具属于 Primitives 层（web search, code execution 都在第 1 课 Primitives 名单里），但执行发生在平台侧的基础设施上 —— 这就把 Primitives 与 Infrastructure 打通了。

🖥️ 二、⭐⭐ Server tools：你声明，平台跑

官方原句： the AI provider provides server tools that run on their infrastructure. You don't execute these — the AI provider does. That means you don't need an agent loop for these calls. the AI calls the tools on its own, and the result comes back inside the same response.

精译：平台提供运行在他们基础设施上的 server tools。你不执行这些 —— 是平台在执行。这意味着这些调用你不需要 agent loop。AI 自己调用这些工具，结果就在同一次响应里回来了。

⭐⭐ 三个要点（每一句都可命题）

⭐⭐ 本课最重要的对照（必背）：

	Custom tools（第 4–5 课）	Server tools（本课）
谁执行	⭐ 你的代码	⭐ 平台
需要 agent loop	⭐ 需要（stop_reason → 执行 → 回传 → 再调用）	⭐⭐ 不需要
请求次数	多次（一次循环一次调用）	⭐ 一次
结果在哪	下一轮请求的 tool_result 里	⭐ 同一次响应里
官方论断	the AI doesn't execute the tool — your code does	You don't execute these — the AI provider does

记忆锚：自定义工具 = 你要跑循环；server tools = 平台自己跑完一起回来。

⚠️ 命题陷阱：题干给「使用 web_search 后需要手写 while 循环处理 tool_result」→ 错。server tools 不需要循环。

⭐ 三个主要 server tools（枚举题）

⭐⭐ returns results with citations（返回带引用的结果） —— 与第 5 课的 cites specific code sections 是同一条可溯源原则： * 第 5 课：工具带回规范条款原文 → 输出引用条款； * 本课：web search 带回引用来源 → 输出可核查。 * 呼应课程 002 的 Diligence：合规义务要映射到具名的控制项、负责人与证据物 —— 引用就是证据物。

⭐ sandbox（沙箱） —— 呼应第 1 课 Infrastructure 与第 11–12 课 managed agents 的 sandboxed。沙箱 = 执行边界，是领域 5 的安全考点词。 ⭐ web fetch 取「完整内容」 —— 与考纲领域 3 的 RAG 流水线 / 检索策略相关（虽然本课未展开）。

官方代码（保持原样）

import anthropic

client = anthropic.the AI provider()

# Call 1: web search — the AI provider runs the search server-side
search_response = client.messages.create(
    model="current-model",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[
        {"role": "user", "content": "What is the AI provider's latest model release? Answer in one sentence."}
    ],
)

for block in search_response.content:
    if block.type == "server_tool_use":
        print(f"Tool call: {block.name} — {block.input}")
    elif block.type == "text":
        print(block.text)

# Call 2: code execution — the AI writes and runs Python in a sandbox
code_response = client.messages.create(
    model="current-model",
    max_tokens=1024,
    tools=[{"type": "code_execution_20260120", "name": "code_execution"}],
    messages=[
        {"role": "user", "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"}
    ],
)

for block in code_response.content:
    if block.type == "server_tool_use":
        print(f"Tool call: {block.name} — {block.input}")
    elif block.type == "bash_code_execution_tool_result":
        print(f"stdout: {block.content.stdout}")
    elif block.type == "text":
        print(block.text)

⚠️ 抓取件说明：anthropic.the AI provider() 与 model="current-model" 为替换残留（按第 3 课映射 = Opus 档）。不要背这些字符串。

⭐ 声明写法：只有 type + name（注意版本号）

tools=[{"type": "web_search_20260209", "name": "web_search"}]

⭐⭐ 两个观察： 1. ⭐ 没有 description，也没有 input_schema —— 与第 5 课的自定义工具（三要素）形成鲜明对照。因为平台已经知道这些工具是什么。 考点：题干问「声明内置工具需要提供什么」→ type 与 name；不需要 description / input_schema。 2. ⭐ type 里带日期版本号（web_search_20260209、code_execution_20260120）—— 内置工具类型是版本化的。 推论（我的分析）：这意味着工具行为被版本钉住，升级时需显式改版本号 —— 这是可复现性设计，对应考纲领域 4 的「评估可重复」。

🧱 三、⭐ 官方点名的两件事（Two things to notice）

① 没有 agent loop

There's no agent loop here.* We don't switch on stop_reason. We don't push tool results back. the AI provider runs the tool server-side, and the response already contains the result*.

精译：这里没有 agent loop。 我们不对 stop_reason 做分支。我们不把工具结果塞回去。平台在服务端运行工具，而响应里已经包含了结果。

⭐⭐ 这一句把第 4/5 课刚教的三件事全部"取消"了： | 第 4–5 课必做 | 本课明确不做 | |---|---| | switch on stop_reason | ⭐ We don't switch on stop_reason | | push tool results back into messages | ⭐ We don't push tool results back | | while 循环 | ⭐ There's no agent loop here |

记忆锚：server tools = 一次调用、一次响应、循环蒸发。

② ⭐ 响应里出现了新的 block 类型

The response has new block types.* A server_tool_use block for the tool call, a code execution tool result block for the output, plus the regular text* blocks.

⭐⭐ block 类型家族至此扩大为（跨课汇总，考试极可能考「哪种 block 对应哪种工具」）：

block 类型	出处	谁的工具
text	第 2 课	—
thinking	第 2 课预告 / 第 6 课展开	—
tool_use	第 4–5 课	⭐ 你的（client-side / custom）
tool_result	第 4–5 课	⭐ 你回传的结果（放 user role）
⭐ server_tool_use	第 7 课	⭐ 平台的
⭐ *_tool_result（如 bash）	第 7 课	⭐ 平台回传的结果（已在响应里）

记忆锚：tool_use 是你跑，server_tool_use 是平台跑 —— 前缀 server_ 就是分界线。

▶️ 四、跑起来看（Running it）

For web search, you'll see the AI's tool call printed, then a one-sentence answer about the latest model release with the search citations folded in. For code execution, you'll see the actual Python the AI wrote, the stdout from the sandbox running it, and a final text answer. We didn't have to spin up a search crawler. We didn't run a Python sandbox. We declared two tools and got both for free.

⭐ We didn't have to spin up a search crawler. We didn't run a Python sandbox. （我们不必去起一个搜索爬虫，也不必去跑一个 Python 沙箱。） —— 呼应开篇的三个「不用」，落到了运维负担上。 对应考纲领域 3「集成机制选型」与领域 1「端到端架构」：能外包的就不自建。 呼应课程 002：Delegating implementation is usually safe（委派实现通常是安全的）—— server tools 就是这一条在工具层的实例。

💻 五、⭐ 另一类：Client tools

官方原句： Worth knowing the other category exists. Client tools run where your code runs.* They're shipped in the the AI SDK, so you don't have to define the schema yourself. Two examples: * Memory — the AI reads and writes memory across sessions * Bash — a persistent bash shell so the AI can execute commands They have the same shape as a custom tool, but the SDK gives you the schema and a sensible runner.***

精译：值得知道还有另一类存在。Client tools 跑在你的代码所在的地方。 它们随 SDK 一起发布，所以你不必自己定义 schema。两个例子： * Memory —— AI 跨会话读写记忆 * Bash —— 一个持久的 bash shell，让 AI 能执行命令 它们的形状与自定义工具相同，但 SDK 给了你 schema 和一个合理的 runner。

⭐⭐ 三类工具的最终对照表（本课的结构性产出，务必整体记忆）：

类别	谁给 schema	谁执行	需要 agent loop	出处
Custom tools	⭐ 你（手写 JSON Schema）	⭐ 你（runTool）	⭐ 需要	第 4–5 课
⭐ Server tools	平台（你只给 type + name）	⭐⭐ 平台	⭐⭐ 不需要	第 7 课
⭐ Client tools	⭐ SDK	⭐ 你（你的环境）	需要（但 SDK 给 runner）	第 7 课

记忆锚：server = 平台跑；client = 你的地盘跑，但 schema 白送。

⭐ 两个 client tools 的安全含义（领域 5 / 领域 3）： * Bash = persistent bash shell —— ⭐ 这是本课程出现的危险等级最高的工具：持久 shell 意味着命令执行能力。 呼应课程 002 的 least privilege 与 capability bloat：不是所有场景都该挂 bash。 * Memory 跨会话读写 —— 直接呼应对话第 10 课 Context management：记忆是一种跨会话的上下文延伸，也因此带来数据留存与合规问题（领域 5：GDPR 等）。

⭐ 呼应第 5 课 Tool Runner：两者都体现同一方向 —— SDK 在替你承担 schema 与 runner。区别是 Tool Runner 处理的是你自己的函数，client tools 是SDK 预置的能力。

🏭 六、⭐⭐ 为什么这在生产里重要（含本课的态度判语）

官方原句： In a production app, this is the shortest path to features that would otherwise take weeks. Web search can power a fact-check endpoint that verifies every numeric and regulatory claim in a draft against the live web. One reminder, though: just because something is validated on the internet doesn't mean it's true. Always double-check the AI's work.

精译：在生产应用里，这是通往「否则要花数周」的功能的最短路径。Web search 可以驱动一个事实核查接口，对照实时的互联网，核验一份草稿里的每一个数字与每一条监管声明。 但要提醒一句：某件事在互联网上被验证了，并不等于它就是真的。永远要复核 AI 的工作。

⭐⭐ 本课的态度判语（必背）

just because something is validated on the internet doesn't mean it's true. Always double-check the AI's work.

⭐⭐ 这是本课的道德/态度落点，与课程 002 完全同构： * 002 第 6 课 Lens 1：Code that passes unit tests but **breaks on real data**； * 002 第 9 课：AI output often passes "Does it work?" but stumbles on "**Is it the right thing?**"； * 002 第 8 课：**audit** what you get back（审计你拿回来的东西）； * 本课：Always double-check the AI's work（永远复核）。

四句话是同一条纪律：工具给出的结果与模型给出的结果一样，都不是免检品。 考点提示：题干给「团队用 web search 做事实核查，认为有引用就够了，可以免去人工复核」→ 错。官方明确要求 Always double-check。

⭐ 呼应第 6 课：it can confidently get it wrong —— 引用也在，答案也可能错。

生产价值的表述

• ⭐ the shortest path to features that would otherwise take weeks（通往否则要花数周的功能的最短路径）—— 对应领域 1 的方案价值论证与领域 7 的开发者生产力。
• fact-check endpoint：核验每一个数字与每一条监管声明（every numeric and regulatory claim）—— 呼应第 3 课的 regulatory response 与第 4–6 课的合规审查案例。合规是本课贯穿的场景线。

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

1. Server tools — web search, code execution, web fetch — are declared in your tools array. the AI provider runs them. Server tools —— web search、code execution、web fetch —— 在你的 tools 数组里声明。平台运行它们。
2. ⭐⭐ You get the result in the same response, with no agent loop required. Look for server_tool_use and tool result blocks alongside the regular text blocks. 你在同一次响应里拿到结果，不需要 agent loop。去找 server_tool_use 和工具结果 block，它们与常规 text block 并排。
3. Client tools like memory and bash run where your code runs, but the SDK ships the schema and a runner for you. 像 memory 和 bash 这样的 client tools 跑在你的代码所在处，但 SDK 白送你 schema 与 runner。
4. ⭐⭐ The "hosted by the AI provider" idea scales all the way up: managed agents apply it to the entire agent, not just one tool. 「由平台托管」这个思路可以一路放大：托管智能体把它应用到了整个智能体上，而不只是一个工具。

⭐⭐ 第 4 条是第二条前向钩子（第一条在第 5 课 Recap 第 7 条）。它把「托管」确立为一条贯穿线索： * 第 5 课：委托循环（Tool Runner） * 第 7 课：托管一个工具（server tools） * 第 11–12 课：托管整个智能体（managed agents）

记忆锚：托管的对象可以是一个工具、一个循环，或者整个智能体 —— 光谱越往右，你交出去的越多。

🧠 本课 → CCAR-P 考点映射

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

✅ 本课进度

• [x] 全文精译与架构师级拆解（2026-10-14）
• [x] ⭐⭐ 建立 custom / server / client 三类工具对照表（谁给 schema、谁执行、要不要循环）
• [x] ⭐⭐ 记录「server tools 不需要 agent loop」及与第 4–5 课的取消清单
• [x] ⭐ 记录 block 类型家族扩展（server_tool_use vs tool_use）并做跨课汇总表
• [x] ⭐ 记录三个 server tools、两个 client tools 及安全含义（bash / memory）
• [x] ⭐⭐ 记录态度判语 Always double-check the AI's work 及与 002 四句纪律的合并
• [x] 记录工具类型带日期版本号（标注推论）
• [x] 记录 Recap 第 4 条的第二条「托管」前向钩子
• [x] 英文原文已存：22-English-07-Built-in-tools.md
• [x] 生词回灌 30-单词表/03-考试核心生词与术语表.md（2026-10-14 建表，301 条入速查区，⭐⭐ 28 条精讲）
• [ ] 官方未提供 What you'll learn 区块 —— 若后续页面补全，需回填

🔗 关联

• 本课英文原文：22-English-07-Built-in-tools.md ✅ 已存
• 对照：07-第5课-What-is-tool-use.md（custom tools：你定义、你执行、要循环）
• 对照：06-第4课-The-agent-loop-explained.md（agent loop 本体）
• 前向呼应：第 10 课 Context management（memory 的跨会话上下文）；第 11–12 课 Managed agents（托管放大到整个智能体）
• 呼应课程 002：least privilege / capability bloat；audit what you get back；Discernment；Diligence 的证据物
• 课程大纲：01-课程导读与大纲全景
• 考纲：00-CCAR-P备考蓝图

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