把这个工具拆成两个、描述写清楚、返回值砍掉八成,中杯模型的表现就超过了原来大杯的版本。

这不是个例。Agent 能力的天花板,很多时候是工具设计,不是模型。 模型是你换不动的那部分——它由 Anthropic、OpenAI 训练,你只能选型;工具是你完全能控制的那部分。把精力花在能控制的地方,回报率高得多。

Anthropic 在 2026 年那篇《Writing effective tools for AI agents》里有一句话我很认同:工具是一种新的软件形态,它是确定性系统和非确定性 Agent 之间的契约。你不能再按"给另一个程序员写 API"的思路写工具——调用方变了,设计原则就得跟着变。

工具描述:你在跟模型"招标"

模型面对一组工具,做的事情和招标差不多:读每个工具的描述,判断"这个活该派给谁"。描述写得含糊,它就选错;描述之间边界不清,它就来回横跳。

最常见的坏味道是用实现细节代替使用场景。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 反例
{
  "name": "db_query",
  "description": "对主库执行 SQL 查询"
}

# 正例
{
  "name": "search_orders",
  "description": "按用户 ID、时间范围或订单状态查询订单。
                  用于回答'用户买过什么''某笔订单到哪了'这类问题。
                  不要用它查商品库存——那是 search_inventory 的活。"
}

差别在哪?反例描述的是"工具内部怎么干活"(执行 SQL),模型并不关心这个;它关心的是"什么时候该用我"。正例直接给出触发场景,还顺手划清了和邻居工具的边界。

这里有个容易被忽略的点:当你有多个相似工具时,描述里必须明确"我不是谁"。 Anthropic 的建议是用命名空间区分,比如 asana_search 和 jira_search,或者更细的 asana_projects_search、asana_users_search。前缀本身就是一种边界声明。光靠名字还不够时,就在描述里直接写"查 X 用我,查 Y 请用那个工具"。

另一个实战技巧:在描述里塞一两个使用示例。模型在互联网文本里见过的函数,旁边大多带着调用例子,这种格式它最熟。一个 search_orders(user_id="u_123", status="shipped") 的示例,比三行抽象说明管用。2026 年 Anthropic 的 Claude API 干脆把这个能力产品化了,叫 Tool Use Examples——可见示例不是锦上添花,是正经手段。

参数:让模型"填得对",而不是"填得全"

参数设计的核心矛盾是:你想要灵活,模型想要明确。这两者经常打架,而你应该站在模型这边。

第一,别用裸字符串当枚举。 一个 status 参数,如果你在描述里写"传订单状态",模型可能传 "已发货"、"shipped"、"SHIPPED"、"发货中"——四种写法,你的代码能认几种?直接用枚举把可选值锁死:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 反例:status 是 str,模型自由发挥
def search_orders(user_id: str, status: str): ...

# 正例:枚举,模型只能在合法值里选
from enum import Enum
class OrderStatus(str, Enum):
    PENDING = "pending"
    SHIPPED = "shipped"
    DELIVERED = "delivered"
    CANCELLED = "cancelled"

def search_orders(user_id: str, status: OrderStatus | None = None): ...

第二,能有默认值就别让模型填。 每多一个必填参数,就多一个模型出错的机会。分页的 page_size、排序的 order_by,给个合理默认值,模型大多数时候根本不用碰它。

第三,警惕"看起来很像"的参数。 一个工具同时收 start_date 和 end_date,模型偶尔会填反。如果业务允许,合并成一个 time_range 枚举(last_7_days、last_30_days、this_month)往往更稳——你把"理解日期区间"这件事从模型手里拿回来了。当然,需要精确区间时该用两个还得用两个,这是取舍,不是教条。

一个判断标准:如果一个参数,你自己都要想三秒才知道该填什么,模型只会比你更糊涂。

返回值:给模型能用的信息,不是给它一份数据库导出

这是我见过踩坑最多的地方,值得单独讲。

工具的返回值会原封不动进入模型的上下文窗口。这意味着两件事:一是它占 token,占的还是最贵的那部分;二是模型要从里面提取信息做下一步决策。所以返回值的设计目标只有一个——高信噪比。

反例长这样:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "data": [{
    "order_id": "ord_8f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c",
    "tenant_uuid": "tn_a1b2c3d4",
    "created_at_unix": 1747300800,
    "updated_at_unix": 1747387200,
    "row_version": 7,
    "status_code": 2,
    "_internal_flags": { "is_migrated": true, "shard": 3 }
  }]
}

模型看到这个,得自己去想:status_code: 2 是什么意思?created_at_unix 怎么换算成人话?tenant_uuid 要不要在下一步带上?这些都是噪声,而且每一条都是潜在的出错点。

Anthropic 的原则说得很直白:返回人类可读的字段,别返回底层技术标识符。 name、status、created_at(写成可读时间)这种字段能直接指导模型的下一步动作;uuid、mime_type、row_version 不能,它们只是占地方。

正例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "orders": [{
    "id": "ord_8f3a2b1c",
    "status": "shipped",
    "created_at": "2026-05-15 14:00",
    "total": "¥299.00",
    "items_summary": "无线耳机 x1"
  }],
  "total_count": 47,
  "showing": "1-10",
  "hint": "还有 37 条,加 status 或更窄的时间范围可缩小结果"
}

注意最后那个 hint 字段。返回值不只是数据,也是给模型的下一步提示。 当结果太多时,与其返回 47 条把上下文撑爆,不如返回 10 条加一句"还有 37 条,这样筛"。Anthropic 把这类机制叫分页、范围过滤、截断,核心思想一致:别让模型被数据淹没,主动引导它做更窄、更省 token 的查询。

下面这张图是返回值设计的取舍:

flowchart TD
  A[工具拿到原始结果] --> B{结果量大吗?}
  B -->|小| C[直接返回可读字段]
  B -->|大| D[截断 + 分页]
  D --> E[附 hint:怎么缩小范围]
  C --> F[剔除 uuid/时间戳/内部 flag]
  E --> F
  F --> G[进入模型上下文]
  style F fill:#fde7c2,stroke:#e8b23c
  style E fill:#fde7c2,stroke:#e8b23c

橙色那两块——剔除噪声字段和附带引导提示——是最容易省略、又最影响效果的环节。

错误怎么回:错误信息是给模型的"操作手册"

工具调用失败是常态,不是异常。模型填错参数、查的资源不存在、触发了限流——这些每天都在发生。真正决定 Agent 韧性的,是出错之后它能不能自己爬起来。而它能不能爬起来,取决于你的错误信息写成什么样。

反例:

1
2
3

raise ValueError("Invalid input")          # 模型:啥 input?哪儿错了?
return {"error": "ERR_4012"}                 # 模型:4012 是什么我怎么知道
raise Exception(traceback...)                # 模型:吞掉半屏 token,然后还是不知道咋办

这三种回法的共同问题是:模型读完不知道下一步该干什么。 它要么放弃,要么用同样的错参数原样重试,卡进死循环。

好的错误信息要满足一个标准——模型读完就知道怎么改:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 正例:说清错在哪 + 给出可执行的下一步
return {
  "error": "参数 status 的值 '发货中' 不合法",
  "valid_values": ["pending", "shipped", "delivered", "cancelled"],
  "hint": "你可能想用 'shipped'"
}

return {
  "error": "未找到 user_id 'u_999' 对应的用户",
  "hint": "确认 ID 是否正确,或先用 search_users 按用户名查到 ID"
}

Anthropic 的说法是:你可以对错误信息做提示工程,把它写成清晰、可执行的改进建议,而不是不透明的错误码或堆栈。一条好的错误信息会顺手告诉模型"下一步该调哪个工具"——上面那个 search_users 的提示就是。这等于把错误信息也当成了引导模型的一个入口。

还有个常被忽略的点:错误也要省 token。 别把整个 Python traceback 塞回去,那几百个 token 对模型几乎没有信息价值。给一句人话就够了。

工具粒度:太细太粗都不行

最后一个,也是最难的——工具切多大。

切太细的坑。 把 get_user、get_user_orders、get_order_detail 拆成三个独立工具,听起来很"单一职责"。但 Agent 要回答"用户最近这单到哪了",得连着调三次:第一次拿 user,第二次拿 order 列表,第三次拿 detail。三次往返,三段返回值堆进上下文,任何一步选错都得重来。工具太细,模型就被迫去干编排的活,而编排正是它最容易出错的地方。

切太粗的坑。 反过来做一个万能的 manage_order,靠一个 action 参数切换"查询/创建/退款/改地址"。模型每次都要先想清楚 action 填什么、对应又该带哪些参数,描述也长得没法读。而且一个工具权限太大,审计和兜底都难做——你没法只给某个 Agent “查询"权限而不给"退款"权限。

我的经验法则是:按"用户意图"切,不按"数据库表"切,也不按"一个超级动作"切。

判断方法很简单:想象一个真实的用户问题,数一数 Agent 要调几次工具才能答上。 如果一个常见问题要调四五次,你的工具大概率切太细了;如果一个工具的描述你得写满一屏才说得清,那它八成切太粗了。

Anthropic 反复强调的"evaluation-driven development"在这里特别管用:先拿真实任务跑一批评测,看 Agent 卡在哪、绕了多少弯路,再回头调工具的粒度。工具设计不是一次写对的,是测出来、改出来的。

几条收尾的话

把上面的拆开看是五个话题,合起来其实是一个视角的转变:你不是在给程序写接口,你是在给一个会读字、会犯错、上下文有限的"实习生"写操作手册。

落到日常,优先级我会这么排:

1. 先治返回值。 砍掉 uuid、时间戳、内部 flag,只留可读字段。这一步零成本,收益立竿见影。
2. 再治错误信息。 把每条错误都改成"说清错在哪 + 下一步怎么办”。Agent 的韧性主要靠这个。
3. 然后理顺粒度。 按意图切,用真实任务量一量调用次数。
4. 最后打磨描述和参数。 加示例、上枚举、给默认值。

别一上来就盯着换模型。先把你能 100% 控制的那部分——工具——做扎实了,再去谈模型选型。很多时候,中杯配一组好工具,比大杯配一组烂工具跑得稳得多,还便宜。

参考资料

• Writing effective tools for AI agents — Anthropic Engineering
• Introducing advanced tool use on the Claude Developer Platform — Anthropic
• Effective context engineering for AI agents — Anthropic
• Writing Effective Tools for Agents: Complete MCP Development Guide

三天后告警响了。某条响应里,LLM 在 JSON 后面多写了一句"希望这个分析对你有帮助!"。你的 json.loads() 当场抛异常,整条链路挂掉。

这不是小概率事件,是结构性问题。只要你还在用"自由文本里夹一段 JSON"的方式跟 LLM 要数据,这种崩溃就是迟早的——区别只是它发生在测试环境还是生产环境。

这篇讲清楚:为什么自由文本提 JSON 天生不可靠,2026 年有哪几种正经方案、各自的代价是什么,schema 怎么设计才不坑自己,以及最难的那块——流式场景下怎么拿到结构化数据。

为什么"让它输出 JSON"本身就是错的

先理解 LLM 在干什么。它做的是一件事:根据前面所有 token,预测下一个 token 的概率分布,然后采样。它没有“我现在要写一个合法 JSON"这种全局意识。

所以当你在 prompt 里写"请只返回 JSON,不要有多余文字”,你是在用一句话,对抗模型训练数据里成千上万条"先解释再给结果"的对话样本。大多数时候它听话,因为你的指令把概率压过去了。但只要某次采样,在该写 } 的位置,“希望"这个 token 的概率偶然爬到了第一,它就会写下去——而且一旦写下去,后面就会顺着"希望这个分析对你有帮助"这条最自然的路径滑下去。

常见的失败长这样:

• JSON 外面套了 ```json 代码块,或者前后有一段自然语言
• 字符串里有没转义的换行、引号
• 该是数字的字段写成了 "4.5"(带引号),或者写成 4.5分
• 嵌套对象少了一个括号,尤其是输出很长的时候
• 枚举字段返回了你没定义的值——你要 positive/negative/neutral,它给你个 mixed

这些都不是模型"笨”,是概率采样的必然结果。你不可能靠把 prompt 写得更恳切来根治它,你只能降低概率,没法归零。要归零,得换思路:不是请求它输出合法结构,而是从机制上让它没法输出不合法的结构。

五种方案,以及它们各自的代价

2026 年,从最弱到最强,实际可用的方案是这五种。关键不是"哪个最好",是搞清楚每个的边界。

flowchart TB
  A["LLM 要输出结构化数据"] --> B{"模型在哪?"}
  B -->|"闭源 API"| C{"要不要 100% 保证 schema?"}
  B -->|"自己部署的开源模型"| D["约束解码
xgrammar / llguidance"]
  C -->|"要"| E["Structured Outputs / strict 工具"]
  C -->|"差不多就行"| F["JSON Mode（已是 legacy）"]
  E --> G["拿到必定合法的 JSON"]
  D --> G
  F --> H["只保证语法合法，schema 靠运气"]
  style E fill:#fde7c2,stroke:#e8b23c
  style D fill:#fde7c2,stroke:#e8b23c

1. 纯 prompt 约束。 就是开头那种"请只返回 JSON"。它的唯一价值是当作其他方案的补充——把字段含义、示例写清楚能提升内容质量。但别拿它当结构保证。如果你现在生产环境还在裸用这个,这篇文章后面的部分就是为你写的。

2. JSON Mode。 OpenAI 最早的尝试,response_format: {"type": "json_object"}。它保证一件事:输出是语法合法的 JSON——不会有代码块包裹,不会有多余文字,括号配对。但它不管 schema:字段名、字段类型、枚举值、必填项,一概不保证。所以你还是得做完整校验。2026 年它基本算 legacy 了,OpenAI 自己的文档也把它标成旧特性,纯 JSON Mode 在生产里早就没人用了。

3. 约束解码 / Grammar(constrained decoding)。 这是真正解决问题的机制,也是后面几种方案底层共用的东西。原理:在每一步采样时,根据"目前已经生成的部分 + 目标 schema",算出下一个 token 哪些是合法的,把所有非法 token 的概率直接屏蔽(mask 成负无穷),只在合法集合里采样。

举例:已经生成到 {"rating":,那么下一个 token 只能是数字、-、空格——模型这一步根本采样不到 " 或者字母。它不是"被劝住了",是那条路被物理封死了。

开源世界里这块 2026 年很成熟。xgrammar 是目前 vLLM、SGLang、TensorRT-LLM 的默认结构化生成后端,支持完整的上下文无关文法(JSON、正则、自定义 CFG),每 token 开销做到了 40 微秒以下,几乎不影响吞吐;llguidance 是另一个主力,OpenAI 2025 年公开说过自家实现的底层借鉴了它。早期的 outlines 用有限状态机思路,开了这个方向,但碰到递归 schema(比如树形结构、嵌套评论)会很吃力,编译能慢到几十秒甚至几分钟,递归类结构现在更推荐用 xgrammar、llguidance 这种 CFG 引擎。

4. Structured Outputs API。 这是闭源厂商把约束解码包装成的产品功能。OpenAI 的 response_format: {"type": "json_schema", strict: true} 就是它——你传一个 JSON Schema,模型底层用约束解码,输出必定符合 schema:每个必填字段都在、类型都对、枚举值都合法。可用模型是 gpt-4o-2024-08-06 之后的版本、GPT-4.1 全系、GPT-5 和 o 系列。2026 年它是数据抽取、Agent 场景的生产默认。

5. Function Calling / Tool Use。 你定义工具,带 input schema,模型返回一个符合 schema 的工具调用。本质上跟 Structured Outputs 是同一套约束解码机制,只是包装成了"调用工具"的语义。它适合两类场景:一是模型真的要去调外部 API;二是你给了多个工具让模型自己选(多 Agent、路由)。Anthropic 的 Claude 走的就是 tool use 这条路,且复杂嵌套 schema 下也很稳;Gemini 这边把 JSON 模式和结构化输出合并成了一个特性。

一句话总结取舍:

选型其实很简单:自己部署模型,上 xgrammar;用闭源 API 且只想要一段数据,用 Structured Outputs;用闭源 API 且模型要决策调哪个工具,用 Function Calling。剩下两个,知道它们存在就行。

schema 设计:决定成败的地方往往不是代码

很多人以为开了 Structured Outputs 就万事大吉了。不是。约束解码保证模型输出符合你的 schema,但如果你的 schema 设计得烂,模型会在"合法"的范围内给你垃圾。

几条我踩过坑后总结的硬规则:

用枚举,别用开放字符串。 情感字段写成 "sentiment": string 模型可能给你 非常正面、positive、POSITIVE 三种花样。写成 enum: ["positive", "negative", "neutral"],约束解码会保证它只能落在这三个里。能枚举的一律枚举。

给每个字段写 description。 schema 里的 description 不是注释,模型会读。"score" 含糊,"score: 1-5 整数,5 表示强烈推荐,严格保守打分" 就清楚得多。约束解码管类型,不管"打分准不准",后者靠 description。

注意 strict 模式的限制。 OpenAI 的 strict 模式有几条硬约束容易绊人:所有字段都必须列进 required(想要可选字段,得把类型写成联合类型带 null);不支持任意的 dict[str, Any],key 不确定的字典它接不了;日期时间得用 ISO 字符串表示。设计前先翻一遍文档的限制清单,别等运行时报错。

给模型一条"我不知道"的出路。 这条最容易被忽略。如果信息缺失,你又强迫模型必须填某个字段,约束解码会逼它编一个——它在合法 token 里硬凑,于是你拿到一个格式完美的幻觉。正确做法是显式留口子:加 confidence 字段,或者让关键字段可空,或者加一个 "status": ["ok", "insufficient_info"]。结构合法不等于内容可信,这是约束解码救不了你的部分。

别一次榨太多。 一个 schema 里塞二十个字段,还层层嵌套,模型质量会肉眼可见地掉。能拆成两次调用就拆。

出错了怎么兜底

上了 Structured Outputs,JSON 解析层面的错确实没了。但还有别的会出问题,得有兜底。

第一类,API 层面的失败:超时、限流、网络抖动。这跟结构化无关,但既然你依赖一个必定返回结构的接口,它一旦不返回,你的下游就断了。退避重试,该做做。

第二类,约束解码碰上 token 上限。约束解码保证"如果生成完成,结构一定合法",但它不保证一定能生成完成。如果 max_tokens 设小了,模型在一个深层嵌套里被强行截断,你拿到的是一段合法但不完整的 JSON。对策:嵌套深、字段多的 schema,把 max_tokens 给足;并且检查 finish reason 是不是 length,是的话当失败处理。

第三类,内容兜底——前面说的幻觉。schema 里留了 confidence 或 status,这里就要用上:低于阈值的结果不直接进库,转人工或走降级逻辑。

一个实战习惯:就算用了 Structured Outputs,落库前也做一次业务校验。 不是不信约束解码,是 schema 只能表达"类型和结构",表达不了"评分必须在 1 到 5 之间且这条订单的金额不能是负数"这种业务约束。两层防线:schema 管结构,代码管语义。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 闭源 API:Structured Outputs 保证结构,代码补业务校验
resp = client.chat.completions.create(
    model="gpt-4.1",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "review", "strict": True, "schema": SCHEMA},
    },
    max_tokens=800,
)
if resp.choices[0].finish_reason == "length":
    raise TruncatedError("被 token 上限截断,当失败重试")

data = json.loads(resp.choices[0].message.content)  # 这里几乎不会再抛
validate_business_rules(data)  # 评分范围、字段间一致性等,schema 管不到

流式场景:最难啃的一块

到这里都还好。真正难的是这个:你要流式输出,同时要结构化数据。

比如一个 UI,要边生成边把解析结果填进表单——名字一出来就显示名字,地址一出来就显示地址。但 LLM 是一个 token 一个 token 吐的,而 JSON 的任何中间状态都是语法非法的:

flowchart LR
  T1["{"] --> T2["{\"name\""] --> T3["{\"name\":\"张"] --> T4["{\"name\":\"张三\"}"]
  T1 -.->|"json.loads"| X1["报错"]
  T2 -.->|"json.loads"| X2["报错"]
  T3 -.->|"json.loads"| X3["报错"]
  T4 -.->|"json.loads"| OK["成功"]
  style X1 fill:#f8d7da,stroke:#c33
  style X2 fill:#f8d7da,stroke:#c33
  style X3 fill:#f8d7da,stroke:#c33
  style OK fill:#d4edda,stroke:#3a3

你不能等整段 JSON 攒齐——那就退化成非流式,流式的意义没了。也不能拿 json.loads() 去解每个中间态——它每次都抛异常。

可行的有两条路:

一是分隔符切块。 别要一个大 JSON,让模型按 JSON Lines 输出——每行一个独立的小对象,中间用换行分隔。每收到一个完整换行,就解析这一行。这等于把"一个大结构"拆成"很多个小结构",每个小结构一旦完整就立刻可用。简单、稳,适合"一批结果"型的输出。

二是容错增量解析。 用一个能处理残缺 JSON 的解析器,把每个中间态尽力补全成一个带类型的部分对象——{"name":"张 直接解析成 {name: "张"},字段还没出现的就当缺失。这条路上 2026 年比较成熟的是 BAML 这类工具,它内置了一个容错 parser,专门把破碎的部分 JSON 实时转成带类型的对象,既保住流式的体验,又拿到渐进的结构化数据。

选哪条:输出是"一组同类项",用 JSON Lines;输出是"一个有很多字段的大对象",且 UI 要逐字段渐进填充,用容错增量解析。

还有个常被忽略的点:流式 + 约束解码可以同时用。约束解码是逐 token 工作的,本来就和流式天然兼容——vLLM 这类引擎流式吐 token 的同时,xgrammar 在每一步做 mask。所以"用了约束解码就不能流式"是个误解,两者是正交的。难的从来不是生成端,是消费端怎么解析这些中间态。

最后:把它当工程问题,别当 prompt 问题

如果只留一句话:结构化输出的可靠性,不该靠 prompt 写得好,该靠机制保证。

很多团队卡在"再调调 prompt 让它别输出多余文字"。这是把一个工程问题误当成了文案问题。prompt 能把失败率从 5% 压到 0.5%,但压不到 0;而约束解码这类机制能压到 0。你的优先级应该是:

1. 先换机制——自部署上 xgrammar,用 API 上 Structured Outputs 或 Function Calling。这一步把"JSON 语法错"和"schema 不符"两类问题直接归零,收益最大。
2. 再认真设计 schema——枚举、description、给"不知道"留出路。约束解码管不到的内容质量,靠这一步。
3. 最后补业务校验和流式兜底——schema 管结构,代码管语义;流式场景按数据形态选 JSON Lines 或容错解析。

机制定了下限,prompt 和 schema 决定上限。顺序别搞反。

参考: OpenAI Structured Outputs 文档、 Introducing Structured Outputs in the API、 xgrammar、 llguidance、 Structured Outputs in vLLM、 Streaming structured data from LLMs is harder than you think、 When should I use function calling, structured outputs or JSON mode