Output strutturati con i modelli Anthropic Claude

Gli output strutturati ti consentono di vincolare l'output generato da un modello Claude in modo che sia conforme esattamente a uno schema JSON specifico. Questa funzionalità è utile per garantire che le risposte dei modelli Claude siano sempre nel formato preciso richiesto per applicazioni, database e pipeline di trattamento a valle.

Gli output strutturati forniscono due funzionalità complementari che puoi utilizzare in modo indipendente o insieme nella stessa richiesta:

  • Output JSON (output_config.format): vincola la risposta di testo del modello a un oggetto JSON che corrisponde a uno schema che fornisci. Utilizza questa opzione quando devi estrarre dati strutturati dal testo, generare report strutturati o formattare le risposte API.
  • Utilizzo rigoroso degli strumenti (tools[].strict): garantisce che gli argomenti che il modello passa a uno strumento corrispondano a input_schema dello strumento. Utilizza questa opzione quando hai bisogno di chiamate di funzioni con sicurezza dei tipi nei workflow agentici.

Per saperne di più, consulta la documentazione di Anthropic Creare con Claude: output strutturati e utilizzo rigoroso degli strumenti.

Modelli Anthropic Claude supportati

Gemini Enterprise Agent Platform supporta gli output strutturati per i seguenti modelli Anthropic Claude:

  • Claude Opus 4.7
  • Claude Sonnet 4.6
  • Claude Opus 4.6
  • (Disponibile a breve) Claude Opus 4.5
  • (Disponibile a breve) Claude Sonnet 4.5
  • (Disponibile a breve) Claude Haiku 4.5

Controllare l'accesso agli output strutturati

Per impostazione predefinita, gli output strutturati sono disattivati dal vincolo della policy dell'organizzazione constraints/vertexai.allowedPartnerModelFeatures. Per attivare gli output strutturati, devi configurare questo vincolo in modo da consentire esplicitamente la funzionalità structured_outputs.

Inoltre, puoi configurare il vincolo della policy dell'organizzazione constraints/vertexai.allowedModels per limitare l'accesso ai modelli Claude.

Per istruzioni dettagliate sulla configurazione dei vincoli delle policy dell'organizzazione, consulta Controllare l'accesso ai modelli di Model Garden.

Inviare una richiesta di output strutturato

Per richiedere un output JSON, invia una richiesta POST all'endpoint del modello del publisher e includi il parametro output_config nel corpo della richiesta. Il parametro output_config specifica lo schema JSON a cui deve essere conforme la risposta del modello.

REST

L'esempio seguente mostra come inviare una richiesta all'API Agent Platform che estrae informazioni di contatto strutturate da un'email non strutturata. La risposta è vincolata a un oggetto JSON con i campi name, email, plan_interest e demo_requested.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • LOCATION: una regione che supporta i modelli Anthropic Claude. Per utilizzare l' endpoint globale, consulta Specificare l'endpoint globale.
  • MODEL: un modello Claude supportato, ad esempio claude-opus-4-7.
  • ROLE: il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli Claude operano con turni alternati di user e assistant. Se il messaggio finale utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questa opzione per vincolare una parte della risposta del modello.
  • CONTENT: il contenuto, ad esempio testo, del user o assistant messaggio. Ad esempio, 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: Numero massimo di token che possono essere generati nella risposta. Un token è composto da circa 3,5 caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore inferiore per le risposte più brevi e un valore superiore per le risposte potenzialmente più lunghe.

  • STREAM: un valore booleano che specifica se la risposta viene trasmessa in streaming o meno. Imposta su true per trasmettere la risposta in streaming e su false per restituire la risposta contemporaneamente. Gli output strutturati vengono in genere restituiti con false.

L'esempio utilizza i seguenti campi di output strutturati. Per dettagli su ogni campo, consulta la sezione Campi della richiesta.

  • output_config: il blocco di configurazione di primo livello che controlla la struttura della risposta del modello.
  • output_config.format.type: imposta su json_schema per vincolare la risposta a un oggetto JSON conforme allo schema fornito.
  • output_config.format.schema: uno schema JSON che definisce la struttura richiesta della risposta del modello. Lo schema deve essere conforme al sottoinsieme dello schema JSON supportato.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "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
      }
    }
  }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente. Il campo text del blocco content contiene una stringa JSON conforme allo schema specificato in output_config.

Campi della richiesta

I seguenti campi sono specifici per gli output JSON. Per informazioni sugli altri campi della richiesta, consulta il riferimento API dei messaggi Claude.

  • output_config: il blocco di configurazione di primo livello che controlla la struttura della risposta del modello.
  • output_config.format: la definizione del formato per l'output. È supportato solo il tipo json_schema.
  • output_config.format.type: il tipo di formato di output da applicare. Imposta questo valore su json_schema per vincolare la risposta a un oggetto JSON.

  • output_config.format.schema: uno schema JSON che definisce la struttura richiesta della risposta del modello. Gli output strutturati supportano lo schema JSON standard con alcune limitazioni, ad esempio richiedono che additionalProperties sia impostato su false per gli oggetti e non supportano vincoli numerici o di lunghezza delle stringhe. Per l'elenco completo delle funzionalità supportate e non supportate, consulta la documentazione di Anthropic Limitazioni dello schema JSON. All'interno dello schema, in genere specifichi:

    • type: il tipo JSON del valore a questo livello (più comunemente object per lo schema radice).
    • properties: una mappa dei nomi dei campi alle relative definizioni dei tipi, che descrivono ogni campo che il modello deve restituire.
    • required: un elenco di nomi di proprietà che il modello deve includere nella risposta.
    • additionalProperties: un valore booleano che, se impostato su false, impedisce al modello di includere campi non dichiarati in properties.

Utilizzare l'utilizzo rigoroso degli strumenti

L'utilizzo rigoroso degli strumenti garantisce che gli argomenti che il modello passa a uno strumento corrispondano a input_schema dello strumento. Senza la modalità StrictMode, il modello potrebbe chiamare uno strumento con argomenti di tipo errato (ad esempio, "2" anziché 2) o omettere i campi obbligatori, il che può interrompere le funzioni a valle e richiedere una logica di ripetizione. Con la modalità StrictMode attivata, l'API utilizza il campionamento con vincoli grammaticali per garantire che:

  • Il name dello strumento sia sempre uno degli strumenti forniti.
  • Lo strumento input sia sempre conforme a input_schema dello strumento.

Utilizza l'utilizzo rigoroso degli strumenti quando devi convalidare i parametri degli strumenti, creare workflow agentici, garantire chiamate di funzioni con sicurezza dei tipi o gestire strumenti complessi con proprietà nidificate.

Per attivare l'utilizzo rigoroso degli strumenti, imposta "strict": true come campo di primo livello nella tua definizione dello strumento, insieme a name, description e input_schema.

REST

L'esempio seguente mostra come inviare una richiesta all'API Agent Platform che definisce uno strumento get_weather rigoroso. Il modello è garantito per chiamare lo strumento con una stringa location e un unit facoltativo che può essere celsius o fahrenheit.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • LOCATION: una regione che supporta i modelli Anthropic Claude. Per utilizzare l' endpoint globale, consulta Specificare l'endpoint globale.
  • MODEL: un modello Claude supportato, ad esempio claude-opus-4-7.
  • ROLE: il ruolo associato a un messaggio. Il primo messaggio deve utilizzare il ruolo user.
  • CONTENT: il contenuto, ad esempio testo, del user o assistant messaggio. Ad esempio, What is the weather in San Francisco?
  • MAX_TOKENS: Numero massimo di token che possono essere generati nella risposta. Un token è composto da circa 3,5 caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore inferiore per le risposte più brevi e un valore superiore per le risposte potenzialmente più lunghe.

  • STREAM: un valore booleano che specifica se la risposta viene trasmessa in streaming o meno. Imposta su true per trasmettere la risposta in streaming e su false per restituire la risposta contemporaneamente.

L'esempio utilizza i seguenti campi di utilizzo rigoroso degli strumenti. Per dettagli su ogni campo, consulta la sezione Campi di utilizzo rigoroso degli strumenti.

  • tools[].strict: un valore booleano che, se impostato su true, attiva il campionamento con vincoli grammaticali per lo strumento. Il modello è garantito per chiamare lo strumento con argomenti che corrispondono a input_schema.
  • tools[].input_schema: uno schema JSON che definisce gli argomenti che il modello può passare allo strumento. Quando strict è true, lo schema deve essere conforme allo stesso supportato sottoinsieme dello schema JSON dello schema output_config per gli output JSON.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "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
      }
    }
  ]
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente. Il tool_use blocco di contenuti contiene un campo input le cui chiavi e tipi di valori corrispondono a input_schema dello strumento.

Campi di utilizzo rigoroso degli strumenti

I seguenti campi sono specifici per l'utilizzo rigoroso degli strumenti. Per informazioni sugli altri campi di definizione degli strumenti, consulta la documentazione di Anthropic Definire gli strumenti.

  • tools[].strict: un valore booleano che, se impostato su true, attiva il campionamento con vincoli grammaticali per lo strumento. Quando strict è true, l'input dello strumento del modello è vincolato in modo che corrisponda allo schema in input_schema. Il valore predefinito è false.

  • tools[].input_schema: uno schema JSON che definisce gli argomenti che il modello può passare allo strumento. Quando strict è true, lo schema deve essere conforme allo stesso sottoinsieme dello schema JSON utilizzato dagli output JSON. In particolare, devi:

    • Impostare additionalProperties su false in ogni oggetto dello schema.
    • Elencare ogni proprietà nell'array required.

    Per l'elenco completo delle funzionalità supportate e non supportate, consulta la documentazione di Anthropic Limitazioni dello schema JSON.