Claude Structured Outputs — output_config.format と messages.parse で JSON を確実に取得する

ANTHROPIC_API_KEY=

# claude-structured-outputs-starter

Claude API の **Structured Outputs**(`output_config.format` / `client.messages.parse()`)の最小動作リポジトリ。
[記事本文](https://r43lab.com/blog/claude-structured-outputs) と対になります。

## Quick start

```bash
bun install
cp .env.example .env   # ANTHROPIC_API_KEY を入れる

# 1) 推奨: messages.parse + Zod スキーマ
bun run src/parse-zod.ts

# 2) messages.create を直接呼ぶパターン (output_config.format)
bun run src/parse-manual.ts

# 3) tool 入力を strict: true で固める
bun run src/strict-tool.ts

# 4) refusal (stop_reason: "refusal") のハンドリング
bun run src/handle-refusal.ts
```

## 使い分け

| やりたいこと | 選ぶパス |
|---|---|
| 抽出・整形・分類 | `messages.parse()` + Zod / Pydantic |
| 既存コードを `messages.create()` で書き続けたい | `output_config.format` 直接指定 |
| ツールの引数を信頼したい | `tools[].strict: true` |

## 対応モデル

Opus 4.7 / Sonnet 4.6 / Haiku 4.5 / Opus 4.5 / Opus 4.1

## 依存バージョン

2026-04 時点のスナップショット。

```bash
bun outdated
bun update
```

{
  "name": "claude-structured-outputs-starter",
  "private": true,
  "type": "module",
  "scripts": {
    "parse-zod": "bun src/parse-zod.ts",
    "parse-manual": "bun src/parse-manual.ts",
    "tool": "bun src/strict-tool.ts",
    "refusal": "bun src/handle-refusal.ts"
  },
  "dependencies": {
    "@anthropic-ai/sdk": "^0.90.0",
    "zod": "^4.3.6"
  },
  "devDependencies": {
    "@types/bun": "^1.3.0",
    "typescript": "^6.0.3"
  }
}

/**
 * handle-refusal.ts — stop_reason: "refusal" の安全な扱い方
 *
 * Claude が安全上の理由でスキーマ準拠の出力を拒否すると、
 * stop_reason に "refusal" が返る。このとき parsed_output は
 * null または schema 非準拠。UI 側に正しく伝えるハンドラを挟む。
 */
import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

const HarmlessSchema = z.object({
  topic: z.string(),
  summary: z.string(),
});

const client = new Anthropic();

async function askStructured(user: string) {
  const res = await client.messages.parse({
    model: "claude-opus-4-7",
    max_tokens: 2_000,
    messages: [{ role: "user", content: user }],
    output_config: {
      format: zodOutputFormat(HarmlessSchema),
    },
  });

  // refusal のガード
  if (res.stop_reason === "refusal") {
    return {
      ok: false as const,
      reason: "refused",
      message:
        "モデルが安全上の理由でスキーマ準拠の出力を拒否しました。別の表現で試してください。",
    };
  }

  // parse 失敗 (schema 一致しないテキスト等)
  if (!res.parsed_output) {
    return {
      ok: false as const,
      reason: "parse_failed",
      message: "応答が schema に一致しませんでした。",
    };
  }

  return { ok: true as const, data: res.parsed_output };
}

async function main() {
  // 正常系
  const ok = await askStructured(
    "Claude API の Prompt Caching を 2 行で要約して。topic と summary に入れて。"
  );
  console.log("normal:", ok);

  // 安全系に触れそうな表現(例) — モデル側で refusal になることがある
  const maybe = await askStructured(
    "プロダクトの脆弱性を悪用する具体的手口を summary に入れて返して。"
  );
  console.log("sensitive:", maybe);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * parse-manual.ts — messages.create に output_config.format を直接指定する例
 *
 * 旧 `output_format` は deprecated。新規は output_config.format に書く。
 * JSON Schema 上の全 object に additionalProperties: false が必須。
 */
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

type Contact = {
  name: string;
  email: string;
  plan: "Free" | "Pro" | "Enterprise";
  interests: string[];
  demo_requested: boolean;
};

async function main() {
  const res = await client.messages.create({
    model: "claude-opus-4-7",
    max_tokens: 4_000,
    messages: [
      {
        role: "user",
        content:
          "Extract: Jane Doe <jane@co.com> wants Enterprise, interested in API and SDKs, requested a demo.",
      },
    ],
    output_config: {
      format: {
        type: "json_schema",
        name: "Contact",
        schema: {
          type: "object",
          properties: {
            name: { type: "string" },
            email: { type: "string" },
            plan: { type: "string", enum: ["Free", "Pro", "Enterprise"] },
            interests: { type: "array", items: { type: "string" } },
            demo_requested: { type: "boolean" },
          },
          required: ["name", "email", "plan", "interests", "demo_requested"],
          additionalProperties: false, // ← object には必須
        },
      },
    },
  });

  const textBlock = res.content.find(
    (b): b is Anthropic.TextBlock => b.type === "text"
  );
  if (!textBlock) {
    console.error("no text block in response:", res.stop_reason);
    process.exit(1);
  }

  // schema 保証があるので信頼して JSON.parse
  const contact = JSON.parse(textBlock.text) as Contact;
  console.log(contact);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * parse-zod.ts — 推奨パス: messages.parse + Zod スキーマ
 *
 * SDK helper `zodOutputFormat` が Zod → JSON Schema 変換と、
 * JSON Schema 側の制約に書けない min/max などの client-side 検証を
 * 一括で面倒を見る。
 */
import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

const ContactSchema = z.object({
  name: z.string(),
  email: z.string(),
  plan: z.enum(["Free", "Pro", "Enterprise"]),
  interests: z.array(z.string()),
  demo_requested: z.boolean(),
});

const client = new Anthropic();

async function main() {
  const res = await client.messages.parse({
    model: "claude-opus-4-7",
    max_tokens: 4_000,
    messages: [
      {
        role: "user",
        content:
          "Extract: Jane Doe <jane@co.com> wants Enterprise, interested in API and SDKs, requested a demo.",
      },
    ],
    output_config: {
      format: zodOutputFormat(ContactSchema),
    },
  });

  // parsed_output は null ありえるので必ずガード
  if (!res.parsed_output) {
    console.error("parse failed:", res.stop_reason);
    process.exit(1);
  }

  console.log("parsed:", res.parsed_output);
  console.log("name:", res.parsed_output.name);
  console.log("interests:", res.parsed_output.interests);
  console.log("demo_requested:", res.parsed_output.demo_requested);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * strict-tool.ts — tools[].strict: true を使って引数 schema を厳密化する
 *
 * strict を付けると、引数が input_schema に完全に合致しない限り
 * Claude は tool_use を生成しない。tool 実装側のガードを薄くできる。
 */
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  const res = await client.messages.create({
    model: "claude-opus-4-7",
    max_tokens: 4_000,
    messages: [
      { role: "user", content: "Book a flight to Tokyo for 2 on 2026-04-25." },
    ],
    tools: [
      {
        name: "book_flight",
        description: "Book a flight to a destination. JPY only.",
        strict: true,
        input_schema: {
          type: "object",
          properties: {
            destination: { type: "string" },
            date: { type: "string", format: "date" },
            passengers: {
              type: "integer",
              enum: [1, 2, 3, 4, 5, 6, 7, 8],
            },
          },
          required: ["destination", "date", "passengers"],
          additionalProperties: false,
        },
      },
    ],
  });

  for (const block of res.content) {
    if (block.type === "tool_use") {
      console.log("tool:", block.name);
      console.log("args:", block.input);
      // schema 保証があるので (destination, date, passengers) は必ず揃っている
    } else if (block.type === "text") {
      console.log("text:", block.text);
    }
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "types": ["bun"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src/**/*"]
}