Claude Agent SDK で output_format / outputFormat を設定したのに、返ってくるのが構造化データではなく素のテキストだった——あるいはリトライ上限で error になった。本稿は、2026-10-24 時点の公式ドキュメントで確認できる仕様をもとに、エージェント向けスキーマを本番で安全に動かすための設計判断をまとめます。対象は Claude Agent SDK（Python / TypeScript）の structured outputs 機能です。
仕様: SDK は draft-07 でスキーマを検証する
SDK に渡すスキーマは JSON Schema draft-07 で検証されます。新しいドラフトを宣言したスキーマは受理されません。
The SDK validates schemas with JSON Schema draft-07, so schemas that declare a newer version are rejected.
スキーマは draft-07 で検証され、より新しいバージョンを宣言するものは拒否される、という仕様です。Zod はデフォルトで draft 2020-12 を出力するため、変換時に target: "draft-7" を渡す必要があります。対応する機能は object/array/string/number/boolean/null の基本型、enum、const、required、ネストオブジェクト、$ref です。format（例: email）はアノテーションとして受理されますが、SDK のバリデーターでは強制されません。
検証が通らない場合、SDK はエージェントに再プロンプトし、リトライ上限内に成功しなければ構造化データの代わりに error を返します。
本番でつまずく失敗モード
過去のバージョンでは、無効なスキーマは黙って無視されていました。
Before v2.1.205, an invalid schema was silently ignored and the agent returned unstructured text.
v2.1.205 より前は無効スキーマがサイレントに無視され、エージェントは非構造化テキストを返していた、という記述です（正確なバージョン番号は公式ドキュメントで要確認）。現在は失敗が明示されるため、呼び出し側は結果メッセージの subtype と structured_output を必ず確認する実装にする必要があります。subtype が success でも structured_output が無い場合があり、それも失敗として扱います。
References
[1] https://code.claude.com/docs/en/agent-sdk/structured-outputs