Claude API Structured Outputs実践ガイド — JSON出力モードとstrict tool useの使い分けから併用パターンまで

// Before: プロンプト頼みのJSON出力 — パースが壊れるリスクが常にある
const response = await client.messages.create({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 1024,
  messages: [{ role: "user", content: "ユーザー情報をJSON形式で返して" }],
});
const text = response.content[0].text;
const data = JSON.parse(text); // ここで落ちる可能性がある

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";

const client = new Anthropic();

// Zodでスキーマを定義
const UserSchema = z.object({
  name: z.string(),
  email: z.string(),
  age: z.number(),
  interests: z.array(z.string()),
});

const response = await client.messages.parse({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 1024,
  output_config: { format: zodOutputFormat(UserSchema) },
  messages: [
    {
      role: "user",
      content:
        "田中太郎、30歳、メールはtanaka@example.com、趣味はプログラミングと登山",
    },
  ],
});

// response.parsed_output は型安全（z.infer<typeof UserSchema> 型）
console.log(response.parsed_output.name); // "田中太郎"
console.log(response.parsed_output.interests); // ["プログラミング", "登山"]

if (response.stop_reason !== "end_turn") {
  throw new Error("JSON出力が途中で切断された可能性があります");
}

const response = await client.messages.create({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 1024,
  tools: [
    {
      name: "extract_user_info",
      description: "テキストからユーザー情報を抽出する",
      strict: true, // これだけで型保証が有効になる
      input_schema: {
        type: "object" as const,
        properties: {
          name: { type: "string", description: "氏名" },
          email: { type: "string", description: "メールアドレス" },
          age: { type: "number", description: "年齢" },
        },
        required: ["name", "email", "age"],
        additionalProperties: false,
      },
    },
  ],
  tool_choice: { type: "any" },
  messages: [
    {
      role: "user",
      content: "山田花子さん（25歳）の連絡先はhanako@example.comです",
    },
  ],
});

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";

const client = new Anthropic();

// 最終出力のスキーマ
const ReportSchema = z.object({
  title: z.string(),
  summary: z.string(),
  findings: z.array(
    z.object({
      topic: z.string(),
      detail: z.string(),
      confidence: z.number(),
    })
  ),
  recommendation: z.string(),
});

// ツール定義（strict: trueで入力パラメータも保証）
const tools: Anthropic.Messages.Tool[] = [
  {
    name: "web_search",
    description: "Webで情報を検索する",
    strict: true,
    input_schema: {
      type: "object" as const,
      properties: {
        query: { type: "string", description: "検索クエリ" },
        max_results: { type: "number", description: "最大件数" },
      },
      required: ["query", "max_results"],
      additionalProperties: false,
    },
  },
];

// エージェントループ
let messages: Anthropic.Messages.MessageParam[] = [
  { role: "user", content: "2026年のTypeScriptフレームワーク動向を調査して" },
];

while (true) {
  const response = await client.messages.parse({
    model: "claude-sonnet-4-5-20250929",
    max_tokens: 4096,
    tools,
    output_config: { format: zodOutputFormat(ReportSchema) },
    messages,
  });

  // ツール呼び出しがあれば処理して続行
  const toolUse = response.content.find((b) => b.type === "tool_use");
  if (toolUse && toolUse.type === "tool_use") {
    const result = await executeSearch(toolUse.input); // 実際のツール実行
    messages.push({ role: "assistant", content: response.content });
    messages.push({
      role: "user",
      content: [
        { type: "tool_result", tool_use_id: toolUse.id, content: result },
      ],
    });
    continue;
  }

  // 最終出力 — ReportSchema準拠が保証されている
  console.log(response.parsed_output.title);
  console.log(response.parsed_output.findings);
  break;
}