Claude Platform Docs
Messages模型能力

结构化输出

从智能体工作流中获取经过验证的 JSON 结果

“Structured outputs”(结构化输出)会约束 Claude 的响应遵循特定的 schema,确保输出有效且可解析,便于下游处理。结构化输出提供两个互补的功能:

  • JSON 输出(output_config.format):以特定的 JSON 格式获取 Claude 的响应,例如从图像或文本中提取数据、生成结构化报告或格式化 API 响应。本页介绍 JSON 输出。
  • 严格工具使用(strict: true):保证对工具名称和输入进行 schema 验证。请参阅严格工具使用。

您可以单独使用这些功能,也可以在同一请求中一起使用。

为什么使用结构化输出

如果不使用结构化输出,Claude 可能会生成格式错误的 JSON 响应或无效的工具输入,从而导致您的应用程序出错。即使经过精心设计提示,您仍可能遇到:

  • 因 JSON 语法无效导致的解析错误
  • 缺少必填字段
  • 数据类型不一致
  • 违反 schema,需要进行错误处理和重试

结构化输出通过"constrained decoding"(约束解码)保证响应符合 schema:

  • 始终有效:不再出现 JSON 解析错误
  • 类型安全:保证字段类型和必填字段
  • 可靠:无需因违反 schema 而重试

工作原理

  1. 定义您的 schema

    以 JSON schema 或您所用语言中的类型来描述您想要的结构。该 schema 遵循 JSON Schema,但有一些限制。

  2. 在 output_config.format 中发送

    请求在 output_config.format 中携带 schema,并设置 type: "json_schema"。SDK 辅助工具会为您完成此设置。

  3. 读取响应

    Claude 会在响应的文本内容块中返回与您的 schema 匹配的有效 JSON。SDK 辅助工具会将其解析为您的类型。

用法

from pydantic import BaseModel



class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

将 Pydantic 模型作为 output_format 传递给推荐的方法 client.messages.parse()。SDK 会转换该模型的 schema,将其作为 output_config.format 发送,验证响应,并在 parsed_output 中返回解析后的模型。

上述示例输出:

Output
name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

如果您知道某个字段的键,请使用嵌套的 Pydantic 模型,而不是 dict。SDK 会将 dict 字段作为 properties 为空的对象发送,因此 Claude 只能为其返回 {}。如果您事先不知道有哪些键,请参阅具有任意键的对象。

SDK 转换的工作原理

大多数 SDK 辅助工具会转换使用了不受支持功能的 schema。转换步骤如下:

  1. 移除不受支持的约束(例如 minimum、maximum、minLength、maxLength)
  2. 更新描述,将每个不受支持的约束添加到字段的描述中(例如 {minimum: 100})
  3. 为所有对象添加 additionalProperties: false
  4. 过滤字符串格式,仅保留受支持的列表
  5. 如果辅助工具会验证响应,则根据您的原始 schema 及其所有约束验证响应

Claude 收到的是简化后的 schema,但会验证响应的辅助工具仍会在您的代码中强制执行每一项约束。

示例:带有 minimum: 100 的字段在发送的 schema 中会变为普通整数,SDK 会将 {minimum: 100} 添加到该字段的描述中。会验证响应的辅助工具仍会根据 minimum: 100 检查响应。

使用原始 JSON schema

要使用来自文件、OpenAPI 规范或在运行时构建它的代码中的 JSON schema,请将其传递到 output_config.format 中。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

上述示例输出:

Output
{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

要将 API 不支持的约束移入字段描述,请在发送之前将 schema 传入 anthropic 包中的 transform_schema(),并根据需要编辑结果。transform_schema() 也接受 Pydantic 模型。与 client.messages.parse() 不同,它返回转换后的 schema,而不是将其发送。

常见用例

严格工具使用

要通过语法约束采样对工具输入强制执行 JSON Schema 合规性,请参阅严格工具使用。

同时使用两种功能

JSON 输出和严格工具使用解决的是不同的问题,并且可以协同工作:

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

两者结合使用时,Claude 可以使用保证有效的参数调用工具,同时返回结构化的 JSON 响应。这对于既需要可靠的工具调用又需要结构化最终输出的智能体工作流非常有用。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON 输出:结构化响应格式
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # 严格工具使用:保证工具参数符合规范
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

重要注意事项

语法编译与缓存

结构化输出使用带有已编译语法工件的约束采样。这会带来一些需要注意的性能特征:

  • 首次请求延迟:首次使用特定 schema 时,编译语法会带来额外的"latency"(延迟)。
  • 自动缓存:已编译的语法会在最后一次使用后缓存 24 小时,从而使后续请求快得多。
  • 缓存失效:如果您更改了 JSON schema 结构,或者在同时使用结构化输出和工具使用时更改了请求中的工具集,缓存就会失效。仅更改 name 或 description 字段不会使缓存失效。

提示修改与令牌成本

使用结构化输出时,Claude 会自动收到一个额外的"system prompt"(系统提示),用于说明预期的输出格式。这意味着:

  • 您的输入令牌数会略有增加。
  • 注入的提示会像其他系统提示一样消耗令牌。
  • 更改 output_config.format 参数会使该对话线程的所有提示缓存失效。

JSON Schema 限制

结构化输出支持标准 JSON Schema,但有一些限制。JSON 输出和严格工具使用都受这些限制约束。

具有任意键的对象

请列出对象的每个键,可以在 properties 中列出,也可以作为您传递给 SDK 的类或 schema 的字段列出。由于 additionalProperties 必须为 false,Claude 只能返回您列出的键。

API 会接受 properties 为空或缺失的对象,但 Claude 只能为其返回 {}。map、字典或 record 类型不会列出任何键,因此 Python 和 TypeScript SDK 会将其作为 properties 为空的对象发送。Java 和 Ruby SDK 则会引发错误。

如果您事先不知道有哪些键,请改用数组。为每个元素提供 key 和 value,如以下 schema 所示:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}

属性顺序

使用结构化输出时,对象中的属性会保持您在 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": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

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

无效输出

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

拒绝(stop_reason: "refusal")

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

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

要求提供模型思考过程或逐步推理的属性可能会导致 reasoning_extraction 拒绝。请改为要求提供简短的解释。请参阅将推理保留在思考块中。

达到令牌限制(stop_reason: "max_tokens")

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

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

枚举值大小写

结构化输出不保证字符串 enum 和 const 值的大小写:Claude 返回的值可能仅在大小写上与您的 schema 不同,通常出现在空格后单词的首字母上。例如,给定以下 schema:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

输出中可能包含 "Conversation Topic 3"(大写的 “T”),即使该确切值并不在枚举中。响应会正常完成,不会出现错误,也没有特殊的 stop_reason。这同时适用于 JSON 输出和严格工具使用。请以不区分大小写的方式比较枚举值,并避免使用仅在大小写上有所不同的枚举值。

Schema 复杂度限制

结构化输出的工作方式是将您的 JSON schema 编译为约束 Claude 输出的语法。schema 越复杂,生成的语法就越大,编译所需的时间也越长。为防止编译时间过长,API 强制执行若干复杂度限制。

显式限制

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

限制值描述
每个请求的严格工具数20带有 strict: true 的工具的最大数量。非严格工具不计入此限制。
可选参数24所有严格工具 schema 和 JSON 输出 schema 中可选参数的总数。每个未列在 required 中的参数都计入此限制。
具有联合类型的参数16所有严格 schema 中使用 anyOf 或类型数组(例如 "type": ["string", "null"])的参数总数。这类参数的开销尤其大,因为它们会产生指数级的编译成本。

其他内部限制

除了上表中的显式限制之外,对已编译语法的大小还有其他内部限制。之所以存在这些限制,是因为 schema 复杂度无法归结为单一维度:可选参数、联合类型、嵌套对象和工具数量等特性会相互影响,可能使已编译语法变得不成比例地庞大。

当超出这些限制时,您将收到 400 错误,消息为 “Schema is too complex for compilation.”。这些错误意味着您的 schema 的综合复杂度超出了可高效编译的范围,即使上表中的每项单独限制都已满足。作为最后的保障,API 还会强制执行 180 秒的编译超时。通过所有显式检查但生成非常大的已编译语法的 schema 可能会触发此超时。

降低 schema 复杂度的技巧

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

  1. 仅将关键工具标记为严格。如果您有许多工具,请将严格工具使用保留给那些违反 schema 会造成实际问题的工具,对于较简单的工具则依赖 Claude 的自然遵循能力。

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

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

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

对于有效 schema 仍持续出现的问题,请携带您的 schema 定义联系支持团队。

从 beta 版迁移

output_format 参数已移至 output_config.format,并且不再需要 beta 标头。output_format 参数已被弃用。如果仍要使用它,请添加 structured-outputs-2025-11-13 beta 标头。否则,API 会返回 400 错误。

在 Python SDK(v1.0 及更高版本)中,以 output_format={...} 形式传递的 schema 字典会引发 TypeError。请改用 output_config。以 output_format=Model 形式传递给 parse() 或 stream() 的 Pydantic 模型无需任何更改、也无需 beta 标头即可正常工作,因为 SDK 会将其作为 output_config 发送。有关更新后的 API 结构,请参阅使用原始 JSON schema。

功能兼容性

兼容:

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

不兼容:

  • 引用:引用需要将引用块与文本交错排列,这与严格的 JSON schema 约束相冲突。如果在启用引用的同时使用 output_config.format,API 会返回 400 错误。要提取结构化数据并为每个值附带引用,请参阅获取带引用的结构化数据。
  • 消息预填充:预填充与 JSON 输出不兼容。

可用性

结构化输出
API
  • Messages API
  • Managed Agents 不支持
模型
  • 所有模型

适用的端点

  • /v1/messages
零数据保留具备资格(有条件)

不包括 涵盖的模型

您的提示和 Claude 的输出不会被存储。仅缓存 JSON schema,自上次使用起最长保留 24 小时。这也涵盖严格工具使用(工具上的 strict: true),它使用相同的语法管道。 了解更多

HIPAA具备资格

JSON schema 定义中不得包含 PHI;请参阅 PHI 处理指南。 了解更多

使用结构化输出时,提示和响应会按 ZDR 方式处理。但是,出于优化目的,JSON schema 本身会在最后一次使用后临时缓存最多 24 小时。API 响应返回后,不会保留任何提示或响应数据。

结构化输出符合 HIPAA 资格,但不得在 JSON schema 定义中包含 PHI。API 会将 JSON schema 编译为语法,这些语法与消息内容分开缓存,并且这些缓存的 schema 不会获得与提示和响应相同的 PHI 保护。请勿在 schema 属性名、enum 值、const 值或 pattern 正则表达式中包含 PHI。PHI 只应出现在消息内容(提示和响应)中,在那里它受到 HIPAA 保障措施的保护。

后续步骤

让 Claude 在回答有关所提供文档的问题时引用其来源。

通过语法约束采样对 Claude 的工具输入强制执行 JSON Schema 合规性。

将 Claude 连接到外部工具和 API。了解工具在何处运行以及智能体循环的工作原理。

了解 Anthropic 针对模型和功能的定价结构。

此页面对您有帮助吗?