マルチエージェントClaude Agent SDK の構造化出力｜AIの答えをJSONで受け取る
この記事の要点
- 構造化出力は、AI エージェントの最後の答えを、決めた形（JSON Schema）どおりの JSON で受け取る仕組み
- エージェントは途中でどの道具を使ってもよく、最後に形の確認と作り直しまで SDK がやる
- 成功の判定は「subtype が success」かつ「structured_output がある」の両方。形はシンプルに保つと失敗しにくい
活用例：問い合わせメールから必要な項目を抜き出して表に入れる
- 部署
- 営業・カスタマーサポート
- 使うもの
- Claude Agent SDK
- AIに任せる
- 文面を読んで項目を抜き出す・形をそろえる
- 人が決める
- 抜き出す項目の決め方・抜けた時の扱い
AI エージェントの答えは、ふつうは文章で返ってきます。人が読むならそれで十分ですが、表やデータベース、画面に流し込みたいとき は困ります。毎回、文章から必要な所を探して形を整える必要があるからです。
公式ドキュメント「Get structured output from agents」（2026年11月7日確認）にもとづいて、Claude Agent SDK で 答えを決まった形の JSON で受け取る方法 を解説します。SDK の全体像は Claude Agent SDK とは をご覧ください。
結論：欲しい形を先に渡せば、その形で返ってくる
構造化出力では、欲しいデータの形（JSON Schema）を先に渡します。 エージェントは作業の途中で検索やファイルの読み込みなど、どんな道具を使ってもかまいません。最後に SDK が答えを形と照らし合わせ、合っていなければ作り直させ、合格したものだけを返します。
| 文章で受け取る | 構造化出力で受け取る | |
|---|---|---|
| 返ってくるもの | 自由な文章 | 決めた形どおりの JSON |
| 使う前の手間 | 必要な所を探して抜き出す・単位をそろえる | そのまま使える |
| 形のぶれ | 毎回少しずつ違う | 毎回同じ |
| 向いている使い道 | 会話・説明 | 表・データベース・画面への流し込み |
たとえばレシピを調べさせる場合、文章だと「準備15分」を数字に直したり、材料と手順を分けたりする手間がかかります。構造化出力なら prep_time_minutes: 15 のように最初から数字で、材料は材料の一覧として返ってきます。
使い方：output_format に形を渡すだけ
呼び出しのオプションに、次の2つを持った設定を渡します（Python は output_format、TypeScript は outputFormat）。
type："json_schema"にするschema：欲しい形を書いた JSON Schema
エージェントが終わると、結果のメッセージに structured_output という項目が付き、そこに形の確認を通った JSON が入っています。
形の書き方は、ふつうの JSON Schema です。文字・数字・真偽・配列・入れ子のオブジェクト、選択肢（enum）、必須の項目（required）、参照（$ref）などが使えます。
{
"type": "object",
"properties": {
"company_name": { "type": "string" },
"founded_year": { "type": "number" },
"headquarters": { "type": "string" }
},
"required": ["company_name"]
}この例では、会社名だけが必須で、設立年と本社は分からなければ省いてよい形になっています。
注意しておきたい細かい点
- SDK は JSON Schema の draft-07 で確かめる。新しい版を名乗る形は受け付けない
- 形そのものが正しくないと、始まる時点でエラーになる（v2.1.205 より前は黙って無視され、文章が返っていた）
- `"format"："email"` のような書式の指定は、メモとして受け取るだけで、強制はされない
Zod・Pydantic で型付きにする
JSON Schema を手で書く代わりに、TypeScript なら Zod、Python なら Pydantic で形を定義できます。こうすると、受け取った結果を型の付いたオブジェクトとして扱え、入力補完や型チェックも効きます。
- Pydantic：モデルのクラスを作り、
.model_json_schema()で JSON Schema にして渡す。受け取った結果はモデルで読み込む - Zod：形を定義して
z.toJSONSchema(...)で変換する。Zod は標準で新しい版の形を出すので、target: "draft-7"を付ける のを忘れない
公式の例では、新しい機能の「実装計画」を、要約・手順の一覧（それぞれの難しさつき）・心配な点の一覧という形で受け取っています。仕事なら、会議の議事録から「決まったこと・担当・期限」を受け取る、といった使い方にそのまま応用できます。
道具を何回使っても、最後は1つの形にまとまる
構造化出力のよいところは、途中の作業は自由なまま、最後の答えだけをそろえられる 点です。
公式の例では、エージェントが次のように動きます。
- 検索の道具で、コードの中の「TODO」というメモを探す
- コマンドで、それぞれのメモを誰がいつ書いたかを調べる
- 結果を「メモの一覧・件数」の形にまとめて返す
書いた人や日付は分からないこともあるので、形の上では 省いてもよい項目 にしてあります。エージェントは分かった分だけ埋めて、残りは空けて返します。自社の処理を道具として足したい場合は、Claude Agent SDK のカスタムツール と組み合わせます。
失敗の見分け方
形に合う答えが作れないこともあります。よくある原因は次のとおりです。
- 形が複雑すぎる
- 頼んだ内容があいまい
- 作り直しの上限に達した
結果のメッセージの subtype を見ると、何が起きたかが分かります。
| subtype | 意味 |
|---|---|
| success | 形の確認を通った答えができた |
| error_max_structured_output_retries | 何回か作り直しても、形に合う答えが残らなかった |
ここで大事なのが、「success なのに structured_output が空」という場合もある ことです。作業は終わったけれど、形どおりの答えを出さなかったケースです。公式は、subtype が success で、かつ structured_output がある時だけ成功 とみなし、それ以外はすべて失敗として扱う書き方をすすめています。
また、モデルが途中で切り替わった影響で、できていた答えが取り消されて同じエラーになることもあります。形を直す前に、エラーの一覧で原因を見分けるようにします。
失敗を減らす3つのコツ
公式が挙げているコツは3つです。
| コツ | やり方 |
|---|---|
| 形はシンプルに | 深い入れ子や必須の項目が多いほど満たしにくい。小さく始めて足していく |
| 形を仕事に合わせる | 情報がそろわないかもしれない項目は「なくてもよい」にする |
| 頼み方をはっきり | あいまいな頼み方だと、何を出せばよいか迷う |
特に2つ目は、仕事のデータでよく効きます。問い合わせメールから項目を抜き出す場合、電話番号が書かれていないメールもあります。全部を必須にすると、それだけで失敗が増えます。
まとめ
- 構造化出力は、AI エージェントの答えを決めた形の JSON で受け取る 仕組み
- 途中でどんな道具を使っても、最後に SDK が形を確かめ、合わなければ作り直させる
- 成功は「success」かつ「structured_output がある」の両方。形はシンプルに、なくてもよい項目は任意に
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
