Anthropic Claude モデルを使用した構造化出力

構造化出力を使用すると、Claude モデルの生成された出力を特定の JSON スキーマに正確に準拠するように制限できます。これは、Claude モデルからのレスポンスが常にダウンストリーム アプリケーション、データベース、処理パイプラインに必要な正確な形式であることを保証するのに役立ちます。

構造化された出力には、次の 2 つの補完的な機能があります。これらの機能は、同じリクエストで個別にまたは組み合わせて使用できます。

  • JSON 出力（output_config.format）: 提供したスキーマに一致する JSON オブジェクトにモデルのテキスト レスポンスを制限します。テキストから構造化データを抽出したり、構造化レポートを生成したり、API レスポンスをフォーマットしたりする必要がある場合に使用します。
  • 厳密なツールの使用（tools[].strict）: モデルがツールに渡す引数がツールの input_schema と一致することを保証します。これは、エージェント ワークフローで型安全な関数呼び出しが必要な場合に使用します。

詳細については、Anthropic の Claude を使用したビルド: 構造化された出力と厳密なツールの使用に関するドキュメントをご覧ください。

サポートされている Anthropic Claude モデル

Gemini Enterprise Agent Platform は、すべての Anthropic Claude 4.5 以降のモデルで構造化された出力をサポートしています。

構造化された出力へのアクセスを制御する

デフォルトでは、構造化出力は組織のポリシーの制約 constraints/vertexai.allowedPartnerModelFeatures によって無効になっています。構造化出力を有効にするには、この制約を構成して structured_outputs 機能を明示的に許可する必要があります。

また、組織のポリシーの制約 constraints/vertexai.allowedModels を構成して、Claude モデルへのアクセスを制限することもできます。

組織のポリシーの制約を構成する手順については、Model Garden モデルへのアクセスを制御するをご覧ください。

構造化出力リクエストを送信する

JSON 出力をリクエストするには、パブリッシャー モデル エンドポイントに POST リクエストを送信し、リクエスト本文に output_config パラメータを含めます。output_config パラメータは、モデルのレスポンスが準拠する必要がある JSON スキーマを指定します。

REST

次のサンプルは、構造化されていないメールから構造化された連絡先情報を抽出するリクエストを Agent Platform API に送信する方法を示しています。レスポンスは、name、email、plan_interest、demo_requested の各フィールドを含む JSON オブジェクトに制限されます。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: Anthropic Claude モデルをサポートするリージョン。グローバル エンドポイントを使用するには、グローバル エンドポイントを指定するをご覧ください。
  • MODEL: サポートされている Claude モデル（例: claude-opus-4-7）。
  • ROLE: メッセージに関連付けられたロール。user または assistant を指定できます。最初のメッセージでは、user ロールを使用する必要があります。Claude モデルは user と assistant のターンを交互に操作します。最後のメッセージが assistant ロールを使用する場合、そのメッセージの内容の直後に回答の内容が続きます。これを使用して、モデルの回答の一部を制限できます。
  • CONTENT: user または assistant のメッセージの内容（テキストなど）。例: Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.
  • MAX_TOKENS: レスポンスで生成できるトークンの最大数。トークンは約 3.5 文字です。100 トークンは約 60～80 語に相当します。

    レスポンスを短くしたい場合は小さい値を、長くしたい場合は大きい値を指定します。

  • STREAM: レスポンスがストリーミングされるかどうかを指定するブール値。レスポンスをストリーミングする場合は true、すべてのレスポンスを一度に戻すには false に設定します。構造化出力は通常、false で返されます。

この例では、次の構造化出力フィールドを使用します。各フィールドの詳細については、リクエスト フィールドのセクションをご覧ください。

  • output_config: モデルのレスポンスの構造を制御する最上位の構成ブロック。
  • output_config.format.type: json_schema に設定すると、提供されたスキーマに準拠する JSON オブジェクトにレスポンスが制限されます。
  • output_config.format.schema: モデルのレスポンスに必要な構造を定義する JSON スキーマ。スキーマは、サポートされている JSON スキーマのサブセットに準拠している必要があります。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

リクエストの本文（JSON）: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。content ブロックの text フィールドには、output_config で指定したスキーマに準拠する JSON 文字列が含まれます。

リクエスト フィールド

次のフィールドは、JSON 出力に固有のものです。他のリクエスト フィールドについては、Claude メッセージ API リファレンスをご覧ください。

  • output_config: モデルのレスポンスの構造を制御する最上位の構成ブロック。
  • output_config.format: 出力の形式定義。json_schema タイプのみがサポートされています。
  • output_config.format.type: 適用する出力形式のタイプ。レスポンスを JSON オブジェクトに制限するには、これを json_schema に設定します。

  • output_config.format.schema: モデルのレスポンスに必要な構造を定義する JSON スキーマ。構造化出力は、標準の JSON スキーマをサポートしていますが、オブジェクトの additionalProperties を false に設定する必要がある、数値や文字列の長さの制約をサポートしていないなどの制限があります。サポートされている機能とサポートされていない機能の一覧については、Anthropic の JSON スキーマの制限事項に関するドキュメントをご覧ください。スキーマ内では、通常、次の項目を指定します。

    • type: このレベルの値の JSON 型（通常はルートスキーマの object）。
    • properties: フィールド名とその型定義のマップ。モデルが返す必要のある各フィールドを記述します。
    • required: モデルがレスポンスに含める必要のあるプロパティ名のリスト。
    • additionalProperties: false に設定すると、モデルが properties で宣言されていないフィールドを含まないようにするブール値。

厳格なツール使用

厳密なツール使用により、モデルがツールに渡す引数がツールの input_schema と一致することが保証されます。厳格モードを使用しない場合、モデルは型が正しくない引数（2 ではなく "2" など）を使用してツールを呼び出したり、必須フィールドを省略したりする可能性があります。これにより、ダウンストリーム関数が中断され、再試行ロジックが必要になることがあります。厳格モードが有効になっている場合、API は文法制約付きサンプリングを使用して、次のことを保証します。

  • ツール name は、常に提供されたツールの 1 つです。
  • ツール input は常にツールの input_schema に準拠します。

ツールのパラメータの検証、エージェント ワークフローの構築、型安全な関数呼び出しの確保、ネストされたプロパティを持つ複雑なツールの処理が必要な場合は、厳密なツール使用を使用します。

厳密なツール使用を有効にするには、ツール定義で "strict": true を最上位のフィールドとして name、description、input_schema とともに設定します。

REST

次のサンプルは、厳密な get_weather ツールを定義するリクエストを Agent Platform API に送信する方法を示しています。モデルは、location 文字列と、celsius または fahrenheit のいずれかである省略可能な unit を使用してツールを呼び出すことが保証されています。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: Anthropic Claude モデルをサポートするリージョン。グローバル エンドポイントを使用するには、グローバル エンドポイントを指定するをご覧ください。
  • MODEL: サポートされている Claude モデル（例: claude-opus-4-7）。
  • ROLE: メッセージに関連付けられたロール。最初のメッセージでは、user ロールを使用する必要があります。
  • CONTENT: user または assistant のメッセージの内容（テキストなど）。例: What is the weather in San Francisco?
  • MAX_TOKENS: レスポンスで生成できるトークンの最大数。トークンは約 3.5 文字です。100 トークンは約 60～80 語に相当します。

    レスポンスを短くしたい場合は小さい値を、長くしたい場合は大きい値を指定します。

  • STREAM: レスポンスがストリーミングされるかどうかを指定するブール値。レスポンスをストリーミングする場合は true、すべてのレスポンスを一度に戻すには false に設定します。

この例では、次の厳格なツール使用フィールドを使用します。各フィールドの詳細については、厳密なツール使用フィールドのセクションをご覧ください。

  • tools[].strict: true に設定すると、ツールの文法制約付きサンプリングが有効になるブール値。モデルは、input_schema と一致する引数を使用してツールを呼び出すことが保証されています。
  • tools[].input_schema: モデルがツールに渡すことができる引数を定義する JSON スキーマ。strict が true の場合、スキーマは JSON 出力の output_config スキーマと同じサポートされている JSON スキーマ サブセットに準拠している必要があります。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

リクエストの本文（JSON）: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, for example San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。tool_use コンテンツ ブロックには、キーと値の型がツールの input_schema と一致することが保証されている input フィールドが含まれています。

厳格なツールの使用フィールド

次のフィールドは、厳密なツール使用に固有のものです。他のツール定義フィールドについては、Anthropic のツールを定義するドキュメントをご覧ください。

  • tools[].strict: true に設定すると、ツールの文法制約付きサンプリングが有効になるブール値。strict が true の場合、モデルのツール入力は input_schema のスキーマと一致するように制約されます。デフォルト値は false です。

  • tools[].input_schema: モデルがツールに渡すことができる引数を定義する JSON スキーマ。strict が true の場合、スキーマは JSON 出力で使用される JSON スキーマのサブセットに準拠している必要があります。具体的には、以下のことを行う必要があります。

    • スキーマ内のすべてのオブジェクトで additionalProperties を false に設定します。
    • required 配列内のすべてのプロパティを一覧表示します。

    サポートされている機能とサポートされていない機能の完全なリストについては、Anthropic の JSON スキーマの制限事項に関するドキュメントをご覧ください。