工具系统Agent 的双手如何长出来第 4 章我们让模型能出手了——但那只是一只手。这一节进入第 5 章六层架构的系统性拆解先从最实在的工具系统说起你手上那几十个工具怎么组织、怎么被模型看见、怎么长成一双灵巧的手。本文导航工具系统在六层架构中的位置工具注册中心工具的户口本JSON Schema 自动生成pydantic 反射工具描述即提示词模型怎么用对工具Tools/Resources/Prompts 三原语与 MCP 的关系工具系统的成熟度从玩具到生产小结下节预告第 21 节。欢迎来到第 5 章——理论区的收官章。前面第 4 章我们把 Agent Loop心脏讲透了。但一个 Agent 只有心脏没有双手就是个空壳。第 5 章要把六层架构第 8 节画的逐层拆开从脑模型接入第 3 章讲过了到手脚到眼睛、缰绳、调度、眼睛的仪表盘——一共 5 层就是第 21-25 节。先从工具系统开始。它是双手决定了 Agent 能不能干活。工具系统在六层架构中的位置回顾一下第 8 节的六层架构从下往上┌─────────────────────────────┐ │ 6 可观测性看得到 Agent 在干嘛 │ ← 第25节 ├─────────────────────────────┤ │ 5 编排多 Agent 怎么调度 │ ← 第24节 ├─────────────────────────────┤ │ 4 权限什么能做、什么不能做 │ ← 第23节 ├─────────────────────────────┤ │ 3 上下文引擎眼睛与记忆 │ ← 第22节 ├─────────────────────────────┤ │ 2 工具系统Agent 的双手 │ ← 这一节 ├─────────────────────────────┤ │ 1 模型接入大脑第3章讲过 │ └─────────────────────────────┘工具系统是离能力最近的一层。但注意工具系统不仅仅是一堆函数它是个有组织的子系统——要解决工具怎么被注册、怎么生成说明书、模型怎么选对工具、工具结果怎么回填这一整串问题。工具注册中心工具的户口本第一个要解决的是户口问题你手上可能有几十个工具读文件、写文件、跑命令、搜网页……如果它们散落在各处模型看不到、代码也管不住。所以要有工具注册中心Tool Registry——一个装着所有可用工具的清单。它的职责很纯粹登记每个工具进来时登记名字、函数、描述、参数 Schema。查询给模型组装tools说明书时从注册中心把所有工具说明书导出来。按名调用模型返回tool_calls里的工具名从注册中心找到对应函数执行。我把它的数据结构想成一张表持有1*ToolRegistrydict toolsregister(name, fn, description, params_schema)to_openai_schemas() : listget(name) : callableToolstr nameCallable fnstr descriptiondict schema注册中心不一定复杂——一个dict[name - Tool]就够启动。它真正的价值在于统一了工具怎么进来、怎么出去的口径不管工具底层是读文件的、查数据库的、还是调外部 API 的在模型眼里、在循环眼里它们都是同一个形态name description schema fn。这个统一形态是整套流程能跑通的前提。JSON Schema 自动生成pydantic 反射第 17 节我们见过工具说明书长什么样——一大堆 JSON Schema。如果每个工具都手写几十个工具写到手抽筋还容易错。聪明做法是用 pydantic 反射自动生成。原理你用一个 pydantic 模型描述工具的参数结构然后model_json_schema()一键生成模型需要的 OpenAI 工具 Schema。这样参数定义一处写Schema 自动生成永远同步、永不手误。tool_schema_demo.py —— pydantic 反射生成工具 JSON Schema第21节 运行环境Python 3.12 uv 依赖 uv add pydantic frompydanticimportBaseModel,FieldclassReadFileParams(BaseModel):读文件工具的参数结构path:strField(description要读取的文件绝对路径)lines:intField(default100,ge1,le500,description读取行数默认100最大500)# 一键反射成 OpenAI 兼容的工具参数 SchemaschemaReadFileParams.model_json_schema()print(生成的参数 Schema)importjson;print(json.dumps(schema,ensure_asciiFalse,indent2))运行输出生成的参数 Schema { properties: { path: { description: 要读取的文件绝对路径, title: Path, type: string }, lines: { description: 读取行数默认100最大500, default: 100, maximum: 500, minimum: 1, title: Lines, type: integer } }, required: [ path ], title: ReadFileParams, type: object }看到maximum/minimum了吗那是Field(ge1, le500)自动带出来的约束——模型选lines时就会收到最大 500的强约束不会给你填个 99999 把文件读爆。这就是 pydantic 反射的威力参数校验规则 工具说明书 模型约束三者一份代码搞定。后面第 36 节《工具注册中心》会用tool装饰器把这个反射能力封装成三行代码注册一个工具的体验现在先记住自动生成这件事。工具描述即提示词模型怎么用对工具工具系统里有个被严重低估的杠杆工具的描述description。它本质是喂给模型的一段提示词——写得好不好直接决定模型会不会、以及会不会用对这个工具。我踩过的坑早期给一个run_bash工具写了句很笼统的执行 shell 命令。结果模型把本该用读文件解决的简单需求也拿去跑 shell甚至用cat代替read_file——它不是不会是我没说清楚何时该用它。后来我把工具描述按一个公式来写效果立竿见影做什么 何时用 何时不用 一个例子以edit_file为例在文件中执行替换用 old_str 精确匹配要替换的文本用 new_str 替换它。 当需要修改已有代码时使用。如果只是想读文件请用 read_file 如果是新增一个文件请用 write_file。 例子把 x 1 改成 x 2这个公式的价值做什么模型知道这工具能力是啥何时用/何时不用给模型决策边界避免它工具选错例子给模型标准动作降低误用概率。这块的深度玩法、A/B 实验是第 45 节《工具描述工程》的重头戏。这里先立下描述即提示词的认知。Tools/Resources/Prompts 三原语与 MCP 的关系你可能在想工具系统搞这么复杂外面那套 MCP 生态是啥关系这里提前统一认知方便你理解后续 MCP 章节第 13 章。MCPModel Context Protocol定义了三种原语可以把它们理解成三类不同性质的能力原语是什么类比谁掌握Tools可被模型调用的函数读文件/查库双手模型主动调用Resources只读的数据资源文件内容/数据库记录参考书模型按需读取Prompts预设的提示词模板操作手册模型可套用关键认知Tools、Resources、Prompts 在架构上是三兄弟——Tools 是能干活的Resources 是能看的Prompts 是能参考的。Claude Code、DeepPilot 这些 Agent 里工具系统主要是 Tools但成熟的 harness 会把三者统一管理。到第 13 章接入 MCP 时你会发现MCP Server 本质上就是提供一个或多个 Tools/Resources/Prompts 的标准化接口。你现在把工具系统的三原语想清楚后面看 MCP 就是外部来的工具怎么入驻这个注册中心的问题——水到渠成。工具系统的成熟度从玩具到生产工具系统不是一蹴而就的它有个成熟度阶梯。我按深浅给你排一下你心里好有个谱阶段特征对应课程玩具级一个 dict 装几个函数硬编码调用第 8 章 35-37 节规范级工具注册中心 Schema 自动生成 统一错误第 9 章 v0.4安全级权限守卫、沙箱、路径白名单第 10 章 v0.5生态级接入外部 MCP Server动态注入第 13 章 v0.8别一上来就整 MCP——那是生态级是锦上添花。先把玩具级→规范级走扎实工具系统的双手才算真正长成、长实。课程的实战线正是按这个阶梯往上搭的。小结工具系统是六层架构的双手但它是个有组织的子系统不是一堆散函数。工具注册中心统一所有工具的形态namedescriptionschemafn是整套流程的户口本。pydantic 反射一键生成 JSON Schema参数校验规则 工具说明书 模型约束三合一。工具描述即提示词按做什么何时用何时不用例子写模型才能用对工具。Tools/Resources/Prompts 三原语是理解 MCP 生态的钥匙Tools 是能干的、Resources 是能看的、Prompts 是能参考的。工具系统有成熟度阶梯玩具→规范→安全→生态按序升级别跳级。下节预告双手有了但 Agent 还要眼睛和记忆才能看清世界、记住上下文。下一节讲上下文工程——为什么说上下文窗口是内存、消息历史是堆栈、系统提示是 BIOS这是 Agent 的眼睛与记忆也是第 8 节六层架构里最难量化的一层。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~ DeepSeek-Agent-Harness-2026终极指南-第5章第21节-六层架构-工具系统：Agent的双手如何长出来
工具系统Agent 的双手如何长出来第 4 章我们让模型能出手了——但那只是一只手。这一节进入第 5 章六层架构的系统性拆解先从最实在的工具系统说起你手上那几十个工具怎么组织、怎么被模型看见、怎么长成一双灵巧的手。本文导航工具系统在六层架构中的位置工具注册中心工具的户口本JSON Schema 自动生成pydantic 反射工具描述即提示词模型怎么用对工具Tools/Resources/Prompts 三原语与 MCP 的关系工具系统的成熟度从玩具到生产小结下节预告第 21 节。欢迎来到第 5 章——理论区的收官章。前面第 4 章我们把 Agent Loop心脏讲透了。但一个 Agent 只有心脏没有双手就是个空壳。第 5 章要把六层架构第 8 节画的逐层拆开从脑模型接入第 3 章讲过了到手脚到眼睛、缰绳、调度、眼睛的仪表盘——一共 5 层就是第 21-25 节。先从工具系统开始。它是双手决定了 Agent 能不能干活。工具系统在六层架构中的位置回顾一下第 8 节的六层架构从下往上┌─────────────────────────────┐ │ 6 可观测性看得到 Agent 在干嘛 │ ← 第25节 ├─────────────────────────────┤ │ 5 编排多 Agent 怎么调度 │ ← 第24节 ├─────────────────────────────┤ │ 4 权限什么能做、什么不能做 │ ← 第23节 ├─────────────────────────────┤ │ 3 上下文引擎眼睛与记忆 │ ← 第22节 ├─────────────────────────────┤ │ 2 工具系统Agent 的双手 │ ← 这一节 ├─────────────────────────────┤ │ 1 模型接入大脑第3章讲过 │ └─────────────────────────────┘工具系统是离能力最近的一层。但注意工具系统不仅仅是一堆函数它是个有组织的子系统——要解决工具怎么被注册、怎么生成说明书、模型怎么选对工具、工具结果怎么回填这一整串问题。工具注册中心工具的户口本第一个要解决的是户口问题你手上可能有几十个工具读文件、写文件、跑命令、搜网页……如果它们散落在各处模型看不到、代码也管不住。所以要有工具注册中心Tool Registry——一个装着所有可用工具的清单。它的职责很纯粹登记每个工具进来时登记名字、函数、描述、参数 Schema。查询给模型组装tools说明书时从注册中心把所有工具说明书导出来。按名调用模型返回tool_calls里的工具名从注册中心找到对应函数执行。我把它的数据结构想成一张表持有1*ToolRegistrydict toolsregister(name, fn, description, params_schema)to_openai_schemas() : listget(name) : callableToolstr nameCallable fnstr descriptiondict schema注册中心不一定复杂——一个dict[name - Tool]就够启动。它真正的价值在于统一了工具怎么进来、怎么出去的口径不管工具底层是读文件的、查数据库的、还是调外部 API 的在模型眼里、在循环眼里它们都是同一个形态name description schema fn。这个统一形态是整套流程能跑通的前提。JSON Schema 自动生成pydantic 反射第 17 节我们见过工具说明书长什么样——一大堆 JSON Schema。如果每个工具都手写几十个工具写到手抽筋还容易错。聪明做法是用 pydantic 反射自动生成。原理你用一个 pydantic 模型描述工具的参数结构然后model_json_schema()一键生成模型需要的 OpenAI 工具 Schema。这样参数定义一处写Schema 自动生成永远同步、永不手误。tool_schema_demo.py —— pydantic 反射生成工具 JSON Schema第21节 运行环境Python 3.12 uv 依赖 uv add pydantic frompydanticimportBaseModel,FieldclassReadFileParams(BaseModel):读文件工具的参数结构path:strField(description要读取的文件绝对路径)lines:intField(default100,ge1,le500,description读取行数默认100最大500)# 一键反射成 OpenAI 兼容的工具参数 SchemaschemaReadFileParams.model_json_schema()print(生成的参数 Schema)importjson;print(json.dumps(schema,ensure_asciiFalse,indent2))运行输出生成的参数 Schema { properties: { path: { description: 要读取的文件绝对路径, title: Path, type: string }, lines: { description: 读取行数默认100最大500, default: 100, maximum: 500, minimum: 1, title: Lines, type: integer } }, required: [ path ], title: ReadFileParams, type: object }看到maximum/minimum了吗那是Field(ge1, le500)自动带出来的约束——模型选lines时就会收到最大 500的强约束不会给你填个 99999 把文件读爆。这就是 pydantic 反射的威力参数校验规则 工具说明书 模型约束三者一份代码搞定。后面第 36 节《工具注册中心》会用tool装饰器把这个反射能力封装成三行代码注册一个工具的体验现在先记住自动生成这件事。工具描述即提示词模型怎么用对工具工具系统里有个被严重低估的杠杆工具的描述description。它本质是喂给模型的一段提示词——写得好不好直接决定模型会不会、以及会不会用对这个工具。我踩过的坑早期给一个run_bash工具写了句很笼统的执行 shell 命令。结果模型把本该用读文件解决的简单需求也拿去跑 shell甚至用cat代替read_file——它不是不会是我没说清楚何时该用它。后来我把工具描述按一个公式来写效果立竿见影做什么 何时用 何时不用 一个例子以edit_file为例在文件中执行替换用 old_str 精确匹配要替换的文本用 new_str 替换它。 当需要修改已有代码时使用。如果只是想读文件请用 read_file 如果是新增一个文件请用 write_file。 例子把 x 1 改成 x 2这个公式的价值做什么模型知道这工具能力是啥何时用/何时不用给模型决策边界避免它工具选错例子给模型标准动作降低误用概率。这块的深度玩法、A/B 实验是第 45 节《工具描述工程》的重头戏。这里先立下描述即提示词的认知。Tools/Resources/Prompts 三原语与 MCP 的关系你可能在想工具系统搞这么复杂外面那套 MCP 生态是啥关系这里提前统一认知方便你理解后续 MCP 章节第 13 章。MCPModel Context Protocol定义了三种原语可以把它们理解成三类不同性质的能力原语是什么类比谁掌握Tools可被模型调用的函数读文件/查库双手模型主动调用Resources只读的数据资源文件内容/数据库记录参考书模型按需读取Prompts预设的提示词模板操作手册模型可套用关键认知Tools、Resources、Prompts 在架构上是三兄弟——Tools 是能干活的Resources 是能看的Prompts 是能参考的。Claude Code、DeepPilot 这些 Agent 里工具系统主要是 Tools但成熟的 harness 会把三者统一管理。到第 13 章接入 MCP 时你会发现MCP Server 本质上就是提供一个或多个 Tools/Resources/Prompts 的标准化接口。你现在把工具系统的三原语想清楚后面看 MCP 就是外部来的工具怎么入驻这个注册中心的问题——水到渠成。工具系统的成熟度从玩具到生产工具系统不是一蹴而就的它有个成熟度阶梯。我按深浅给你排一下你心里好有个谱阶段特征对应课程玩具级一个 dict 装几个函数硬编码调用第 8 章 35-37 节规范级工具注册中心 Schema 自动生成 统一错误第 9 章 v0.4安全级权限守卫、沙箱、路径白名单第 10 章 v0.5生态级接入外部 MCP Server动态注入第 13 章 v0.8别一上来就整 MCP——那是生态级是锦上添花。先把玩具级→规范级走扎实工具系统的双手才算真正长成、长实。课程的实战线正是按这个阶梯往上搭的。小结工具系统是六层架构的双手但它是个有组织的子系统不是一堆散函数。工具注册中心统一所有工具的形态namedescriptionschemafn是整套流程的户口本。pydantic 反射一键生成 JSON Schema参数校验规则 工具说明书 模型约束三合一。工具描述即提示词按做什么何时用何时不用例子写模型才能用对工具。Tools/Resources/Prompts 三原语是理解 MCP 生态的钥匙Tools 是能干的、Resources 是能看的、Prompts 是能参考的。工具系统有成熟度阶梯玩具→规范→安全→生态按序升级别跳级。下节预告双手有了但 Agent 还要眼睛和记忆才能看清世界、记住上下文。下一节讲上下文工程——为什么说上下文窗口是内存、消息历史是堆栈、系统提示是 BIOS这是 Agent 的眼睛与记忆也是第 8 节六层架构里最难量化的一层。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~