從代理獲取結構化輸出

結構化輸出讓您定義想要從代理返回的資料的確切形狀。代理可以使用任何需要的工具來完成任務，而您仍然會在最後獲得與您的架構相匹配的驗證 JSON。定義一個 JSON Schema 來描述您需要的結構，SDK 會根據它驗證輸出，在不匹配時重新提示。如果驗證在重試限制內未成功，結果將是錯誤而不是結構化資料；請參閱錯誤處理。為了獲得完整的類型安全，使用 Zod（TypeScript）或 Pydantic（Python）來定義您的架構並獲得強類型物件。

為什麼要使用結構化輸出？

代理預設返回自由格式的文本，這適用於聊天但不適用於您需要以程式方式使用輸出的情況。結構化輸出為您提供類型化資料，您可以直接傳遞給應用程式邏輯、資料庫或 UI 元件。考慮一個食譜應用程式，其中代理搜尋網路並帶回食譜。沒有結構化輸出，您會獲得自由格式的文本，需要自己解析。使用結構化輸出，您定義想要的形狀並獲得可以直接在應用程式中使用的類型化資料。

沒有結構化輸出

這是一個經典的巧克力晶片餅乾食譜！

**巧克力晶片餅乾**
準備時間：15 分鐘 | 烹飪時間：10 分鐘

材料：
- 2 1/4 杯通用麵粉
- 1 杯軟化黃油
...

要在您的應用程式中使用這個，您需要解析出標題，將’15 分鐘’轉換為數字，將材料與說明分開，並處理跨回應的不一致格式。

使用結構化輸出

{
  "name": "Chocolate Chip Cookies",
  "prep_time_minutes": 15,
  "cook_time_minutes": 10,
  "ingredients": [
    { "item": "all-purpose flour", "amount": 2.25, "unit": "cups" },
    { "item": "butter, softened", "amount": 1, "unit": "cup" }
    // ...
  ],
  "steps": ["Preheat oven to 375°F", "Cream butter and sugar" /* ... */]
}

您可以直接在 UI 中使用的類型化資料。

快速開始

要使用結構化輸出，定義一個 JSON Schema 來描述您想要的資料形狀，然後通過 outputFormat 選項（TypeScript）或 output_format 選項（Python）將其傳遞給 query()。當代理完成時，結果訊息包含一個 structured_output 欄位，其中包含與您的架構相匹配的驗證資料。下面的範例要求代理研究 Anthropic 並返回公司名稱、成立年份和總部作為結構化輸出。

import { query } from "@anthropic-ai/claude-agent-sdk";

// 定義您想要返回的資料形狀
const schema = {
  type: "object",
  properties: {
    company_name: { type: "string" },
    founded_year: { type: "number" },
    headquarters: { type: "string" }
  },
  required: ["company_name"]
};

for await (const message of query({
  prompt: "Research Anthropic and provide key company information",
  options: {
    outputFormat: {
      type: "json_schema",
      schema: schema
    }
  }
})) {
  // 結果訊息包含具有驗證資料的 structured_output
  if (message.type === "result" && message.subtype === "success" && message.structured_output) {
    console.log(message.structured_output);
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

使用 Zod 和 Pydantic 的類型安全架構

與其手動編寫 JSON Schema，您可以使用 Zod（TypeScript）或 Pydantic（Python）來定義您的架構。這些庫為您生成 JSON Schema，並讓您將回應解析為完全類型化的物件，您可以在整個程式碼庫中使用，具有自動完成和類型檢查。下面的範例定義了一個功能實現計劃的架構，包括摘要、步驟列表（每個步驟都有複雜性級別）和潛在風險。代理計劃該功能並返回一個類型化的 FeaturePlan 物件。然後您可以訪問 plan.summary 等屬性，並使用完整的類型安全遍歷 plan.steps。

import { z } from "zod";
import { query } from "@anthropic-ai/claude-agent-sdk";

// 使用 Zod 定義架構
const FeaturePlan = z.object({
  feature_name: z.string(),
  summary: z.string(),
  steps: z.array(
    z.object({
      step_number: z.number(),
      description: z.string(),
      estimated_complexity: z.enum(["low", "medium", "high"])
    })
  ),
  risks: z.array(z.string())
});

type FeaturePlan = z.infer<typeof FeaturePlan>;

// 轉換為 JSON Schema
const schema = z.toJSONSchema(FeaturePlan);

// 在查詢中使用
for await (const message of query({
  prompt:
    "Plan how to add dark mode support to a React app. Break it into implementation steps.",
  options: {
    outputFormat: {
      type: "json_schema",
      schema: schema
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success" && message.structured_output) {
    // 驗證並獲得完全類型化的結果
    const parsed = FeaturePlan.safeParse(message.structured_output);
    if (parsed.success) {
      const plan: FeaturePlan = parsed.data;
      console.log(`Feature: ${plan.feature_name}`);
      console.log(`Summary: ${plan.summary}`);
      plan.steps.forEach((step) => {
        console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`);
      });
    }
  }
}

優點：

完整的類型推斷（TypeScript）和類型提示（Python）
使用 safeParse() 或 model_validate() 進行運行時驗證
更好的錯誤訊息
可組合、可重用的架構

輸出格式配置

outputFormat（TypeScript）或 output_format（Python）選項接受一個物件，其中包含：

type：設置為 "json_schema" 以進行結構化輸出
schema：一個 JSON Schema 物件，定義您的輸出結構。您可以使用 z.toJSONSchema() 從 Zod 架構或使用 .model_json_schema() 從 Pydantic 模型生成此項。

SDK 支援標準 JSON Schema 功能，包括所有基本類型（object、array、string、number、boolean、null）、enum、const、required、嵌套物件和 $ref 定義。有關支援的功能和限制的完整列表，請參閱 JSON Schema 限制。

範例：TODO 追蹤代理

此範例演示了結構化輸出如何與多步驟工具使用配合使用。代理需要在程式碼庫中查找 TODO 註釋，然後為每個註釋查找 git blame 資訊。它自主決定使用哪些工具（Grep 搜尋、Bash 執行 git 命令）並將結果組合成單個結構化回應。架構包括可選欄位（author 和 date），因為 git blame 資訊可能不適用於所有檔案。代理填入它能找到的內容並省略其餘部分。

import { query } from "@anthropic-ai/claude-agent-sdk";

// 定義 TODO 提取的結構
const todoSchema = {
  type: "object",
  properties: {
    todos: {
      type: "array",
      items: {
        type: "object",
        properties: {
          text: { type: "string" },
          file: { type: "string" },
          line: { type: "number" },
          author: { type: "string" },
          date: { type: "string" }
        },
        required: ["text", "file", "line"]
      }
    },
    total_count: { type: "number" }
  },
  required: ["todos", "total_count"]
};

// 代理使用 Grep 查找 TODO，使用 Bash 獲取 git blame 資訊
for await (const message of query({
  prompt: "Find all TODO comments in this codebase and identify who added them",
  options: {
    outputFormat: {
      type: "json_schema",
      schema: todoSchema
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success" && message.structured_output) {
    const data = message.structured_output as { total_count: number; todos: Array<{ file: string; line: number; text: string; author?: string; date?: string }> };
    console.log(`Found ${data.total_count} TODOs`);
    data.todos.forEach((todo) => {
      console.log(`${todo.file}:${todo.line} - ${todo.text}`);
      if (todo.author) {
        console.log(`  Added by ${todo.author} on ${todo.date}`);
      }
    });
  }
}

錯誤處理

當代理無法生成與您的架構相匹配的有效 JSON 時，結構化輸出生成可能會失敗。這通常發生在架構對於任務過於複雜、任務本身不明確或代理在嘗試修復驗證錯誤時達到重試限制時。發生錯誤時，結果訊息有一個 subtype 指示出了什麼問題：

Subtype	含義
`success`	輸出已成功生成並驗證
`error_max_structured_output_retries`	代理在多次嘗試後無法生成有效輸出

下面的範例檢查 subtype 欄位以確定輸出是否成功生成或您是否需要處理失敗：

for await (const msg of query({
  prompt: "Extract contact info from the document",
  options: {
    outputFormat: {
      type: "json_schema",
      schema: contactSchema
    }
  }
})) {
  if (msg.type === "result") {
    if (msg.subtype === "success" && msg.structured_output) {
      // 使用驗證的輸出
      console.log(msg.structured_output);
    } else if (msg.subtype === "error_max_structured_output_retries") {
      // 處理失敗 - 使用更簡單的提示重試、回退到非結構化等
      console.error("Could not produce valid output");
    }
  }
}

避免錯誤的提示：

保持架構專注。 具有許多必需欄位的深層嵌套架構更難滿足。從簡單開始，根據需要添加複雜性。
匹配架構與任務。 如果任務可能沒有您的架構所需的所有資訊，請將這些欄位設為可選。
使用清晰的提示。 不明確的提示使代理更難知道要生成什麼輸出。

​為什麼要使用結構化輸出？

​快速開始

​使用 Zod 和 Pydantic 的類型安全架構

​輸出格式配置

​範例：TODO 追蹤代理

​錯誤處理

​相關資源