Output strutturati con i modelli Anthropic Claude

Gli output strutturati ti consentono di vincolare l'output generato da un modello Claude in modo che corrisponda esattamente a uno schema JSON specifico. Ciò è utile per garantire che le risposte dei modelli Claude siano sempre nel formato preciso richiesto per applicazioni, database e pipeline di elaborazione downstream.

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

  • Output JSON (output_config.format): limita la risposta di testo del modello a un oggetto JSON che corrisponde a uno schema fornito. Utilizza questo strumento 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 type-safe nei flussi di lavoro degli agenti.

Per maggiori informazioni, consulta la documentazione di Anthropic Building with Claude: Structured Outputs e Strict tool use.

Modelli Anthropic Claude supportati

Gemini Enterprise Agent Platform supporta 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 abilitare gli output strutturati, devi configurare questo vincolo in modo da consentire esplicitamente la funzionalità structured_outputs.

Inoltre, puoi configurare il vincolo del criterio 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.

Invia 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 conformarsi la risposta del modello.

REST

Il seguente esempio mostra come inviare una richiesta all'API Agent Platform che estrae informazioni di contatto strutturate da un'email non strutturata. La risposta è limitata 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 funzionano con turni alternati user e assistant. Se l'ultimo messaggio utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questo parametro per vincolare una parte della risposta del modello.
  • CONTENT: i contenuti, ad esempio il testo del messaggio user o assistant. 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 equivale a circa 3,5 caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

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

L'esempio utilizza i seguenti campi di output strutturati. Per informazioni dettagliate 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: impostato su json_schema per limitare 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, 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 dell'API Claude messages.

  • 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 limitare 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 relativa alle limitazioni dello schema JSON di Anthropic. 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 e delle 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 gli strumenti in modo rigoroso

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

  • Lo strumento name è sempre uno di quelli che hai fornito.
  • Lo strumento input è sempre conforme al input_schema dello strumento.

Utilizza l'uso rigoroso degli strumenti quando devi convalidare i parametri degli strumenti, creare flussi di lavoro con agenti, garantire chiamate di funzioni sicure per il tipo o gestire strumenti complessi con proprietà nidificate.

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

REST

Il seguente esempio mostra come inviare una richiesta all'API Agent Platform che definisce uno strumento get_weather rigoroso. È garantito che il modello chiamerà lo strumento con una stringa location e un unit facoltativo che sia 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: i contenuti, ad esempio il testo del messaggio user o assistant. Ad esempio, What is the weather in San Francisco?
  • MAX_TOKENS: Numero massimo di token che possono essere generati nella risposta. Un token equivale a circa 3,5 caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

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

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

  • tools[].strict: un valore booleano che, se impostato su true, attiva il campionamento vincolato dalla grammatica per lo strumento. È garantito che il modello chiamerà 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 sottoinsieme dello schema JSON supportato 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, 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 blocco di contenuti tool_use contiene un campo input le cui chiavi e tipi di valori corrispondono sicuramente a input_schema dello strumento.

Campi di utilizzo degli strumenti rigorosi

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

  • tools[].strict: Un valore booleano che, se impostato su true, attiva il campionamento vincolato dalla grammatica 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:

    • Imposta additionalProperties su false per ogni oggetto dello schema.
    • Elenca ogni proprietà nell'array required.

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