结构化输出

结构化输出将 Claude 的响应限制为遵循特定模式，确保为下游处理提供有效的、可解析的输出。提供两种互补功能：

• JSON 输出 (output_config.format)：以特定 JSON 格式获取 Claude 的响应
• 严格工具使用 (strict: true)：保证对工具名称和输入进行模式验证

这些功能可以独立使用，也可以在同一请求中一起使用。

为什么使用结构化输出

如果不使用结构化输出，Claude 可能会生成格式错误的 JSON 响应或无效的工具输入，从而破坏您的应用程序。即使经过仔细的提示，您也可能遇到：

• 由于无效 JSON 语法导致的解析错误
• 缺少必填字段
• 数据类型不一致
• 需要错误处理和重试的模式违规

结构化输出通过受约束的解码来保证符合模式的响应：

• 始终有效：不再出现 JSON.parse() 错误
• 类型安全：保证字段类型和必填字段
• 可靠：无需因模式违规而重试

JSON 输出

JSON 输出控制 Claude 的响应格式，确保 Claude 返回与您的模式匹配的有效 JSON。在以下情况下使用 JSON 输出：

• 控制 Claude 的响应格式
• 从图像或文本中提取数据
• 生成结构化报告
• 格式化 API 响应

快速开始

响应格式： 在 response.content[0].text 中返回与您的模式匹配的有效 JSON

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

工作原理

在 SDK 中使用 JSON 输出

SDK 提供了辅助工具，使处理 JSON 输出更加便捷，包括模式转换、自动验证以及与流行模式库的集成。

使用原生模式定义

您可以使用语言中熟悉的模式定义工具，而无需编写原始 JSON 模式：

• Python：使用 client.messages.parse() 的 Pydantic 模型
• TypeScript：使用 zodOutputFormat() 的 Zod 模式
• Java：通过 outputFormat(Class<T>) 自动派生模式的普通 Java 类
• Ruby：使用 output_config: {format: Model} 的 Anthropic::BaseModel 类
• C#、Go、PHP：通过 output_config 传递的原始 JSON 模式

SDK 特定方法

每个 SDK 都提供了辅助工具，使处理结构化输出更加便捷。请参阅各 SDK 页面了解完整详情。

SDK 转换的工作原理

Python 和 TypeScript SDK 自动转换具有不支持功能的模式：

1. 删除不支持的约束（例如，minimum、maximum、minLength、maxLength）
2. 更新描述，包含约束信息（例如，"必须至少为 100"），当约束不直接受结构化输出支持时
3. 为所有对象添加 additionalProperties: false
4. 过滤字符串格式，仅保留支持的列表
5. 根据原始模式验证响应（包含所有约束）

这意味着 Claude 接收简化的模式，但您的代码仍通过验证强制执行所有约束。

示例： 带有 minimum: 100 的 Pydantic 字段在发送的模式中变为普通整数，但描述更新为"必须至少为 100"，SDK 根据原始约束验证响应。

常见用例

严格工具使用

严格工具使用验证工具参数，确保 Claude 使用正确类型的参数调用您的函数。在以下情况下使用严格工具使用：

• 验证工具参数
• 构建智能体工作流
• 确保类型安全的函数调用
• 处理具有嵌套属性的复杂工具

为什么严格工具使用对智能体很重要

构建可靠的智能体系统需要保证模式一致性。没有严格模式，Claude 可能返回不兼容的类型（"2" 而不是 2）或缺少必需字段，从而破坏您的函数并导致运行时错误。

严格工具使用保证类型安全的参数：

• 函数每次都接收正确类型的参数
• 无需验证和重试工具调用
• 可在规模化生产中稳定运行的智能体

例如，假设预订系统需要 passengers: int。没有严格模式，Claude 可能提供 passengers: "two" 或 passengers: "2"。使用 strict: true，响应将始终包含 passengers: 2。

快速开始

响应格式： 工具使用块，其中验证后的输入位于 response.content[x].input

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

保证：

• 工具 input 严格遵循 input_schema
• 工具 name 始终有效（来自提供的工具或服务器工具）

工作原理

常见使用场景

同时使用两个功能

JSON 输出和严格工具使用解决不同的问题，可以一起使用：

• JSON 输出控制 Claude 的响应格式（Claude 说什么）
• 严格工具使用验证工具参数（Claude 如何调用您的函数）

结合使用时，Claude 可以使用有保障的有效参数调用工具，并返回结构化的 JSON 响应。这对于需要可靠工具调用和结构化最终输出的智能体工作流非常有用。

重要注意事项

语法编译与缓存

结构化输出使用带有已编译语法构件的约束采样。这引入了一些需要注意的性能特性：

• 首次请求延迟：首次使用特定 schema 时，语法编译期间会有额外延迟
• 自动缓存：已编译的语法会从最后一次使用起缓存 24 小时，使后续请求速度大幅提升
• 缓存失效：如果您更改以下内容，缓存将失效：
  • JSON schema 结构
  • 请求中的工具集（同时使用结构化输出和工具使用时）
  • 仅更改 name 或 description 字段不会使缓存失效

提示词修改与 token 成本

使用结构化输出时，Claude 会自动收到一个额外的系统提示，说明预期的输出格式。这意味着：

• 您的输入 token 数量会略有增加
• 注入的提示词像其他系统提示一样消耗 token
• 更改 output_config.format 参数将使该对话线程的任何提示词缓存失效

JSON Schema 限制

结构化输出支持标准 JSON Schema，但有一些限制。JSON 输出和严格工具使用共享这些限制。

属性排序

使用结构化输出时，对象中的属性会保持 schema 中定义的顺序，但有一个重要注意事项：必填属性排在前面，可选属性排在后面。

例如，给定以下 schema：

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

输出将按以下顺序排列属性：

1. name（必填，按 schema 顺序）
2. email（必填，按 schema 顺序）
3. notes（可选，按 schema 顺序）
4. age（可选，按 schema 顺序）

这意味着输出可能如下所示：

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

如果输出中的属性顺序对您的应用程序很重要，请确保所有属性都标记为必填，或在解析逻辑中考虑这种重新排序。

无效输出

虽然结构化输出在大多数情况下保证符合 schema，但在某些情况下输出可能与您的 schema 不匹配：

拒绝（stop_reason: "refusal"）

即使使用结构化输出，Claude 也会保持其安全性和有用性属性。如果 Claude 出于安全原因拒绝请求：

• 响应将具有 stop_reason: "refusal"
• 您将收到 200 状态码
• 您将为生成的 token 付费
• 输出可能与您的 schema 不匹配，因为拒绝消息优先于 schema 约束

达到 token 限制（stop_reason: "max_tokens"）

如果响应因达到 max_tokens 限制而被截断：

• 响应将具有 stop_reason: "max_tokens"
• 输出可能不完整且与您的 schema 不匹配
• 使用更高的 max_tokens 值重试以获取完整的结构化输出

Schema 复杂度限制

结构化输出通过将您的 JSON schema 编译成约束 Claude 输出的语法来工作。更复杂的 schema 会产生更大的语法，编译时间更长。为了防止过长的编译时间，API 强制执行多个复杂度限制。

明确限制

以下限制适用于所有带有 output_config.format 或 strict: true 的请求：

额外的内部限制

除上述明确限制外，还有对已编译语法大小的额外内部限制。这些限制的存在是因为 schema 复杂度不能简化为单一维度：可选参数、联合类型、嵌套对象和工具数量等功能相互作用，可能使已编译的语法变得不成比例地大。

当超出这些限制时，您将收到带有消息"Schema is too complex for compilation"的 400 错误。这些错误意味着您的 schema 的组合复杂度超出了可以有效编译的范围，即使上述每个单独的限制都满足。作为最后的保障，API 还强制执行 180 秒的编译超时。通过所有明确检查但产生非常大的已编译语法的 schema 可能会触发此超时。

降低 schema 复杂度的技巧

如果您遇到复杂度限制，请按顺序尝试以下策略：

1. 仅将关键工具标记为严格。 如果您有许多工具，请将其保留给 schema 违规会导致真正问题的工具，并依赖 Claude 对更简单工具的自然遵从。

2. 减少可选参数。 尽可能将参数设为 required。每个可选参数大约会使语法状态空间的一部分翻倍。如果参数始终有合理的默认值，请考虑将其设为必填，并让 Claude 明确提供该默认值。

3. 简化嵌套结构。 具有可选字段的深度嵌套对象会加剧复杂度。尽可能扁平化结构。

4. 拆分为多个请求。 如果您有许多严格工具，请考虑将它们拆分到单独的请求或子智能体中。

对于有效 schema 的持续问题，请联系支持并提供您的 schema 定义。

数据保留

使用结构化输出时，提示词和响应通过 ZDR 处理。但是，JSON schema 本身会从最后一次使用起临时缓存最多 24 小时，用于优化目的。API 响应之外不会保留任何提示词或响应数据。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

功能兼容性

兼容：

• 批处理：以 50% 的折扣大规模处理结构化输出
• Token 计数：无需编译即可计算 token
• 流式传输：像普通响应一样流式传输结构化输出
• 组合使用：在同一请求中同时使用 JSON 输出（output_config.format）和严格工具使用（strict: true）

不兼容：

• 引用：引用需要将引用块与文本交错，这与严格的 JSON schema 约束冲突。如果在 output_config.format 中启用引用，则返回 400 错误。
• 消息预填充：与 JSON 输出不兼容