工具系统与事件驱动:参数校验、错误回传让模型自纠错、事件订阅(dg P05/P06/M05/M07)
把工具系统做扎实:参数校验、错误回传给模型自纠错,再用事件订阅把 Agent 内部状态暴露给外部界面。
今日目标
- 能给每个工具加参数校验,拒绝非法输入并给出可读错误
- 能设计一套让模型看到错误后自己纠正调用参数的机制
- 能订阅 Agent 的事件流,实时输出进度或 typing 状态
昨天结尾留了一句话:D4 的 fallback 处理的是"外部服务不可靠",今天的错误回传处理的是"模型自己会犯错"——provider 挂了你换一家,模型把参数填错了换谁都一样,只能让它重来。D2 那几个工具"能跑就行",今天要变成"不会崩、崩了能自纠错、外面看得见"。读完回来勾掉三条目标。
小白版讲解
工具地图:格式约束、交叉引用与改名代价
在网店下单你摸不到实物,买不买得对全靠标题和参数表:写"多功能收纳盒",你不知道它装不装得下 A4 纸;写清"内径 32 厘米",你才敢下单。模型挑工具的处境一模一样——这条底线 D2 讲过,今天钉死三处最容易翻车的写法,其中一处 D2 只提过一句,今天给出可操作的做法。
一、格式类字段不给合法示例。 模型对"订单号"三个字没有概念,只能按语感编一个;配一句"例如 SO20260901",是整份定义里投入产出比最高的一行字。再把同一条约束用 pattern 写成正则钉进 schema——它发给模型是说明书,留给下一节的校验器是规则,从同一处长出来就不会漂移。
二、D2 提过"该用/不该用要写清楚",但没说怎么落地——工具间的交叉引用。 描述最值钱的常是负空间。只写"查询订单",模型会拿它去查退款、查物流;补一句"只查订单本身,物流轨迹请用 track_shipment",误用立刻少一大半。工具越多,你写的就越不是一份份说明书,而是一张工具地图。
三、把工具名当成可随手重构的函数名。 名字要像一条命令 D2 说过;没说的是它上线后的性质——工具名是对外契约。
// 工具定义就是提示词的一部分:这段文字会原样进入模型的上下文
export const queryOrder = {
name: 'query_order',
description:
'按订单号查询一笔订单的状态、金额和下单时间。只查订单本身;' +
'物流轨迹请用 track_shipment,退款进度请用 query_refund。',
parameters: {
type: 'object',
properties: {
order_id: {
type: 'string',
description: '订单号,SO 开头加 8 位数字,例如 SO20260901',
pattern: '^SO\\d{8}$',
},
},
required: ['order_id'],
},
}# 工具定义就是提示词的一部分:这段文字会原样进入模型的上下文
QUERY_ORDER = {
"name": "query_order",
"description": (
"按订单号查询一笔订单的状态、金额和下单时间。只查订单本身;"
"物流轨迹请用 track_shipment,退款进度请用 query_refund。"
),
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单号,SO 开头加 8 位数字,例如 SO20260901",
"pattern": r"^SO\d{8}$",
},
},
"required": ["order_id"],
},
}// 依赖:Jackson。schema 用文本块写,省掉手拼 JSON 的转义。
// ToolSpec 一份到底:前三个字段是发给模型的说明书,execute 是本地实现,
// 下一节的 runTool 直接从它取实现,不用再维护一张「名字到函数」的映射表
@FunctionalInterface
interface ToolImpl {
String apply(JsonNode args);
}
record ToolSpec(String name, String description, JsonNode parameters, ToolImpl execute) {}
static final ObjectMapper MAPPER = new ObjectMapper();
static ToolSpec queryOrder() throws JsonProcessingException {
var schema = MAPPER.readTree("""
{
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单号,SO 开头加 8 位数字,例如 SO20260901",
"pattern": "^SO\\\\d{8}$"
}
},
"required": ["order_id"]
}
""");
return new ToolSpec(
"query_order",
"按订单号查询一笔订单的状态、金额和下单时间。只查订单本身;"
+ "物流轨迹请用 track_shipment,退款进度请用 query_refund。",
schema,
args -> queryOrderById(args.get("order_id").asText()));
}// Swift 里把 schema 也做成 Encodable 类型,编译期就能挡住拼错的字段名
struct ParameterSpec: Encodable {
let type: String
let description: String
var pattern: String?
// 整数参数的上下界,D12 的 memory_search 会用到。Encodable 自动跳过 nil,
// 所以给这里加可空字段不会改动已有工具编码出来的 schema
var minimum: Int?
var maximum: Int?
}
// ToolSpec 一份到底:说明书和本地实现挂在同一个类型上,下一节的 runTool 直接取 execute。
// CodingKeys 里没有 execute,所以编码时它会被跳过——只有前三个字段进请求体
struct ToolSpec: Encodable {
let name: String
let description: String
let parameters: ObjectSchema
let execute: ([String: JSONValue]) async -> String
enum CodingKeys: String, CodingKey {
case name, description, parameters
}
struct ObjectSchema: Encodable {
let type = "object"
let properties: [String: ParameterSpec]
let required: [String]
}
}
let queryOrder = ToolSpec(
name: "query_order",
description: """
按订单号查询一笔订单的状态、金额和下单时间。只查订单本身;\
物流轨迹请用 track_shipment,退款进度请用 query_refund。
""",
parameters: .init(
properties: [
"order_id": ParameterSpec(
type: "string",
description: "订单号,SO 开头加 8 位数字,例如 SO20260901",
pattern: "^SO\\d{8}$")
],
required: ["order_id"]),
execute: { args in
guard case .string(let orderID)? = args["order_id"] else { return "缺少 order_id" }
return await queryOrderByID(orderID)
})写清楚是要花钱的,而且按轮次重复付:工具定义每轮都完整重发。按 D2 的口径,一个写扎实的工具约 100 到 150 token,挂 20 个就是每轮两三千的固定开销,十轮对话光定义烧掉两三万。所以只挂当前场景用得上的工具。
到这里说明书算是写扎实了。但再好的说明书也挡不住下一个问题:模型是概率生成参数的,不是编译器,它照样会把订单号写成 12345、金额填成负数。这时候你的工具会怎么样?
面试题库
设计 Agent 的工具时你会遵循哪些原则?名字、描述、参数分别该怎么写?What principles do you follow when designing tools for an agent — how do you write the name, the description and the parameter schema?
国内高频海外高频基础#tool-design#prompt-engineering🔒 解锁本章后查看答题要点。
工具调用报错或参数非法时,你怎么让模型自己纠正而不是直接失败?When a tool call fails validation or errors out, how do you get the model to correct itself instead of failing the whole turn?
国内高频海外高频进阶#tool-calling#error-handling🔒 解锁本章后查看答题要点。
Agent 的事件系统一般会暴露哪些生命周期事件?为什么不能只等最终返回值?Which lifecycle events does an agent runtime typically expose, and why is waiting for the final return value not enough?
国内高频海外高频进阶#event-driven#observability🔒 解锁本章后查看答题要点。
怎么限定工具的权限边界,避免 Agent 越权操作?把规则写进系统提示词够不够?How do you bound an agent's tool permissions, and is putting the rules in the system prompt enough?
国内高频海外高频深入#tool-permissions#security#prompt-injection🔒 解锁本章后查看答题要点。
