Agent SDKとAPIでStructured Outputsを使う

JSONをプロンプトだけで頼むと、構文、必須項目、型が崩れることがあります。現行のClaude APIのStructured Outputsは、JSON出力をスキーマへ制約する機能と、ツール名・入力を検証するStrict Tool Useを分けて提供します。 公式Structured Outputs

まず小さいスキーマ

決まった形のJSONでも、中身が業務に合うかは別に確認します。

1. 1スキーマを決める必要なキー・型・追加キーの扱いを定義。
2. 2結果の状態を読む成功とstructured_outputの有無を確認。失敗は別経路へ。
3. 3値の意味を検査空文字、URL形式、根拠、用途上の条件を確認。

形式に合っていることと事実が正しいことを混同しません。拒否や上限到達を正常データとして渡さないようにします。

{
  "type": "object",
  "properties": {
    "title": {"type":"string"},
    "needs_review": {"type":"boolean"}
  },
  "required": ["title", "needs_review"],
  "additionalProperties": false
}

Messages APIでは output_config.format に type: "json_schema" とスキーマを渡し、応答のtext content blockをJSONとして読みます。旧ベータ版の output_format から位置が変わり、現在は output_config が基本です。 公式仕様

安定性を測る

一回成功しただけで安定とは言いません。同じ入力を複数回送り、必須キー、型、追加キー、拒否や空入力、長文切り詰めを機械的に検証します。複雑なネスト、任意項目、union型が増えるとスキーマのコンパイル制限に触れる可能性があるため、必要な項目だけに絞り、分割できる処理は分割します。JSONが有効でも、値の意味やメールアドレスの実在性を保証する機能ではありません。

Agent SDKでエージェント結果を構造化する場合は、Agent SDKの「Get structured output」ページと使用言語の型・スキーマ例を確認します。CLIには --output-format json（CLI結果の形式指定）とは別に、print mode専用の --json-schema（エージェント処理後にスキーマに一致するJSONを返す指定）があります。両者を混同せず、スキーマと失敗時の扱いを確認します。 CLIリファレンス

PythonはAgent SDK、TypeScriptは実装、独自の入力検証はCustom Toolsへ進めます。

限界

制約付き出力は形式の信頼性を上げますが、事実の正しさ、権限、個人情報、業務ルールを判断しません。受信後にアプリ側でもスキーマ・値・権限を検証します。

Agent SDKで受け取る

Agent SDKでは、TypeScriptの outputFormat、Pythonの output_format へ type: "json_schema" とスキーマを渡します。成功した result メッセージに structured_output があれば、それが検証済みの値です。失敗時は error_max_structured_output_retries などを確認し、フィールドがない成功メッセージも成功データとして扱いません。 Agent SDKのStructured Output

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

schema = {
    "type": "object",
    "properties": {"title": {"type": "string"}, "needs_review": {"type": "boolean"}},
    "required": ["title", "needs_review"],
}

async def main():
    async for message in query(
        prompt="README.mdの題名と、確認が必要かを返して。ファイルを変更しないで。",
        options=ClaudeAgentOptions(
            tools=["Read"],
            allowed_tools=["Read"],
            output_format={"type": "json_schema", "schema": schema},
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success" and message.structured_output:
                print(message.structured_output)
            else:
                print(f"structured output unavailable: {message.subtype}")

asyncio.run(main())

CLIで同じ考え方を使う場合は、現行CLIリファレンスの --json-schema を使います。これはprint mode専用で、スキーマが不正ならCLIがエラー終了します。例えばPowerShellでは次のように実行します。

claude -p --json-schema '{"type":"object","properties":{"title":{"type":"string"},"needs_review":{"type":"boolean"}},"required":["title","needs_review"]}' "README.mdの題名と確認フラグを返して"

--output-format json はCLI応答の包み方を選ぶ指定で、--json-schemaとは役割が異なります。どちらを使っても、受け側で値の意味、許可されたキー、用途上の妥当性を確認します。 CLIリファレンス

ブログのメタデータなら、タイトル、説明、タグ、要確認理由を別フィールドにし、空文字を許すかを明示します。スキーマへ説明文を詰め込みすぎず、後段で値の長さやURL形式を検証します。拒否や上限到達時には、JSONが返る前提を捨ててエラー経路へ送ります。制約を増やすほど安心と考えず、必要な項目だけを小さく保ちます。