Output terstruktur dengan model Claude dari Anthropic

Output terstruktur memungkinkan Anda membatasi output yang dihasilkan model Claude agar sesuai persis dengan skema JSON tertentu. Hal ini berguna untuk memastikan bahwa respons dari model Claude Anda selalu dalam format yang tepat dan diperlukan untuk aplikasi, database, dan pipeline pemrosesan downstream.

Output terstruktur menyediakan dua fitur pelengkap yang dapat Anda gunakan secara terpisah atau bersama-sama dalam permintaan yang sama:

  • Output JSON (output_config.format): Membatasi respons teks model ke objek JSON yang cocok dengan skema yang Anda berikan. Gunakan fitur ini saat Anda perlu mengekstrak data terstruktur dari teks, membuat laporan terstruktur, atau memformat respons API.
  • Penggunaan alat yang ketat (tools[].strict): Menjamin bahwa argumen yang diteruskan model ke alat cocok dengan input_schema alat. Gunakan fitur ini saat Anda memerlukan panggilan fungsi yang aman untuk jenis dalam alur kerja agen.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi Anthropic's Building with Claude: Structured Outputs and Strict tool use.

Model Anthropic Claude yang didukung

Gemini Enterprise Agent Platform mendukung output terstruktur untuk semua model Anthropic Claude 4.5 dan yang lebih baru.

Mengontrol akses ke output terstruktur

Secara default, output terstruktur dinonaktifkan oleh batasan kebijakan organisasi constraints/vertexai.allowedPartnerModelFeatures. Untuk mengaktifkan output terstruktur, Anda harus mengonfigurasi batasan ini agar secara eksplisit mengizinkan fitur structured_outputs.

Selain itu, Anda dapat mengonfigurasi batasan kebijakan organisasi constraints/vertexai.allowedModels untuk membatasi akses ke model Claude.

Untuk mengetahui petunjuk mendetail tentang cara mengonfigurasi batasan kebijakan organisasi, lihat Mengontrol akses ke model Model Garden.

Mengirim permintaan output terstruktur

Untuk meminta output JSON, kirim permintaan POST ke endpoint model penayang dan sertakan parameter output_config dalam isi permintaan Anda. Parameter output_config menentukan skema JSON yang harus dipatuhi oleh respons model.

REST

Contoh berikut menunjukkan cara mengirim permintaan ke Agent Platform API yang mengekstrak informasi kontak terstruktur dari email yang tidak terstruktur. Respons dibatasi ke objek JSON dengan kolom name, email, plan_interest, dan demo_requested.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Region yang mendukung model Anthropic Claude. Untuk menggunakan the global endpoint, lihat Specify the global endpoint.
  • MODEL: Model Claude yang didukung, misalnya claude-opus-4-7.
  • ROLE: Peran yang terkait dengan sebuah pesan. Anda dapat menentukan user atau assistant. Pesan pertama harus menggunakan peran user. Model Claude beroperasi dengan pergantian giliran user dan assistant. Jika pesan terakhir menggunakan peran assistant, konten respons akan langsung dilanjutkan dari konten dalam pesan tersebut. Anda dapat menggunakan hal ini untuk membatasi sebagian respons model.
  • CONTENT: Konten, seperti teks, dari pesan user atau assistant. Misalnya, 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: Jumlah maksimum token yang dapat dibuat dalam respons. Token terdiri dari sekitar 3,5 karakter. 100 token setara dengan sekitar 60-80 kata.

    Tentukan nilai yang lebih rendah untuk respons yang lebih singkat dan nilai yang lebih tinggi untuk respons yang berpotensi lebih panjang.

  • STREAM: Boolean yang menentukan apakah respons di-streaming atau tidak. Tetapkan ke true untuk men-streaming respons dan false untuk menampilkan respons sekaligus. Output terstruktur biasanya ditampilkan dengan false.

Contoh ini menggunakan kolom output terstruktur berikut. Untuk mengetahui detail setiap kolom, lihat bagian Kolom permintaan

  • output_config: Blok konfigurasi tingkat atas yang mengontrol struktur respons model.
  • output_config.format.type: Tetapkan ke json_schema untuk membatasi respons ke objek JSON yang sesuai dengan skema yang disediakan.
  • output_config.format.schema: Skema JSON yang menentukan struktur respons model yang diperlukan. Skema harus sesuai dengan subset Skema JSON yang didukung.

Metode HTTP dan URL: 

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

Meminta isi 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
      }
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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

Anda akan menerima respons JSON yang mirip dengan berikut ini. Kolom text dari blok content berisi string JSON yang sesuai dengan skema yang Anda tentukan di output_config.

Kolom permintaan

Kolom berikut khusus untuk output JSON. Untuk mengetahui informasi tentang kolom permintaan lainnya, lihat referensi Claude messages API.

  • output_config: Blok konfigurasi tingkat atas yang mengontrol struktur respons model.
  • output_config.format: Definisi format untuk output. Hanya jenis json_schema yang didukung.
  • output_config.format.type: Jenis format output yang akan diterapkan. Tetapkan ke json_schema untuk membatasi respons ke objek JSON.

  • output_config.format.schema: Skema JSON yang menentukan struktur respons model yang diperlukan. Output terstruktur mendukung Skema JSON standar dengan beberapa batasan, seperti mengharuskan additionalProperties ditetapkan ke false untuk objek dan tidak mendukung batasan numerik atau panjang string. Untuk mengetahui daftar lengkap fitur yang didukung dan tidak didukung, lihat dokumentasibatasan Skema JSON Anthropic. Dalam skema, Anda biasanya menentukan:

    • type: Jenis JSON dari nilai di tingkat ini (paling umum adalah object untuk skema root).
    • properties: Peta nama kolom ke definisi jenisnya, yang menjelaskan setiap kolom yang harus ditampilkan model.
    • required: Daftar nama properti yang harus disertakan model dalam responsnya.
    • additionalProperties: Boolean yang, jika ditetapkan ke false, mencegah model menyertakan kolom apa pun yang tidak dideklarasikan dalam properties.

Menggunakan penggunaan alat yang ketat

Penggunaan alat yang ketat memastikan bahwa argumen yang diteruskan model ke alat cocok dengan input_schema alat. Tanpa mode ketat, model mungkin memanggil alat dengan argumen yang salah jenisnya (misalnya, "2" bukan 2) atau menghilangkan kolom yang diperlukan, yang dapat merusak fungsi downstream dan memerlukan logika coba lagi. Dengan mode ketat diaktifkan, API menggunakan pengambilan sampel yang dibatasi tata bahasa untuk memastikan bahwa:

  • name alat selalu merupakan salah satu alat yang Anda berikan.
  • Alat input selalu sesuai dengan input_schema alat.

Gunakan penggunaan alat yang ketat saat Anda perlu memvalidasi parameter alat, membuat alur kerja agen, memastikan panggilan fungsi yang aman untuk jenis, atau menangani alat kompleks dengan properti bertingkat.

Untuk mengaktifkan penggunaan alat yang ketat, tetapkan "strict": true sebagai kolom tingkat atas dalam definisi alat Anda, bersama dengan name, description, dan input_schema.

REST

Contoh berikut menunjukkan cara mengirim permintaan ke Agent Platform API yang menentukan alat get_weather yang ketat. Model dijamin akan memanggil alat dengan string location dan unit opsional yang berupa celsius atau fahrenheit.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Region yang mendukung model Anthropic Claude. Untuk menggunakan the global endpoint, lihat Specify the global endpoint.
  • MODEL: Model Claude yang didukung, misalnya claude-opus-4-7.
  • ROLE: Peran yang terkait dengan sebuah pesan. Pesan pertama harus menggunakan peran user.
  • CONTENT: Konten, seperti teks, dari pesan user atau assistant. Misalnya, What is the weather in San Francisco?
  • MAX_TOKENS: Jumlah maksimum token yang dapat dibuat dalam respons. Token terdiri dari sekitar 3,5 karakter. 100 token setara dengan sekitar 60-80 kata.

    Tentukan nilai yang lebih rendah untuk respons yang lebih singkat dan nilai yang lebih tinggi untuk respons yang berpotensi lebih panjang.

  • STREAM: Boolean yang menentukan apakah respons di-streaming atau tidak. Tetapkan ke true untuk men-streaming respons dan false untuk menampilkan respons sekaligus.

Contoh ini menggunakan kolom penggunaan alat yang ketat berikut. Untuk mengetahui detail setiap kolom, lihat bagian Kolom penggunaan alat yang ketat.

  • tools[].strict: Boolean yang, jika ditetapkan ke true, mengaktifkan pengambilan sampel yang dibatasi tata bahasa untuk alat. Model dijamin akan memanggil alat dengan argumen yang cocok dengan input_schema.
  • tools[].input_schema: Skema JSON yang menentukan argumen yang dapat diteruskan model ke alat. Jika strict adalah true, skema harus sesuai dengan subset Skema JSON yang sama dengan skema output_config untuk output JSON yang didukung.

Metode HTTP dan URL: 

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

Meminta isi 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
      }
    }
  ]
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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

Anda akan menerima respons JSON yang mirip dengan berikut ini. Blok konten tool_use berisi kolom input yang kunci dan jenis nilainya dijamin cocok dengan input_schema alat.

Kolom penggunaan alat yang ketat

Kolom berikut khusus untuk penggunaan alat yang ketat. Untuk mengetahui informasi tentang kolom definisi alat lainnya, lihat dokumentasi Anthropic's Define tools.

  • tools[].strict: Boolean yang, jika ditetapkan ke true, mengaktifkan pengambilan sampel yang dibatasi tata bahasa untuk alat. Jika strict adalah true, input alat model dibatasi agar cocok dengan skema di input_schema. Nilai defaultnya adalah false.

  • tools[].input_schema: Skema JSON yang menentukan argumen yang dapat diteruskan model ke alat. Jika strict adalah true, skema harus sesuai dengan subset Skema JSON yang sama dengan yang digunakan output JSON. Secara khusus, Anda harus:

    • Tetapkan additionalProperties ke false pada setiap objek dalam skema.
    • Cantumkan setiap properti dalam array required.

    Untuk mengetahui daftar lengkap fitur yang didukung dan tidak didukung, lihat dokumentasi batasan Skema JSON Anthropic.