做 Agent 的人迟早会遇到同一个尴尬：模型回答得头头是道，可输出是一大段自由文本，下游脚本想解析、想入库、想对接 API，全都无从下手。结构化输出，就是把「模型说的」变成「机器能用的」——这是 Agent 从演示走向生产的第一道坎。
这篇把结构化输出讲透：为什么需要它、三种主流实现路径、双层校验与重试怎么搭、常见坑有哪些，最后给一张可以直接抄的落地清单。
先搞清楚：结构化输出为什么决定 Agent 能不能被接住
Agent 不是给人看的聊天框，它的输出要喂给下一环节：入库（数据库写入）、触发工作流、调用 API、生成报表。这一环要求的是「机器能消费的格式」——字段名固定、类型正确、结构可解析。
输出格式一乱，整条链路就断：解析直接失败、字段错位、更危险的是静默出错——解析器容错太强，把错字段当对的用，数据悄悄就脏了。这也解释了为什么评测要盯着输出质量：AI Agent 评测怎么做 里，结构化输出达标率本身就是核心指标之一。模型自由发挥的文本，本质和幻觉是同一类问题——模型不承诺格式，就没人能保证下游正确（AI Agent 幻觉怎么治）。
路径一：提示词约束 + 解析器（轻量方案）
最简单的做法：在提示词里写清楚「只输出 JSON，不要任何其他文字，格式如下」，然后配合解析器兜底——先试 json.loads，失败就提取代码块、修常见错误再试。
优点：零依赖、实现快，几行代码就能跑。缺点：模型不保证遵守，偶尔夹带说明文字，字段类型也可能不按约定来，解析失败只能靠重试硬扛。适合内部工具、低风险场景、快速原型——先跑通再升级。
路径二：JSON Schema 强制（主流方案）
主流模型 API（OpenAI Structured Outputs、Anthropic 等）都支持声明式 schema 约束：字段名、类型、是否必填、枚举值、嵌套结构，一次说清。模型输出时会被「架构级」保证是合法 JSON、字段类型正确——从「求它听话」变成「结构上保证」。
能约束的包括：必填字段（required）、枚举（enum）、数组与嵌套对象、类型（string/number/boolean）。但必须记住一条边界：schema 保证形式合法，不保证内容正确——模型照样可能把「北京」填进「城市」字段，把数字填错位。格式靠 schema，内容靠校验，两层都不能省。
路径三：工具调用（Tool Use）当输出通道
第三种做法是把「返回结果」声明成一个工具函数，让模型通过函数参数输出。模型本来就会调用工具，把「交结果」也变成一次工具调用，输出天然带 schema、不容易跑偏、还支持多次调用。
这条路径特别适合多 Agent 场景：子代理干完活，用「交结果」工具把结构化成果传给主代理，主代理不用猜格式。这和 OpenClaw 多 Agent 配置 里「结果聚合先约定输出格式」是同一个思路——格式在交接点定死，后面才不会乱。
校验与重试：结构合法只是及格线
结构合法不等于能用，要上双层校验：
第一层 schema 校验——用 jsonschema 之类的库检查字段、类型、必填，不过就重试。第二层语义校验——字段值域、关联关系（比如「状态=完成」必须带「完成时间」）、长度上限、枚举之外的自定义规则。语义校验是防「内容错误」的关键，也是幻觉治理的落地动作（模型一本正经胡说八道 的输出，很多能在语义校验这层拦下来）。
重试策略：最多 3 次，每次把具体的校验错误反馈给模型让它改；还不行就按 失败升级规则 走——转人工或者降级方案。这套「输出 → 校验 → 反馈 → 重试 → 升级」的链路，本质就是给 Agent 的输出加了一道 质量门禁，只不过门禁管的是格式和数据正确性。
常见坑与排查
JSON 被截断：长输出撞上 token 上限，括号不闭合。解法：schema 强制 + 输出分块，别让模型一次吐太长的结构。
转义问题：换行、引号、特殊字符被吞。解法：统一用 JSON 序列化，别手拼字符串。
嵌套过深：schema 设计得太复杂，模型犯错率直线上升。解法：保持扁平，一层不行就拆字段。
幻觉字段：模型输出 schema 里没有的字段。解法：校验时严格拒收多余字段，宁可报错不要猜。
静默出错：解析器容错太强，把错字段当对的用。解法：解析失败就明确报错重试，别自作聪明地猜——猜错的成本永远比报错高。
落地清单与适合人群
给一张自查清单：输出格式是否统一声明（不要每处提示词各写各的）；是否双层校验（schema + 语义）；是否有重试和升级机制；是否拒收多余字段；关键输出是否留了 证据包（原始输出 + 校验结果存档，出问题可回溯）。
最值得投入的是要对接系统的场景：数据管道、自动化流程、Agent 之间协作、评测集构建。纯聊天、给人看答案的场景不必强上——为结构化而结构化，反而增加复杂度和失败率。判断标准就一句：你的 Agent 输出要进机器，就一定要结构化；只给人看，宽松点无妨。
总结
结构化输出不是「让模型输出 JSON」，而是「让 Agent 的输出可被程序信任」。三件事：形式靠 schema 保证（合法 JSON）、内容靠校验保证（语义正确）、失败靠重试和升级兜底。把这条链路建好，Agent 才能从「能聊」变成「能用」——这是所有 Agent 工程的地基之一，值得一次建到位。
