Claude Code SDK #10：结构化输出全解——JSON Schema × Zod/Pydantic，让 Agent 直接返回你要的数据结构

为什么需要结构化输出

Here's a classic chocolate chip cookie recipe!
**Chocolate Chip Cookies**
Prep time: 15 minutes | Cook time: 10 minutes
Ingredients: - 2 1/4 cups all-purpose flour - 1 cup butter, softened ...

{
  "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"]
}

快速入门：三步接入

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"]
};

// 第二步：传入 outputFormat
for await (const message of query({
  prompt: "Research Anthropic and provide key company information",
  options: {
    outputFormat: {
      type: "json_schema",
      schema: schema
    }
  }
})) {
  // 第三步：从 ResultMessage 取 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" }
  }
}

• outputFormat.type 固定传 "json_schema"
• Agent 在执行过程中可以自由调用任何工具（WebSearch、Bash 等）；结构化约束只作用于最终输出
• 结果挂在 ResultMessage 的 structured_output 字段，不是普通消息流

用 Zod（TS）和 Pydantic（Python）拿到类型安全

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

// 用 Zod 定义 schema（含枚举类型）
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 }
  }
})) {
  if (message.type === "result" &&
      message.subtype === "success" &&
      message.structured_output) {
    // safeParse：拿到完全类型化的对象
    const parsed = FeaturePlan.safeParse(message.structured_output);
    if (parsed.success) {
      const plan: FeaturePlan = parsed.data;
      console.log(`Feature: ${plan.feature_name}`);
      plan.steps.forEach((step) => {
        console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`);
      });
    }
  }
}

from pydantic import BaseModel
from claude_code_sdk import query, ClaudeCodeOptions, OutputFormat

class Step(BaseModel):
    step_number: int
    description: str
    complexity: str   # "low" | "medium" | "high"

class FeaturePlan(BaseModel):
    feature_name: str
    summary: str
    steps: list[Step]
    risks: list[str]

async def main():
    schema = FeaturePlan.model_json_schema()
    async for message in query(
        prompt="Plan dark mode support for a React app.",
        options=ClaudeCodeOptions(
            output_format=OutputFormat(
                type="json_schema",
                schema=schema
            )
        )
    ):
        if message.type == "result" and message.subtype == "success":
            if message.structured_output:
                plan = FeaturePlan.model_validate(message.structured_output)
                print(plan.feature_name)

output_format 配置结构

实战：多步工具调用 + 结构化输出

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

const todoSchema = {
  type: "object",
  properties: {
    todos: {
      type: "array",
      items: {
        type: "object",
        properties: {
          text:   { type: "string" },
          file:   { type: "string" },
          line:   { type: "number" },
          author: { type: "string" },   // 可选：git blame 可能找不到
          date:   { type: "string" }    // 可选
        },
        required: ["text", "file", "line"]  // 必填字段最小化
      }
    },
    total_count: { type: "number" }
  },
  required: ["todos", "total_count"]
};

// Agent 会自动决定：先用 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}`);
    });
  }
}

错误处理：验证失败怎么办

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") {
      // 降级处理：用更简单的 prompt 重试，或回退到非结构化流程
      console.error("Could not produce valid output");
    }
  }
}

五条实践建议