AI神功 KNOWLEDGE BASE
内功06 · AI Agent 智能体·第 14 关 / 36 约 5 分钟

INNER 06 / AGENT / 02 · ENGINE v1

工具调用设计模式(Lesson 04: Tool Use Design Pattern)

本关练习：为售后退款智能体编写严谨的 Tool JSON Schema。

约 5 分钟·免费阅读·整理自 AI 现代必修课 · 内功06·来源精读 ↓·直接做题 ↓

30 SECONDS / 30 秒看懂

这一关只解决一件事：根据 Microsoft AI Agents for Beginners 第 4 课与 LLM Engineering 工具调用实验,大模型本身并不会直接运行代码或查数据库 , 而是根据你提供的工具函数签名与文档字符串 ( Docstring / JSON Schema),输出结构化的函数名与 JSON 参数,由宿主程序执行后再将结果返回给模型。工具调用成败的 80% 取决于函数描述是否清晰说明了“何时该调、何时不该调”以及参数枚举/格式约束。

  • 编写完整的 OpenAI/Pydantic 兼容 JSON Schema,包含工具名、详细调用前提说明(description) 与 required 必填字段列表(
  • 5 分);
  • 为 order_id、refund_amount_cny(设定单笔上限说明)、reason_category(设定枚举值 enum)三个参数提供精确类型与业务约束;

3 MINUTES / 3 分钟拆解

先看来源里的例子：PDF 本关任务（来源）

输入
你要为客服 Agent 配备一个“查询订单物流与发起部分退款”的工具声明,防止模型在未核实物流状态前乱调退款接口。 待改造劣质定义:{"name": "refund", "description": "给客戶退款", "parameters": {"id": "string", "money": "number"}}

发生了什么

来源要求：编写完整的 OpenAI/Pydantic 兼容 JSON Schema,包含工具名、详细调用前提说明(description) 与 required 必填字段列表( / 5 分); / 为 order_id、refund_amount_cny(设定单笔上限说明)、reason_category(设定枚举值 enum)三个参数提供精确类型与业务约束;

输出

参考答案：参考答案:售后部分退款工具的强类型 JSON Schema 定义 { "name": "initiate_partial_refund", "description": "向买家发起订单部分退款。调用前提:必须先调用 get_logistics_status 确认包裹已签收或存在核实的物流异常,严禁在未查询订单状态前直接调用本工具。单笔自动退款上限为 200 元人⺠币。", "parameters": { "type": "objec

术语拆开

JSON Schema
描述工具参数结构和约束的格式。
required
调用时必须提供的参数。

为什么有效

来源核心原理：根据 Microsoft AI Agents for Beginners 第 4 课与 LLM Engineering 工具调用实验,大模型本身并不会直接运行代码或查数据库 , 而是根据你提供的工具函数签名与文档字符串 ( Docstring / JSON Schema),输出结构化的函数名与 JSON 参数,由宿主程序执行后再将结果返回给模型。工具调用成败的 80% 取决于函数描述是否清晰说明了“何时该调、何时不该调”以及参数枚举/格式约束。 踩坑 Schema vs. 高手 Schema 对比: 新手踩坑写法:定义一个函数 def query_db(sql: str),描述仅写“查询数据库”。结果模型自己瞎猜表名和字段名,拼出错误的 SQL 甚至引发删表⻛险。 高手强类型工具定义:将模糊的通用查询拆解为语义明确的业务原子工具(如 get_order_status_by_id(order_id: str)),并在参数描述中注明正则格式(如“必须是以 ORD- 开头的 12 位订单号”)及错误返回值格式。

结构长什么样

编写完整的 OpenAI/Pydantic 兼容 JSON Schema,包含工具名、详细调用前提说明(description) 与 required 必填字段列表(
5 分);
为 order_id、refund_amount_cny(设定单笔上限说明)、reason_category(设定枚举值 enum)三个参数提供精确类型与业务约束;
设计当参数校验失败时返回给 Agent 的结构化错误提示格式,引导 Agent 向用戶追问缺失信息而非盲目报错。 第二阶段:核心能力篇(第 3‒4 关)——目标规划拆解与智能体记忆系统

为什么 description 和 required 会直接影响工具调用？

SOURCE READING / 来源精读

根据 Microsoft AI Agents for Beginners 第 4 课与 LLM Engineering 工具调用实验,大模型本身并不会直接运行代码或查数据库 , 而是根据你提供的工具函数签名与文档字符串 ( Docstring / JSON Schema),输出结构化的函数名与 JSON 参数,由宿主程序执行后再将结果返回给模型。工具调用成败的 80% 取决于函数描述是否清晰说明了“何时该调、何时不该调”以及参数枚举/格式约束。

逐点读懂

  1. 编写完整的 OpenAI/Pydantic 兼容 JSON Schema,包含工具名、详细调用前提说明(description) 与 required 必填字段列表(
  2. 5 分);
  3. 为 order_id、refund_amount_cny(设定单笔上限说明)、reason_category(设定枚举值 enum)三个参数提供精确类型与业务约束;

怎么对应本关练习

先读 30 秒与 3 分钟拆解，再读本关原文与实验，最后做客观题和实操题；答案在下方。

例子在哪

本关任务与参考答案见页面下方；来源为本册 PDF 对应关卡。

本关先记住：编写完整的 OpenAI/Pydantic 兼容 JSON Schema,包含工具名、详细调用前提说明(description) 与 required 必填字段列表(

SOURCESPDF 第 2 关（用户提供）Microsoft · Lesson 4 Tool Use ↗

核心原理

根据 Microsoft AI Agents for Beginners 第 4 课与 LLM Engineering 工具调用实验,大模型本身并不会直接运行代码或查数据库 , 而是根据你提供的工具函数签名与文档字符串 ( Docstring / JSON Schema),输出结构化的函数名与 JSON 参数,由宿主程序执行后再将结果返回给模型。

工具调用成败的 80% 取决于函数描述是否清晰说明了“何时该调、何时不该调”以及参数枚举/格式约束。

踩坑 Schema vs. 高手 Schema 对比: 新手踩坑写法:定义一个函数 def query_db(sql: str),描述仅写“查询数据库”。

结果模型自己瞎猜表名和字段名,拼出错误的 SQL 甚至引发删表⻛险。

高手强类型工具定义:将模糊的通用查询拆解为语义明确的业务原子工具(如 get_order_status_by_id(order_id: str)),并在参数描述中注明正则格式(如“必须是以 ORD- 开头的 12 位订单号”)及错误返回值格式。

第 2 关实操练习题：为售后退款智能体编写严谨的 Tool JSON Schema

任务背景

你要为客服 Agent 配备一个“查询订单物流与发起部分退款”的工具声明,防止模型在未核实物流状态前乱调退款接口。

待改造劣质定义:{"name": "refund", "description": "给客戶退款", "parameters": {"id": "string", "money": "number"}}

通关硬性要求（满分 12.5 分）

1. 编写完整的 OpenAI/Pydantic 兼容 JSON Schema,包含工具名、详细调用前提说明(description) 与 required 必填字段列表(

4.5 分);

2. 为 order_id、refund_amount_cny(设定单笔上限说明)、reason_category(设定枚举值 enum)三个参数提供精确类型与业务约束(5 分);

3. 设计当参数校验失败时返回给 Agent 的结构化错误提示格式,引导 Agent 向用戶追问缺失信息而非盲目报错(3 分)。 第二阶段:核心能力篇(第 3‒4 关)——目标规划拆解与智能体记忆系统

PRACTICE / 本关练习 · 本地规则 + 覆盖检查

为售后退款智能体编写严谨的 Tool JSON Schema

本地检查在你的浏览器里完成，不上传。覆盖检查需要先登录（免费注册），并把这段答案发送到服务器计算一次，算完即弃、不存档，需你点同意；只核对本关评分项覆盖的方向，不在评分项里的题目不会被检查。

0 字未保存

评分项

评分项加载中…

结构分 — / 12.5 分

查看参考答案与得分点 先自己写，再打开＋

参考答案与得分要点

参考答案:售后部分退款工具的强类型 JSON Schema 定义 { "name": "initiate_partial_refund", "description": "向买家发起订单部分退款。调用前提:必须先调用 get_logistics_status 确认包裹已签收或存在核实的物流异常,严禁在未查询订单状态前直接调用本工具。单笔自动退款上限为 200 元人⺠币。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "pattern": "^ORD-[0-9]{8}$", "description": "标准 12 位订单编号,必须以 'ORD-' 开头后跟 8 位数字(如 ORD-20261015)。若用戶未提供,请先向用戶追问。" }, "refund_amount_cny": { "type": "number", "minimum": 0.01, "maximum": 200.00, "description": "退款金额(人⺠币元),保留两位小数,不得超过 200.00 元。" }, "reason_category": { "type": "string", "enum": ["DELAYED_SHIPPING", "MINOR_DEFECT", "PRICE_MATCH", "MISSING_ACCESSORY"], "description": "退款原因分类枚举值,必须严格从四个预设枚举项中选择。" } }, "required": ["order_id", "refund_amount_cny", "reason_category"], "additionalProperties": false } } // 参数校验失败时的结构化回退返回示例: {"status": "validation_error", "error_field": "order_id", "agent_instruction": "订单号格式不合法或缺失,请礼貌询问买家提供以 ORD- 开头的 12 位订单号,切勿自行编造参数重试。"} 得分要点拆解:完整声明 JSON Schema 与前置调用约束(4.5 分);对订单号正则、金额上下限、原因枚举进行强类型锁定(5 分);提供面向 Agent 的结构化错误回退指引(3 分)。 第 3 关

网页永久免费。完整 PDF 会按顺序发给留邮箱的读者，不转售、不群发广告。

留邮箱，获取完整 PDF ↗
上一关Agent 核心循环与框架选型下一关任务规划与动态拆解模式
← 上一关 下一关 →