040、StructuredOutput 结构化输出：让子代理返回 JSON Schema 验证的数据

040、StructuredOutput 结构化输出：让子代理返回 JSON Schema 验证的数据

从一次凌晨的告警说起

凌晨两点，PagerDuty 把我从床上拽起来。看了一眼告警内容：生产环境某个子代理返回的数据格式异常，导致下游的聚合服务直接崩溃。我打开日志，发现那个子代理本该返回一个包含name、age、email三个字段的 JSON，结果它返回了{"name": "张三", "age": "不详", "contact": "138xxxx"}。

这种问题在 AI Agent 系统里太常见了。LLM 天生就是“自由灵魂”，你让它输出 JSON，它可能给你加个字段、改个字段名、甚至直接输出一段 Markdown。在单 Agent 场景下还能容忍，但在多 Agent 协作的工程化系统里，一个子代理的输出格式不规范，整个链路就会像多米诺骨牌一样倒下。

为什么需要结构化输出

先别急着上代码，想清楚一个问题：我们为什么需要结构化输出？

在 Claude Code 的多 Agent 架构里，子代理不是给人看的，是给其他 Agent 或下游服务消费的。Agent 之间通过消息传递数据，如果消息格式不统一，解析逻辑就会变得极其脆弱。你不可能在每个消费方都写一套“智能解析”逻辑——那是在给系统埋雷。

我见过最离谱的做法是在下游 Agent