結構化輸出

結構化輸出將 Claude 的回應限制為遵循特定的結構描述，確保下游處理能獲得有效且可解析的輸出。提供兩種互補功能：

• JSON 輸出 (output_config.format)：以特定 JSON 格式獲取 Claude 的回應
• 嚴格工具使用 (strict: true)：保證對工具名稱和輸入進行結構描述驗證

這些功能可以獨立使用，也可以在同一請求中一起使用。

為何使用結構化輸出

若不使用結構化輸出，Claude 可能會產生格式錯誤的 JSON 回應或無效的工具輸入，從而破壞您的應用程式。即使經過仔細的提示設計，您仍可能遇到：

• 無效 JSON 語法導致的解析錯誤
• 缺少必要欄位
• 不一致的資料類型
• 需要錯誤處理和重試的結構描述違規

結構化輸出透過受限解碼保證符合結構描述的回應：

• 始終有效：不再有 JSON.parse() 錯誤
• 類型安全：保證欄位類型和必要欄位
• 可靠：無需因結構描述違規而重試

JSON 輸出

JSON 輸出控制 Claude 的回應格式，確保 Claude 返回符合您結構描述的有效 JSON。在以下情況下使用 JSON 輸出：

• 控制 Claude 的回應格式
• 從圖片或文字中提取資料
• 生成結構化報告
• 格式化 API 回應

快速入門

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Extract the key information from this email: John Smith ([email protected]) 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
        }
      }
    }
  }'

回應格式： 在 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 結構描述

from pydantic import BaseModel
from anthropic import Anthropic


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


client = Anthropic()

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

print(response.parsed_output)

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。

快速開始

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }]
  }'

回應格式： 在 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 回應。這對於需要可靠工具呼叫和結構化最終輸出的代理工作流程非常有用。

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Help me plan a trip to Paris for next month"}
    ],
    # JSON outputs: structured response format
    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,
            },
        }
    },
    # Strict tool use: guaranteed tool parameters
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

重要注意事項

語法編譯與快取

結構化輸出使用帶有已編譯語法構件的受限採樣。這引入了一些需要注意的效能特性：

• 首次請求延遲：第一次使用特定結構描述時，語法編譯期間會有額外延遲
• 自動快取：已編譯的語法從最後一次使用起快取 24 小時，使後續請求速度大幅提升
• 快取失效：如果您更改以下內容，快取將失效：
  • JSON 結構描述結構
  • 請求中的工具集（同時使用結構化輸出和工具使用時）
  • 僅更改 name 或 description 欄位不會使快取失效

提示詞修改與 Token 成本

使用結構化輸出時，Claude 會自動收到一個額外的系統提示詞，說明預期的輸出格式。這意味著：

• 您的輸入 token 數量將略有增加
• 注入的提示詞像任何其他系統提示詞一樣消耗 token
• 更改 output_config.format 參數將使該對話執行緒的任何提示詞快取失效

JSON Schema 限制

結構化輸出支援標準 JSON Schema，但有一些限制。JSON 輸出和嚴格工具使用共享這些限制。

屬性排序

使用結構化輸出時，物件中的屬性會維持您結構描述中定義的順序，但有一個重要注意事項：必要屬性排在前面，可選屬性排在後面。

例如，給定此結構描述：

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

輸出將按以下順序排列屬性：

1. name（必要，按結構描述順序）
2. email（必要，按結構描述順序）
3. notes（可選，按結構描述順序）
4. age（可選，按結構描述順序）

這意味著輸出可能如下所示：

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

如果輸出中的屬性順序對您的應用程式很重要，請確保所有屬性都標記為必要，或在您的解析邏輯中考慮此重新排序。

無效輸出

雖然結構化輸出在大多數情況下保證符合結構描述，但在某些情況下輸出可能與您的結構描述不符：

拒絕（stop_reason: "refusal"）

Claude 即使在使用結構化輸出時也會維持其安全性和有用性。如果 Claude 出於安全原因拒絕請求：

• 回應將具有 stop_reason: "refusal"
• 您將收到 200 狀態碼
• 您將為生成的 token 付費
• 輸出可能與您的結構描述不符，因為拒絕訊息優先於結構描述約束

達到 Token 限制（stop_reason: "max_tokens"）

如果回應因達到 max_tokens 限制而被截斷：

• 回應將具有 stop_reason: "max_tokens"
• 輸出可能不完整且與您的結構描述不符
• 使用更高的 max_tokens 值重試以獲取完整的結構化輸出

結構描述複雜度限制

結構化輸出透過將您的 JSON 結構描述編譯成限制 Claude 輸出的語法來運作。更複雜的結構描述會產生更大的語法，需要更長的編譯時間。為了防止過長的編譯時間，API 強制執行幾個複雜度限制。

明確限制

以下限制適用於所有帶有 output_config.format 或 strict: true 的請求：

額外的內部限制

除了上述明確限制之外，還有對已編譯語法大小的額外內部限制。這些限制的存在是因為結構描述複雜度無法簡化為單一維度：可選參數、聯合類型、巢狀物件和工具數量等功能以可能使已編譯語法不成比例地增大的方式相互作用。

當超過這些限制時，您將收到帶有訊息「Schema is too complex for compilation」的 400 錯誤。這些錯誤意味著您的結構描述的組合複雜度超過了可以有效編譯的範圍，即使上述每個單獨的限制都已滿足。作為最後的保護措施，API 還強制執行 180 秒的編譯超時。通過所有明確檢查但產生非常大的已編譯語法的結構描述可能會達到此超時。

降低結構描述複雜度的技巧

如果您遇到複雜度限制，請按順序嘗試以下策略：

1. 僅將關鍵工具標記為嚴格。 如果您有許多工具，請將其保留給結構描述違規會造成真正問題的工具，並依賴 Claude 對較簡單工具的自然遵從。

2. 減少可選參數。 盡可能將參數設為 required。每個可選參數大約使語法狀態空間的一部分翻倍。如果參數始終有合理的預設值，請考慮將其設為必要，並讓 Claude 明確提供該預設值。

3. 簡化巢狀結構。 具有可選欄位的深度巢狀物件會加劇複雜度。盡可能扁平化結構。

4. 拆分為多個請求。 如果您有許多嚴格工具，請考慮將它們拆分到不同的請求或子代理中。

對於有效結構描述的持續問題，請聯繫支援並提供您的結構描述定義。

資料保留

使用結構化輸出時，提示詞和回應會透過 ZDR 處理。但是，JSON 結構描述本身會暫時快取最多 24 小時（從最後一次使用起）以用於最佳化目的。API 回應之後不會保留任何提示詞或回應資料。

有關所有功能的 ZDR 資格，請參閱 API 和資料保留。

功能相容性

可搭配使用：

• 批次處理：以 50% 折扣大規模處理結構化輸出
• Token 計數：無需編譯即可計算 token
• 串流：像正常回應一樣串流結構化輸出
• 組合使用：在同一請求中同時使用 JSON 輸出（output_config.format）和嚴格工具使用（strict: true）

不相容：

• 引用：引用需要在文字中穿插引用區塊，這與嚴格的 JSON 結構描述約束衝突。如果在 output_config.format 中啟用引用，則返回 400 錯誤。
• 訊息預填充：與 JSON 輸出不相容