---
title: Output strutturati
url: https://platform.claude.com/docs/it/build-with-claude/structured-outputs
description: Ottieni risultati JSON convalidati dai flussi di lavoro degli agenti
featureMetadata:
  status: stable
  zdr:
    eligibility: qualified
    note: "Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). I tuoi prompt e gli output di Claude non vengono archiviati. Solo lo JSON schema viene memorizzato nella cache, per un massimo di 24 ore dall’ultimo utilizzo. Ciò copre anche l’uso rigoroso degli strumenti (`strict: true` sugli strumenti), che usa la stessa pipeline grammaticale."
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Amazon Bedrock: stable
    Amazon Bedrock (bedrock-runtime): stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Claude Models on Google Cloud (Google managed): stable
    Microsoft Foundry: stable
---

Gli “structured outputs” (output strutturati) vincolano le risposte di Claude a seguire uno schema specifico, garantendo un output valido e analizzabile per l’elaborazione a valle. Gli output strutturati forniscono due funzionalità complementari:

* **Output JSON** (`output_config.format`): ottieni la risposta di Claude in un formato JSON specifico, ad esempio per estrarre dati da immagini o testo, generare report strutturati o formattare risposte API. Questa pagina tratta gli output JSON.
* **Uso rigoroso degli strumenti** (`strict: true`): garantisci la convalida dello schema sui nomi e sugli input degli strumenti. Consulta [Uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use).

Puoi usare queste funzionalità in modo indipendente oppure [insieme nella stessa richiesta](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#using-both-features-together).

## Perché usare gli output strutturati

Senza output strutturati, Claude può generare risposte JSON malformate o input di strumenti non validi che interrompono le tue applicazioni. Anche con un prompting accurato, potresti incontrare:

* Errori di parsing dovuti a sintassi JSON non valida
* Campi obbligatori mancanti
* Tipi di dati incoerenti
* Violazioni dello schema che richiedono gestione degli errori e nuovi tentativi

Gli output strutturati garantiscono risposte conformi allo schema tramite “constrained decoding” (decodifica vincolata):

* **Sempre validi:** nessun errore di parsing JSON
* **Type safe:** tipi dei campi e campi obbligatori garantiti
* **Affidabili:** nessun nuovo tentativo necessario per violazioni dello schema

## Come funziona

<Steps>
  <Step title="Definisci il tuo schema">
    Descrivi la struttura che desideri come JSON schema o come tipo nel tuo linguaggio. Lo schema segue JSON Schema, con alcune [limitazioni](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#json-schema-limitations).
  </Step>

  <Step title="Invialo in output_config.format">
    La richiesta contiene lo schema in `output_config.format` con `type: "json_schema"`. Gli helper dell’SDK lo impostano per te.
  </Step>

  <Step title="Leggi la risposta">
    Claude restituisce JSON valido che corrisponde al tuo schema nel blocco di contenuto testuale della risposta. Gli helper dell’SDK lo analizzano nel tuo tipo.
  </Step>
</Steps>

## Utilizzo

<Tabs>
  <Tab title="cURL">
    ```bash
    curl https://api.anthropic.com/v1/messages \
      -H "content-type: application/json" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2026-10-21" \
      -d '{
        "model": "claude-opus-5-5",
        "max_tokens": 1024,
        "messages": [
          {
            "role": "user",
            "content": "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."
          }
        ],
        "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
            }
          }
        }
      }'
    ```

    Claude restituisce JSON come questo nel blocco di contenuto testuale della risposta:

    ```json Output
    {
      "name": "John Smith",
      "email": "john@example.com",
      "plan_interest": "Enterprise",
      "demo_requested": true
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash
    ant messages create <<'YAML'
    model: claude-opus-5-5
    max_tokens: 1024
    messages:
      - role: user
        content: >-
          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.
    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
    YAML
    ```

    Claude restituisce JSON come questo nel blocco di contenuto testuale della risposta:

    ```json Output
    {
      "name": "John Smith",
      "email": "john@example.com",
      "plan_interest": "Enterprise",
      "demo_requested": true
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python
    from pydantic import BaseModel
    # ...


    class ContactInfo(BaseModel):
        name: str
        email: str
        plan_interest: str
        demo_requested: bool


    client = Anthropic()

    response = client.messages.parse(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": (
                    "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."
                ),
            }
        ],
        output_format=ContactInfo,
    )

    print(response.parsed_output)
    ```

    Passa un modello [Pydantic](https://docs.pydantic.dev/) a `client.messages.parse()`, il metodo consigliato, come `output_format`. L’SDK trasforma lo schema del modello, lo invia come `output_config.format`, convalida la risposta e restituisce il modello analizzato in `parsed_output`.

    L’esempio precedente produce:

    ```text Output wrap
    name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True
    ```

    Se conosci le chiavi di un campo, usa un modello Pydantic annidato, non un `dict`. L’SDK invia un campo `dict` come oggetto con `properties` vuoto, quindi Claude può restituire solo `{}` per quel campo. Se non conosci le chiavi in anticipo, consulta [Oggetti con chiavi arbitrarie](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#objects-with-arbitrary-keys).
  </Tab>

  <Tab title="TypeScript">
    ```typescript
    import { z } from "zod";
    import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

    const ContactInfoSchema = z.object({
      name: z.string(),
      email: z.string(),
      plan_interest: z.string(),
      demo_requested: z.boolean()
    });

    const client = new Anthropic();

    const response = await client.messages.parse({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      messages: [
        {
          role: "user",
          content:
            "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."
        }
      ],
      output_config: { format: zodOutputFormat(ContactInfoSchema) }
    });

    // Analizzato e convalidato automaticamente
    console.log(response.parsed_output);
    ```

    Racchiudi uno schema [Zod](https://zod.dev/) in `zodOutputFormat()` e passalo a `client.messages.parse()` come `output_config.format`. `zodOutputFormat()` trasforma lo schema e `parse()` convalida la risposta e restituisce il risultato analizzato in `parsed_output`, tipizzato in modo da corrispondere allo schema.

    L’esempio precedente produce:

    ```text Output wrap
    {
      name: 'John Smith',
      email: 'john@example.com',
      plan_interest: 'Enterprise',
      demo_requested: true
    }
    ```

    Se conosci le chiavi di un campo, usa `z.object()`, non `z.record()`. L’SDK invia un campo `z.record()` come oggetto con `properties` vuoto, quindi Claude può restituire solo `{}` per quel campo. Se non conosci le chiavi in anticipo, consulta [Oggetti con chiavi arbitrarie](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#objects-with-arbitrary-keys).
  </Tab>

  <Tab title="C#">
    ```csharp
    using Anthropic;
    using Anthropic.Models.Messages;
    using Anthropic.Services;

    var client = new AnthropicClient();

    var response = await client.Messages.Create<ContactInfo>(new MessageCreateParams
    {
        Model = Model.ClaudeOpus5_5,
        MaxTokens = 1024,
        Messages = [
            new UserMessageParam
            {
                Content = "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."
            }
        ],
    });

    if (response.Content.Select(block => block.Parsed()).OfType<ContactInfo>().FirstOrDefault() is { } contact)
    {
        Console.WriteLine(contact);
    }

    public record ContactInfo
    {
        public string Name { get; set; } = "";
        public string Email { get; set; } = "";
        public string PlanInterest { get; set; } = "";
        public bool DemoRequested { get; set; }
    }
    ```

    Passa una semplice classe o record C# all’overload generico `Create<T>()`. L’SDK deriva un JSON schema dal tipo, lo trasforma e analizza ogni blocco di testo riconvertendolo in quel tipo.

    L’esempio precedente produce:

    ```text Output wrap
    ContactInfo { Name = John Smith, Email = john@example.com, PlanInterest = Enterprise, DemoRequested = True }
    ```
  </Tab>

  <Tab title="Go">
    ```go
    type ContactInfo struct {
    	Name          string `json:"name"`
    	Email         string `json:"email"`
    	PlanInterest  string `json:"plan_interest"`
    	DemoRequested bool   `json:"demo_requested"`
    }

    func main() {
    	client := anthropic.NewClient()

    	var contact ContactInfo
    	_, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{
    		Model:     anthropic.ModelClaudeOpus5_5,
    		MaxTokens: 1024,
    		Messages: []anthropic.BetaMessageParam{
    			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(
    				"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.",
    			)),
    		},
    		OutputConfig: anthropic.BetaOutputConfigParam{
    			Format: anthropic.BetaJSONOutputFormatParam{Schema: &contact},
    		},
    	})
    	if err != nil {
    		panic(err)
    	}

    	fmt.Printf("%#v\n", contact)
    }
    ```

    <Note>
      Passare una struct come schema è in beta in Go, quindi questo esempio usa `client.Beta.Messages.New`. Per usare la versione stabile `client.Messages.New`, passa un JSON schema come mostrato in [Usare un JSON schema grezzo](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#using-a-raw-json-schema).
    </Note>

    L’SDK genera e trasforma il JSON schema a partire dalla struct e deserializza la risposta al suo interno.

    L’esempio precedente produce:

    ```text Output wrap
    main.ContactInfo{Name:"John Smith", Email:"john@example.com", PlanInterest:"Enterprise", DemoRequested:true}
    ```
  </Tab>

  <Tab title="Java">
    ```java
    static class ContactInfo {
        public String name;
        public String email;
        public String plan_interest;
        public boolean demo_requested;
    }

    void main() throws Exception {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        StructuredMessageCreateParams<ContactInfo> params = MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_5_5)
            .maxTokens(1024)
            .addUserMessage("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.")
            .outputConfig(ContactInfo.class)
            .build();

        StructuredMessage<ContactInfo> response = client.messages().create(params);
        ContactInfo contact = response.content().stream()
            .flatMap(block -> block.text().stream())
            .findFirst().orElseThrow().text();
        IO.println(new ObjectMapper().writeValueAsString(contact));
    }
    ```

    Quando passi una classe Java a `outputConfig()`, l’SDK ne deriva un JSON schema e convalida lo schema. Il builder produce quindi un `StructuredMessageCreateParams<T>`. Invece di trasformare lo schema, la convalida locale dell’SDK rifiuta i [vincoli non supportati dall’API](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#json-schema-limitations). Leggi il risultato analizzato con `response.content().stream().flatMap(block -> block.text().stream()).findFirst().orElseThrow().text()`.

    L’esempio precedente produce:

    ```json Output
    {"name":"John Smith","email":"john@example.com","plan_interest":"Enterprise","demo_requested":true}
    ```

    <Note>
      Dichiara le classi del tuo schema come classi di primo livello o classi annidate `static`. Questo requisito deriva dalla libreria Jackson Databind (`com.fasterxml.jackson.databind`), che l’SDK usa per deserializzare le risposte JSON nelle istanze delle tue classi e che non può istanziare classi interne non statiche.
    </Note>

    <Accordion title="Cancellazione dei tipi generici">
      Java conserva le informazioni sui tipi generici per i campi nei metadati della classe, ma la “type erasure” (cancellazione dei tipi) generica si applica in altri ambiti. Sebbene sia possibile derivare un JSON schema da un campo `BookList.books` di tipo `List<Book>`, non è possibile derivare un JSON schema valido da una variabile locale dello stesso tipo.

      Se si verifica un errore durante la conversione di una risposta JSON in un’istanza di una classe Java, il messaggio di errore include la risposta JSON per facilitare la diagnosi. Se la tua risposta JSON potrebbe contenere informazioni sensibili, evita di registrarla direttamente nei log oppure assicurati di oscurare eventuali dettagli sensibili dal messaggio di errore.
    </Accordion>

    <Accordion title="Convalida locale dello schema">
      Gli output strutturati supportano un [sottoinsieme del linguaggio JSON Schema](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#json-schema-limitations). L’SDK genera automaticamente gli schemi dalle classi in modo da allinearli a questo sottoinsieme. Il metodo `outputConfig(Class<T>)` esegue un controllo di convalida sullo schema derivato dalla classe specificata.

      Punti chiave:

      * **Convalida locale:** l’SDK convalida lo schema senza inviare una richiesta.
      * **Convalida remota:** anche l’API convalida il JSON schema quando riceve la richiesta.
      * **Compatibilità delle versioni:** se la versione dell’SDK è obsoleta, la convalida locale potrebbe rifiutare uno schema che la convalida remota accetta.
      * **Disabilitare la convalida locale:** passa `JsonSchemaLocalValidation.NO` se riscontri problemi di compatibilità:

      ```java
      import com.anthropic.core.JsonSchemaLocalValidation;
      // ...

      static class BookList {
          public List<String> books;
      }

      void main() {
          StructuredMessageCreateParams<BookList> createParams = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(2048)
              .outputConfig(BookList.class, JsonSchemaLocalValidation.NO)
              .addUserMessage("List some famous late twentieth century novels.")
              .build();
      }
      ```
    </Accordion>

    <Accordion title="Streaming">
      Gli output strutturati funzionano anche con lo streaming. Poiché le risposte arrivano sotto forma di eventi di stream, devi accumulare la risposta completa prima di deserializzare il JSON.

      Usa `MessageAccumulator` per raccogliere le stringhe JSON dallo stream. Una volta accumulate, chiama `MessageAccumulator.message(Class<T>)` per convertire il `Message` accumulato in uno `StructuredMessage`, che deserializza automaticamente il JSON nella tua classe Java.
    </Accordion>

    <Accordion title="Proprietà del JSON schema">
      Quando l’SDK deriva un JSON schema dalle tue classi Java, per impostazione predefinita include tutte le proprietà rappresentate da campi `public` o metodi getter `public` ed esclude i campi e i metodi getter non `public`.

      Puoi controllare la visibilità con le annotazioni:

      * `@JsonIgnore` esclude un campo o un metodo getter `public`.
      * `@JsonProperty` include un campo o un metodo getter non `public`.

      Se definisci campi `private` con metodi getter `public`, l’SDK deriva il nome della proprietà dal getter (ad esempio, il campo `private` `myValue` con il metodo `public` `getMyValue()` produce una proprietà `"myValue"`). Per usare un nome di getter non convenzionale, annota il metodo con `@JsonProperty`.

      Ogni classe deve definire almeno una proprietà per il JSON schema. Si verifica un errore di convalida se nessun campo o metodo getter può produrre proprietà dello schema, ad esempio quando:

      * Non ci sono campi o metodi getter nella classe
      * Tutti i membri `public` sono annotati con `@JsonIgnore`
      * Tutti i membri non `public` sono privi di annotazioni `@JsonProperty`
      * Un campo usa un tipo `Map`, che produce un campo `"properties"` vuoto (per evitarlo, consulta [Oggetti con chiavi arbitrarie](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#objects-with-arbitrary-keys))
    </Accordion>

    <Accordion title="Composizione ed ereditarietà">
      Le tue classi Java possono usare la composizione e l’ereditarietà per condividere la struttura quando definisci i JSON schema. Ciascun pattern influisce in modo diverso sulla struttura dell’output.

      La **composizione** produce un output JSON annidato. Derivando uno schema dalla classe `Composed` che compone `A` e `B`:

      ```java
      static class A {
          public String a;
      }

      static class B {
          public String b;
      }

      static class Composed {
          public A composedA;
          public B composedB;
      }
      ```

      L’output JSON ha questa struttura annidata:

      ```json Output
      {
        "composedA": { "a": "hello" },
        "composedB": { "b": "world" }
      }
      ```

      L’**ereditarietà** produce un output JSON piatto. Derivando uno schema dalla classe `Derived` che estende `Base`:

      ```java
      static class Base {
          public String a;
      }

      static class Derived extends Base {
          public String b;
      }
      ```

      L’output JSON ha questa struttura piatta:

      ```json Output
      {
        "a": "hello",
        "b": "world"
      }
      ```
    </Accordion>

    <Accordion title="Annotazioni (Jackson e Swagger)">
      Puoi usare le annotazioni di Jackson Databind per arricchire il JSON schema derivato dalle tue classi Java:

      ```java
      import com.fasterxml.jackson.annotation.JsonClassDescription;
      import com.fasterxml.jackson.annotation.JsonIgnore;
      import com.fasterxml.jackson.annotation.JsonPropertyDescription;

      static class Person {

          @JsonPropertyDescription("The first name and surname of the person")
          public String name;

          public int birthYear;

          @JsonPropertyDescription("The year the person died, or 'present' if the person is living.")
          public String deathYear;
      }

      @JsonClassDescription("The details of one published book")
      static class Book {

          public String title;
          public Person author;

          @JsonPropertyDescription("The year in which the book was first published.")
          public int publicationYear;

          @JsonIgnore
          public String genre;
      }

      static class BookList {
          public List<Book> books;
      }
      ```

      Riepilogo delle annotazioni:

      * `@JsonClassDescription`: aggiunge una descrizione a una classe
      * `@JsonPropertyDescription`: aggiunge una descrizione a un campo o a un metodo getter
      * `@JsonIgnore`: esclude un campo o un getter `public` dallo schema
      * `@JsonProperty`: include un campo o un getter non `public` nello schema

      Se usi `@JsonProperty(required = false)`, l’SDK ignora il valore `false`. Gli schemi derivati dalle classi contrassegnano sempre tutte le proprietà come obbligatorie.

      Puoi anche usare le annotazioni `@Schema` e `@ArraySchema` di Swagger Core (OpenAPI 3) per vincoli specifici del tipo:

      ```java
      import io.swagger.v3.oas.annotations.media.ArraySchema;
      import io.swagger.v3.oas.annotations.media.Schema;

      static class Article {

          @ArraySchema(minItems = 1)
          public List<String> authors;

          public String title;

          @Schema(format = "date")
          public String publicationDate;

          public int pageCount;
      }
      ```

      La convalida locale verifica che tu non abbia usato parole chiave di vincolo non supportate, ma i valori dei vincoli non vengono convalidati localmente. Ad esempio, un valore `"format"` non supportato potrebbe superare la convalida locale ma causare un errore remoto.

      Se usi sia le annotazioni Jackson sia quelle Swagger per impostare lo stesso campo dello schema, l’annotazione Jackson ha la precedenza.
    </Accordion>
  </Tab>

  <Tab title="PHP">
    ```php
    use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
    use Anthropic\Lib\Contracts\StructuredOutputModel;

    $client = new Client();

    class ContactInfo implements StructuredOutputModel
    {
        use StructuredOutputModelTrait;

        public string $name;
        public string $email;
        public string $plan_interest;
        public bool $demo_requested;
    }

    $message = $client->messages->create(
        maxTokens: 1024,
        messages: [
            [
                'role' => 'user',
                'content' => '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.',
            ],
        ],
        model: 'claude-opus-5-5',
        outputConfig: ['format' => ContactInfo::class],
    );

    $contact = $message->parsedOutput();
    if ($contact instanceof ContactInfo) {
        var_dump($contact);
    }
    ```

    Definisci una classe che implementa `StructuredOutputModel` e usa `StructuredOutputModelTrait`, e passa il suo nome in `outputConfig: ['format' => MyClass::class]`. L’SDK deriva un JSON schema dai tipi delle proprietà PHP 8 della classe, lo trasforma e restituisce un’istanza tipizzata da `$message->parsedOutput()`.

    `parsedOutput()` restituisce l’istanza del tuo modello in caso di successo, oppure `null` (o un array di errori) se il parsing non riesce. Usa `instanceof` per restringere il tipo prima di accedere ai campi.

    L’esempio precedente produce:

    ```text Output wrap
    object(ContactInfo)#42 (4) {
      ["name"]=>
      string(10) "John Smith"
      ["email"]=>
      string(16) "john@example.com"
      ["plan_interest"]=>
      string(10) "Enterprise"
      ["demo_requested"]=>
      bool(true)
    }
    ```

    <Accordion title="Inferenza dei tipi">
      L’SDK mappa i tipi nativi delle proprietà PHP 8 su JSON Schema:

      | Tipo PHP                                      | JSON Schema                       |
      | --------------------------------------------- | --------------------------------- |
      | `string`                                      | `"string"`                        |
      | `int`                                         | `"integer"`                       |
      | `float`                                       | `"number"`                        |
      | `bool`                                        | `"boolean"`                       |
      | `array`                                       | `"array"` (vedi la nota seguente) |
      | `?type` (nullable)                            | Campo facoltativo                 |
      | Classe che implementa `StructuredOutputModel` | Oggetto annidato                  |

      Per le proprietà `array`, l’SDK aggiunge uno schema `items` solo quando il tipo degli elementi è un `StructuredOutputModel` annidato, dichiarato con `#[Constrained(itemClass: MyModel::class)]` o con un docblock `/** @var MyModel[] */`. Gli array di scalari (`string[]`, `int[]`) emettono un `{"type":"array"}` non vincolato.

      Tutte le proprietà non nullable diventano campi obbligatori.
    </Accordion>

    <Accordion title="Vincoli con l’attributo #[Constrained]">
      Aggiungi vincoli con l’attributo `#[Constrained]`:

      ```php
      use Anthropic\Lib\Attributes\Constrained;
      use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
      use Anthropic\Lib\Contracts\StructuredOutputModel;

      class Address implements StructuredOutputModel { use StructuredOutputModelTrait; public string $street; }

      class Profile implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          #[Constrained(description: 'Age in years', minimum: 0, maximum: 150)]
          public int $age;

          #[Constrained(format: 'email')]
          public string $email;

          #[Constrained(itemClass: Address::class, minItems: 1)]
          public array $addresses;
      }
      ```

      **Vincoli applicati dall’API** (inviati nello schema): `description`, `format`, `const`, `itemClass`, `minItems` (solo 0 o 1).

      **Vincoli convalidati dall’SDK** (rimossi dallo schema inviato, aggiunti alla descrizione e convalidati rispetto alla risposta): `minimum`, `maximum`, `multipleOf`, `minLength`, `maxLength`.
    </Accordion>
  </Tab>

  <Tab title="Ruby">
    ```ruby
    client = Anthropic::Client.new

    class ContactInfo < Anthropic::BaseModel
      required :name, String
      required :email, String
      required :plan_interest, String
      required :demo_requested, Anthropic::Boolean
    end

    message = client.messages.create(
      model: Anthropic::Model::CLAUDE_OPUS_5_5,
      max_tokens: 1024,
      messages: [{
        role: "user",
        content: "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."
      }],
      output_config: { format: ContactInfo }
    )

    contact = message.parsed_output
    puts contact
    ```

    Definisci una classe che estende `Anthropic::BaseModel` e passala a `messages.create()` come `output_config: { format: Model }`. L’SDK deriva un JSON schema dalla classe, lo trasforma e assegna il risultato analizzato all’attributo `parsed_output` della risposta come oggetto Ruby tipizzato.

    L’esempio precedente produce:

    ```text Output wrap
    {name: "John Smith", email: "john@example.com", plan_interest: "Enterprise", demo_requested: true}
    ```

    <Accordion title="Funzionalità avanzate dei modelli">
      L’SDK Ruby supporta funzionalità aggiuntive di definizione dei modelli per schemi più ricchi:

      * **Parola chiave `doc:`:** aggiungi descrizioni ai campi per un output dello schema più informativo
      * **`Anthropic::ArrayOf[T]`:** array tipizzati. Passa i vincoli a livello di array (`min_items:`, `max_items:`) come parole chiave su `required`/`optional`, non su `ArrayOf` stesso
      * **`Anthropic::EnumOf[:a, :b]`:** campi enum con valori vincolati
      * **`Anthropic::UnionOf[T1, T2]`:** tipi unione mappati su `anyOf`

      ```ruby
      class FamousNumber < Anthropic::BaseModel
        required :value, Float
        optional :reason, String, doc: "why is this number mathematically significant?"
      end

      class Output < Anthropic::BaseModel
        required :numbers, Anthropic::ArrayOf[FamousNumber], min_items: 3, max_items: 5
      end

      message = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_5,
        max_tokens: 1024,
        messages: [{ role: "user", content: "give me some famous numbers" }],
        output_config: { format: Output }
      )

      message.parsed_output
      # => #<Output numbers=[#<FamousNumber value=3.14159... reason="Pi greco è...">...]>
      ```
    </Accordion>
  </Tab>
</Tabs>

## Come funziona la trasformazione dell’SDK

La maggior parte degli helper dell’SDK trasforma gli schemi che usano funzionalità non supportate. I passaggi della trasformazione:

1. **Rimuove i vincoli non supportati** (ad esempio, `minimum`, `maximum`, `minLength`, `maxLength`)
2. **Aggiorna le descrizioni** aggiungendo ogni vincolo non supportato alla descrizione del campo (ad esempio, `{minimum: 100}`)
3. **Aggiunge `additionalProperties: false`** a tutti gli oggetti
4. **Filtra i formati delle stringhe** limitandoli all’elenco supportato
5. **Convalida le risposte** rispetto al tuo schema originale e a tutti i suoi vincoli, se l’helper convalida le risposte

Claude riceve uno schema semplificato, ma un helper che convalida le risposte applica comunque ogni vincolo nel tuo codice.

**Esempio:** un campo con `minimum: 100` diventa un semplice intero nello schema inviato e l’SDK aggiunge `{minimum: 100}` alla descrizione del campo. Un helper che convalida le risposte verifica comunque la risposta rispetto a `minimum: 100`.

## Usare un JSON schema grezzo

Per usare un JSON schema proveniente da un file, da una specifica OpenAPI o da codice che lo costruisce in fase di esecuzione, passalo in `output_config.format`.

<Tabs>
  <Tab title="cURL">
    ```bash
    curl https://api.anthropic.com/v1/messages \
      -H "content-type: application/json" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2026-10-21" \
      -d '{
        "model": "claude-opus-5-5",
        "max_tokens": 1024,
        "messages": [
          {
            "role": "user",
            "content": "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."
          }
        ],
        "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
            }
          }
        }
      }'
    ```

    Claude restituisce JSON come questo nel blocco di contenuto testuale della risposta:

    ```json Output
    {
      "name": "John Smith",
      "email": "john@example.com",
      "plan_interest": "Enterprise",
      "demo_requested": true
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash
    ant messages create <<'YAML'
    model: claude-opus-5-5
    max_tokens: 1024
    messages:
      - role: user
        content: >-
          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.
    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
    YAML
    ```

    Claude restituisce JSON come questo nel blocco di contenuto testuale della risposta:

    ```json Output
    {
      "name": "John Smith",
      "email": "john@example.com",
      "plan_interest": "Enterprise",
      "demo_requested": true
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python
    client = anthropic.Anthropic()

    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": (
                    "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."
                ),
            }
        ],
        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,
                },
            }
        },
    )
    text = next(block.text for block in response.content if block.type == "text")
    contact = json.loads(text)
    print(contact)
    ```

    L’esempio precedente produce:

    ```text Output wrap
    {'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}
    ```

    Per spostare i [vincoli non supportati dall’API](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#json-schema-limitations) nelle descrizioni dei campi, passa lo schema attraverso `transform_schema()` del pacchetto `anthropic` prima di inviarlo, e modifica il risultato se necessario. `transform_schema()` accetta anche un modello Pydantic. A differenza di `client.messages.parse()`, restituisce lo schema trasformato anziché inviarlo.
  </Tab>

  <Tab title="TypeScript">
    ```typescript
    import { jsonSchemaOutputFormat } from "@anthropic-ai/sdk/helpers/json-schema";

    const client = new Anthropic();

    const response = await client.messages.parse({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      messages: [
        {
          role: "user",
          content: "Extract contact info: John Smith, john@example.com, interested in the Pro plan"
        }
      ],
      output_config: {
        format: jsonSchemaOutputFormat({
          type: "object",
          properties: {
            name: { type: "string" },
            email: { type: "string" },
            planInterest: { type: "string" }
          },
          required: ["name", "email", "planInterest"],
          additionalProperties: false
        } as const)
      }
    });

    // response.parsed_output è tipizzato come { name: string; email: string; planInterest: string } | null
    console.log(response.parsed_output);
    ```

    Usa `jsonSchemaOutputFormat()` per passare un semplice JSON schema a `parse()`, senza installare Zod. L’API restituisce una risposta conforme allo schema e, se dichiari lo schema con `as const`, TypeScript inferisce automaticamente il tipo di `parsed_output` in base al tuo schema. Per uno schema importato o generato, `parsed_output` è tipizzato come `unknown`.

    Per impostazione predefinita, l’helper [trasforma lo schema](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#how-sdk-transformation-works) nello stesso modo di `zodOutputFormat()`. Passa `{ transform: false }` come secondo argomento per inviarlo invariato. A differenza di `zodOutputFormat()`, non convalida la risposta, quindi non rileva le violazioni dei [vincoli non supportati dall’API](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#json-schema-limitations), come `minimum`.

    L’esempio precedente produce:

    ```text Output wrap
    { name: 'John Smith', email: 'john@example.com', planInterest: 'Pro' }
    ```
  </Tab>

  <Tab title="C#">
    ```csharp
    using System.Text.Json;
    using Anthropic;
    using Anthropic.Models.Messages;

    var client = new AnthropicClient();

    var response = await client.Messages.Create(new MessageCreateParams
    {
        Model = Model.ClaudeOpus5_5,
        MaxTokens = 1024,
        Messages = [
            new UserMessageParam
            {
                Content = "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."
            }
        ],
        OutputConfig = new OutputConfig
        {
            Format = new JsonOutputFormat
            {
                Schema = new Dictionary<string, JsonElement>
                {
                    ["type"] = JsonSerializer.SerializeToElement("object"),
                    ["properties"] = JsonSerializer.SerializeToElement(new
                    {
                        name = new { type = "string" },
                        email = new { type = "string" },
                        plan_interest = new { type = "string" },
                        demo_requested = new { type = "boolean" },
                    }),
                    ["required"] = JsonSerializer.SerializeToElement(
                        new[] { "name", "email", "plan_interest", "demo_requested" }),
                    ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
                },
            },
        },
    });

    if (response.Content.Select(block => block.Value).OfType<TextBlock>().FirstOrDefault() is { } textBlock)
    {
        // È garantito che il JSON corrisponda allo schema
        var contact = JsonSerializer.Deserialize<JsonElement>(textBlock.Text);
        Console.WriteLine(contact);
    }
    ```

    L’esempio precedente produce:

    ```json Output
    {"name":"John Smith","email":"john@example.com","plan_interest":"Enterprise","demo_requested":true}
    ```
  </Tab>

  <Tab title="Go">
    ```go
    type ContactInfo struct {
    	Name          string `json:"name"`
    	Email         string `json:"email"`
    	PlanInterest  string `json:"plan_interest"`
    	DemoRequested bool   `json:"demo_requested"`
    }

    func main() {
    	client := anthropic.NewClient()

    	message, _ := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
    		Model:     anthropic.ModelClaudeOpus5_5,
    		MaxTokens: 1024,
    		Messages: []anthropic.MessageParam{
    			anthropic.NewUserMessage(anthropic.NewTextBlock(
    				"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.",
    			)),
    		},
    		OutputConfig: anthropic.OutputConfigParam{
    			Format: anthropic.JSONOutputFormatParam{
    				Schema: map[string]any{
    					"type": "object",
    					"properties": map[string]any{
    						"name":           map[string]string{"type": "string"},
    						"email":          map[string]string{"type": "string"},
    						"plan_interest":  map[string]string{"type": "string"},
    						"demo_requested": map[string]string{"type": "boolean"},
    					},
    					"required":             []string{"name", "email", "plan_interest", "demo_requested"},
    					"additionalProperties": false,
    				},
    			},
    		},
    	})

    	for _, block := range message.Content {
    		switch variant := block.AsAny().(type) {
    		case anthropic.TextBlock:
    			var contact ContactInfo
    			json.Unmarshal([]byte(variant.Text), &contact)
    			fmt.Printf("%#v\n", contact)
    		}
    	}
    }
    ```

    L’esempio precedente produce:

    ```text Output wrap
    main.ContactInfo{Name:"John Smith", Email:"john@example.com", PlanInterest:"Enterprise", DemoRequested:true}
    ```

    Per fare in modo che l’SDK trasformi uno schema di tipo map, passalo attraverso `BetaJSONSchemaOutputFormat()` sull’API beta.
  </Tab>

  <Tab title="Java">
    ```java
    import com.anthropic.core.JsonValue;
    import com.anthropic.models.messages.JsonOutputFormat;
    // ...
    import com.anthropic.models.messages.OutputConfig;
    import com.fasterxml.jackson.databind.JsonNode;
    import com.fasterxml.jackson.databind.ObjectMapper;

    void main() throws Exception {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        JsonOutputFormat.Schema schema = JsonOutputFormat.Schema.builder()
            .putAdditionalProperty("type", JsonValue.from("object"))
            .putAdditionalProperty("properties", JsonValue.from(Map.of(
                "name", Map.of("type", "string"),
                "email", Map.of("type", "string"),
                "plan_interest", Map.of("type", "string"))))
            .putAdditionalProperty("required", JsonValue.from(
                List.of("name", "email", "plan_interest")))
            .putAdditionalProperty("additionalProperties", JsonValue.from(false))
            .build();

        OutputConfig outputConfig = OutputConfig.builder()
            .format(JsonOutputFormat.builder()
                .schema(schema)
                .build())
            .build();

        MessageCreateParams createParams = MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_5_5)
            .maxTokens(1024)
            .outputConfig(outputConfig)
            .addUserMessage(
                "John Smith (john@example.com) is interested in our Enterprise plan.")
            .build();

        String json = client.messages().create(createParams).content().stream()
            .flatMap(contentBlock -> contentBlock.text().stream())
            .findFirst()
            .orElseThrow()
            .text();

        JsonNode contact = new ObjectMapper().readTree(json);
        IO.println(contact);
    }
    ```

    L’esempio precedente produce:

    ```json Output
    {"name":"John Smith","email":"john@example.com","plan_interest":"Enterprise"}
    ```

    Per un esempio più completo che costruisce uno schema annidato con array e descrizioni, consulta [`StructuredOutputsRawExample.java`](https://github.com/anthropics/anthropic-sdk-java/blob/main/anthropic-java-example/src/main/java/com/anthropic/example/StructuredOutputsRawExample.java) nel repository dell’SDK.
  </Tab>

  <Tab title="PHP">
    ```php
    use Anthropic\Messages\OutputConfig;
    use Anthropic\Messages\JSONOutputFormat;

    $client = new Client();

    $message = $client->messages->create(
        maxTokens: 1024,
        messages: [
            [
                'role' => 'user',
                'content' => 'Extract the key information from this email: '
                    . 'John Smith (john@example.com) is interested in our Enterprise plan.',
            ],
        ],
        model: 'claude-opus-5-5',
        outputConfig: OutputConfig::with(format: JSONOutputFormat::with(schema: [
            'type' => 'object',
            'properties' => [
                'name' => ['type' => 'string'],
                'email' => ['type' => 'string'],
                'plan_interest' => ['type' => 'string'],
            ],
            'required' => ['name', 'email', 'plan_interest'],
            'additionalProperties' => false,
        ])),
    );

    $textBlock = array_find($message->content, static fn ($block): bool => $block instanceof \Anthropic\Messages\TextBlock)
        ?? throw new \RuntimeException('Expected a text block in the response.');
    $contact = json_decode($textBlock->text, associative: true);
    var_dump($contact);
    ```

    Passa lo schema come array associativo a `JSONOutputFormat::with()` all’interno di `OutputConfig::with()` e decodifica la risposta con `json_decode()`.

    L’esempio precedente produce:

    ```text Output wrap
    array(3) {
      ["name"]=>
      string(10) "John Smith"
      ["email"]=>
      string(16) "john@example.com"
      ["plan_interest"]=>
      string(10) "Enterprise"
    }
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby
    client = Anthropic::Client.new

    response = client.messages.create(
      model: Anthropic::Model::CLAUDE_OPUS_5_5,
      max_tokens: 1024,
      messages: [
        {
          role: "user",
          content: "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."
        }
      ],
      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
          }
        }
      }
    )

    text = response.content.find { it.type == :text }.text
    contact = JSON.parse(text)
    p contact
    ```

    L’esempio precedente produce:

    ```text Output wrap
    {"name" => "John Smith", "email" => "john@example.com", "plan_interest" => "Enterprise", "demo_requested" => true}
    ```
  </Tab>
</Tabs>

## Casi d’uso comuni

<AccordionGroup>
  <Accordion title="Estrazione di dati">
    Estrai dati strutturati da testo non strutturato:

    <CodeGroup>
      ```bash cURL
      curl https://api.anthropic.com/v1/messages \
        -H "content-type: application/json" \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2026-10-21" \
        -d '{
          "model": "claude-opus-5-5",
          "max_tokens": 4096,
          "messages": [
            {
              "role": "user",
              "content": "Extract invoice data from: Invoice #12345, Date: 2024-01-15, Customer: Acme Corp, 2 widgets at $150.00 each, 1 setup fee at $200.00, Total: $500.00"
            }
          ],
          "output_config": {
            "format": {
              "type": "json_schema",
              "schema": {
                "type": "object",
                "properties": {
                  "invoice_number": {"type": "string"},
                  "date": {"type": "string"},
                  "total_amount": {"type": "number"},
                  "line_items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "description": {"type": "string"},
                        "quantity": {"type": "number"},
                        "unit_price": {"type": "number"}
                      },
                      "required": ["description", "quantity", "unit_price"],
                      "additionalProperties": false
                    }
                  },
                  "customer_name": {"type": "string"}
                },
                "required": ["invoice_number", "date", "total_amount", "line_items", "customer_name"],
                "additionalProperties": false
              }
            }
          }
        }'
      ```

      ```bash CLI
      ant messages create <<'YAML'
      model: claude-opus-5-5
      max_tokens: 4096
      messages:
        - role: user
          content: |
            Extract invoice data from:
            Invoice #12345
            Date: 2024-01-15
            Customer: Acme Corp
            2 widgets at $150.00 each
            1 setup fee at $200.00
            Total: $500.00
      output_config:
        format:
          type: json_schema
          schema:
            type: object
            properties:
              invoice_number: {type: string}
              date: {type: string}
              total_amount: {type: number}
              line_items:
                type: array
                items:
                  type: object
                  properties:
                    description: {type: string}
                    quantity: {type: number}
                    unit_price: {type: number}
                  required: [description, quantity, unit_price]
                  additionalProperties: false
              customer_name: {type: string}
            required: [invoice_number, date, total_amount, line_items, customer_name]
            additionalProperties: false
      YAML
      ```

      ```python Python
      from pydantic import BaseModel


      class LineItem(BaseModel):
          description: str
          quantity: float
          unit_price: float


      class Invoice(BaseModel):
          invoice_number: str
          date: str
          total_amount: float
          line_items: list[LineItem]
          customer_name: str


      client = anthropic.Anthropic()
      invoice_text = """
      Invoice #12345
      Date: 2024-01-15
      Customer: Acme Corp
      2 widgets at $150.00 each
      1 setup fee at $200.00
      Total: $500.00
      """

      response = client.messages.parse(
          model="claude-opus-5-5",
          max_tokens=4096,
          output_format=Invoice,
          messages=[
              {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
          ],
      )

      print(response.parsed_output)
      ```

      ```typescript TypeScript
      import { z } from "zod";
      import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

      const client = new Anthropic();

      const LineItemSchema = z.object({
        description: z.string(),
        quantity: z.number(),
        unit_price: z.number()
      });

      const InvoiceSchema = z.object({
        invoice_number: z.string(),
        date: z.string(),
        total_amount: z.number(),
        line_items: z.array(LineItemSchema),
        customer_name: z.string()
      });

      const invoiceText = `
      Invoice #12345
      Date: 2024-01-15
      Customer: Acme Corp
      2 widgets at $150.00 each
      1 setup fee at $200.00
      Total: $500.00
      `;

      const response = await client.messages.parse({
        model: "claude-opus-5-5",
        max_tokens: 4096,
        output_config: { format: zodOutputFormat(InvoiceSchema) },
        messages: [{ role: "user", content: `Extract invoice data from: ${invoiceText}` }]
      });
      console.log(response.parsed_output);
      ```

      ```csharp C#
      AnthropicClient client = new();

      string invoiceText = """
          Invoice #12345
          Date: 2024-01-15
          Customer: Acme Corp
          2 widgets at $150.00 each
          1 setup fee at $200.00
          Total: $500.00
          """;

      var parameters = new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 4096,
          OutputConfig = new OutputConfig
          {
              Format = new JsonOutputFormat
              {
                  Schema = new Dictionary<string, JsonElement>
                  {
                      ["type"] = JsonSerializer.SerializeToElement("object"),
                      ["properties"] = JsonSerializer.SerializeToElement(new
                      {
                          invoice_number = new { type = "string" },
                          date = new { type = "string" },
                          total_amount = new { type = "number" },
                          line_items = new
                          {
                              type = "array",
                              items = new
                              {
                                  type = "object",
                                  properties = new
                                  {
                                      description = new { type = "string" },
                                      quantity = new { type = "number" },
                                      unit_price = new { type = "number" },
                                  },
                                  required = new[] { "description", "quantity", "unit_price" },
                                  additionalProperties = false,
                              },
                          },
                          customer_name = new { type = "string" },
                      }),
                      ["required"] = JsonSerializer.SerializeToElement(new[] { "invoice_number", "date", "total_amount", "line_items", "customer_name" }),
                      ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
                  },
              },
          },
          Messages = [new UserMessageParam { Content = $"Extract invoice data from: {invoiceText}" }]
      };

      var message = await client.Messages.Create(parameters);
      Console.WriteLine(message);
      ```

      ```go Go
      client := anthropic.NewClient()

      invoiceText := `
      Invoice #12345
      Date: 2024-01-15
      Customer: Acme Corp
      2 widgets at $150.00 each
      1 setup fee at $200.00
      Total: $500.00
      `

      schema := map[string]any{
      	"type":                 "object",
      	"additionalProperties": false,
      	"properties": map[string]any{
      		"invoice_number": map[string]any{"type": "string"},
      		"date":           map[string]any{"type": "string"},
      		"total_amount":   map[string]any{"type": "number"},
      		"line_items": map[string]any{
      			"type": "array",
      			"items": map[string]any{
      				"type":                 "object",
      				"additionalProperties": false,
      				"properties": map[string]any{
      					"description": map[string]any{"type": "string"},
      					"quantity":    map[string]any{"type": "number"},
      					"unit_price":  map[string]any{"type": "number"},
      				},
      				"required": []string{"description", "quantity", "unit_price"},
      			},
      		},
      		"customer_name": map[string]any{"type": "string"},
      	},
      	"required": []string{"invoice_number", "date", "total_amount", "line_items", "customer_name"},
      }

      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
      	Model:     anthropic.ModelClaudeOpus5_5,
      	MaxTokens: 4096,
      	OutputConfig: anthropic.OutputConfigParam{
      		Format: anthropic.JSONOutputFormatParam{
      			Schema: schema,
      		},
      	},
      	Messages: []anthropic.MessageParam{
      		anthropic.NewUserMessage(anthropic.NewTextBlock(fmt.Sprintf("Extract invoice data from: %s", invoiceText))),
      	},
      })
      if err != nil {
      	log.Fatal(err)
      }
      for _, block := range response.Content {
      	switch variant := block.AsAny().(type) {
      	case anthropic.TextBlock:
      		fmt.Println(variant.Text)
      	}
      }
      ```

      ```java Java
      import com.fasterxml.jackson.annotation.JsonProperty;

      static class LineItem {
          @JsonProperty("description")
          public String description;

          @JsonProperty("quantity")
          public double quantity;

          @JsonProperty("unit_price")
          public double unitPrice;
      }

      static class Invoice {
          @JsonProperty("invoice_number")
          public String invoiceNumber;

          @JsonProperty("date")
          public String date;

          @JsonProperty("total_amount")
          public double totalAmount;

          @JsonProperty("line_items")
          public List<LineItem> lineItems;

          @JsonProperty("customer_name")
          public String customerName;
      }

      void main() {
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          String invoiceText = """
              Invoice #12345
              Date: 2024-01-15
              Customer: Acme Corp
              2 widgets at $150.00 each
              1 setup fee at $200.00
              Total: $500.00
              """;

          StructuredMessageCreateParams<Invoice> params = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(4096L)
              .outputConfig(Invoice.class)
              .addUserMessage("Extract invoice data from: " + invoiceText)
              .build();

          StructuredMessage<Invoice> response = client.messages().create(params);
          Invoice invoice = response.content().stream()
              .flatMap(block -> block.text().stream())
              .findFirst().orElseThrow().text();
          IO.println("Invoice " + invoice.invoiceNumber + ": $" + invoice.totalAmount);
          for (LineItem item : invoice.lineItems) {
              IO.println(item.quantity + " x " + item.description);
          }
      }
      ```

      ```php PHP
      use Anthropic\Lib\Attributes\Constrained;
      use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
      use Anthropic\Lib\Contracts\StructuredOutputModel;

      $client = new Client();

      class LineItem implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          public string $description;
          public float $quantity;
          public float $unit_price;
      }

      class Invoice implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          public string $invoice_number;
          public string $date;
          public float $total_amount;
          #[Constrained(itemClass: LineItem::class)]
          public array $line_items;
          public string $customer_name;
      }

      $invoiceText = <<<'TEXT'
      Invoice #12345
      Date: 2024-01-15
      Customer: Acme Corp
      2 widgets at $150.00 each
      1 setup fee at $200.00
      Total: $500.00
      TEXT;

      $message = $client->messages->create(
          maxTokens: 4096,
          messages: [
              ['role' => 'user', 'content' => "Extract invoice data from: $invoiceText"]
          ],
          model: 'claude-opus-5-5',
          outputConfig: ['format' => Invoice::class],
      );

      $invoice = $message->parsedOutput();
      if ($invoice instanceof Invoice) {
          echo "Invoice {$invoice->invoice_number}: \${$invoice->total_amount}\n";
          foreach ($invoice->line_items as $item) {
              echo "{$item->quantity} x {$item->description}\n";
          }
      }
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      class LineItem < Anthropic::BaseModel
        required :description, String
        required :quantity, Float
        required :unit_price, Float
      end

      class Invoice < Anthropic::BaseModel
        required :invoice_number, String
        required :date, String
        required :total_amount, Float
        required :line_items, Anthropic::ArrayOf[LineItem]
        required :customer_name, String
      end

      invoice_text = <<~TEXT
        Invoice #12345
        Date: 2024-01-15
        Customer: Acme Corp
        2 widgets at $150.00 each
        1 setup fee at $200.00
        Total: $500.00
      TEXT

      message = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_5,
        max_tokens: 4096,
        output_config: { format: Invoice },
        messages: [
          { role: "user", content: "Extract invoice data from: #{invoice_text}" }
        ]
      )

      invoice = message.parsed_output
      puts "Invoice #{invoice.invoice_number}: $#{invoice.total_amount}"
      invoice.line_items.each { |item| puts "#{item.quantity} x #{item.description}" }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Classificazione">
    Classifica i contenuti con categorie strutturate:

    <CodeGroup>
      ```bash cURL
      curl https://api.anthropic.com/v1/messages \
        -H "content-type: application/json" \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2026-10-21" \
        -d '{
          "model": "claude-opus-5-5",
          "max_tokens": 1024,
          "messages": [
            {
              "role": "user",
              "content": "Classify this feedback: Great product, fast shipping!"
            }
          ],
          "output_config": {
            "format": {
              "type": "json_schema",
              "schema": {
                "type": "object",
                "properties": {
                  "category": {"type": "string"},
                  "confidence": {"type": "number"},
                  "tags": {"type": "array", "items": {"type": "string"}},
                  "sentiment": {"type": "string"}
                },
                "required": ["category", "confidence", "tags", "sentiment"],
                "additionalProperties": false
              }
            }
          }
        }'
      ```

      ```bash CLI
      ant messages create <<'YAML'
      model: claude-opus-5-5
      max_tokens: 1024
      messages:
        - role: user
          content: "Classify this feedback: Great product, fast shipping!"
      output_config:
        format:
          type: json_schema
          schema:
            type: object
            properties:
              category:
                type: string
              confidence:
                type: number
              tags:
                type: array
                items:
                  type: string
              sentiment:
                type: string
            required:
              - category
              - confidence
              - tags
              - sentiment
            additionalProperties: false
      YAML
      ```

      ```python Python
      from pydantic import BaseModel

      client = Anthropic()


      class Classification(BaseModel):
          category: str
          confidence: float
          tags: list[str]
          sentiment: str


      feedback_text = "Great product, but the delivery was slow."
      response = client.messages.parse(
          model="claude-opus-5-5",
          max_tokens=1024,
          output_format=Classification,
          messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
      )

      print(response.parsed_output)
      ```

      ```typescript TypeScript
      import { z } from "zod";
      import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

      const client = new Anthropic();

      const ClassificationSchema = z.object({
        category: z.string(),
        confidence: z.number(),
        tags: z.array(z.string()),
        sentiment: z.string()
      });

      const feedbackText = "Great product, but the delivery was slow.";
      const response = await client.messages.parse({
        model: "claude-opus-5-5",
        max_tokens: 1024,
        output_config: { format: zodOutputFormat(ClassificationSchema) },
        messages: [{ role: "user", content: `Classify this feedback: ${feedbackText}` }]
      });

      console.log(response.parsed_output);
      ```

      ```csharp C#
      AnthropicClient client = new();

      string feedbackText = "Great product, fast shipping!";

      var parameters = new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages = [new UserMessageParam { Content = $"Classify this feedback: {feedbackText}" }],
          OutputConfig = new OutputConfig
          {
              Format = new JsonOutputFormat
              {
                  Schema = new Dictionary<string, JsonElement>
                  {
                      ["type"] = JsonSerializer.SerializeToElement("object"),
                      ["properties"] = JsonSerializer.SerializeToElement(new
                      {
                          category = new { type = "string" },
                          confidence = new { type = "number" },
                          tags = new { type = "array", items = new { type = "string" } },
                          sentiment = new { type = "string" },
                      }),
                      ["required"] = JsonSerializer.SerializeToElement(new[] { "category", "confidence", "tags", "sentiment" }),
                      ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
                  },
              },
          },
      };

      var message = await client.Messages.Create(parameters);
      Console.WriteLine(message);
      ```

      ```go Go
      client := anthropic.NewClient()

      feedbackText := "Great product, fast shipping!"

      schema := map[string]any{
      	"type": "object",
      	"properties": map[string]any{
      		"category":   map[string]any{"type": "string"},
      		"confidence": map[string]any{"type": "number"},
      		"tags":       map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
      		"sentiment":  map[string]any{"type": "string"},
      	},
      	"required":             []string{"category", "confidence", "tags", "sentiment"},
      	"additionalProperties": false,
      }

      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
      	Model:     anthropic.ModelClaudeOpus5_5,
      	MaxTokens: 1024,
      	OutputConfig: anthropic.OutputConfigParam{
      		Format: anthropic.JSONOutputFormatParam{
      			Schema: schema,
      		},
      	},
      	Messages: []anthropic.MessageParam{
      		anthropic.NewUserMessage(anthropic.NewTextBlock(fmt.Sprintf("Classify this feedback: %s", feedbackText))),
      	},
      })
      if err != nil {
      	log.Fatal(err)
      }
      for _, block := range response.Content {
      	switch variant := block.AsAny().(type) {
      	case anthropic.TextBlock:
      		var result map[string]any
      		json.Unmarshal([]byte(variant.Text), &result)
      		fmt.Println(result)
      	}
      }
      ```

      ```java Java
      import com.fasterxml.jackson.annotation.JsonProperty;

      static class Classification {
          @JsonProperty("category")
          public String category;

          @JsonProperty("confidence")
          public double confidence;

          @JsonProperty("tags")
          public List<String> tags;

          @JsonProperty("sentiment")
          public String sentiment;
      }

      void main() {
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          String feedbackText = "Great product, fast shipping!";

          StructuredMessageCreateParams<Classification> params = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(1024L)
              .outputConfig(Classification.class)
              .addUserMessage("Classify this feedback: " + feedbackText)
              .build();

          StructuredMessage<Classification> response = client.messages().create(params);
          Classification result = response.content().stream()
              .flatMap(block -> block.text().stream())
              .findFirst().orElseThrow().text();
          IO.println(result.category + " (" + result.confidence + ")");
      }
      ```

      ```php PHP
      use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
      use Anthropic\Lib\Contracts\StructuredOutputModel;

      $client = new Client();

      class Classification implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          public string $category;
          public float $confidence;
          public array $tags;
          public string $sentiment;
      }

      $feedbackText = 'Great product, fast shipping!';

      $message = $client->messages->create(
          maxTokens: 1024,
          messages: [
              ['role' => 'user', 'content' => "Classify this feedback: {$feedbackText}"]
          ],
          model: 'claude-opus-5-5',
          outputConfig: ['format' => Classification::class],
      );

      $result = $message->parsedOutput();
      if ($result instanceof Classification) {
          echo "{$result->category} ({$result->confidence}): {$result->sentiment}\n";
      }
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      class Classification < Anthropic::BaseModel
        required :category, String
        required :confidence, Float
        required :tags, Anthropic::ArrayOf[String]
        required :sentiment, String
      end

      feedback_text = "Great product, fast shipping!"

      message = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_5,
        max_tokens: 1024,
        output_config: { format: Classification },
        messages: [
          { role: "user", content: "Classify this feedback: #{feedback_text}" }
        ]
      )
      puts message.parsed_output
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Formattazione delle risposte API">
    Genera risposte pronte per l’API:

    <CodeGroup>
      ```bash cURL
      curl https://api.anthropic.com/v1/messages \
        -H "content-type: application/json" \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2026-10-21" \
        -d '{
          "model": "claude-opus-5-5",
          "max_tokens": 1024,
          "messages": [
            {
              "role": "user",
              "content": "Write an API response: request req_2abc3def has an invalid email."
            }
          ],
          "output_config": {
            "format": {
              "type": "json_schema",
              "schema": {
                "type": "object",
                "properties": {
                  "status": {"type": "string"},
                  "data": {
                    "type": "object",
                    "properties": {"message": {"type": "string"}},
                    "required": ["message"],
                    "additionalProperties": false
                  },
                  "errors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "code": {"type": "string"},
                        "detail": {"type": "string"}
                      },
                      "required": ["code", "detail"],
                      "additionalProperties": false
                    }
                  },
                  "metadata": {
                    "type": "object",
                    "properties": {"request_id": {"type": "string"}},
                    "required": ["request_id"],
                    "additionalProperties": false
                  }
                },
                "required": ["status", "data", "metadata"],
                "additionalProperties": false
              }
            }
          }
        }'
      ```

      ```bash CLI
      ant messages create <<'YAML'
      model: claude-opus-5-5
      max_tokens: 1024
      output_config:
        format:
          type: json_schema
          schema:
            type: object
            properties:
              status:
                type: string
              data:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              errors:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                    detail:
                      type: string
                  required:
                    - code
                    - detail
                  additionalProperties: false
              metadata:
                type: object
                properties:
                  request_id:
                    type: string
                required:
                  - request_id
                additionalProperties: false
            required:
              - status
              - data
              - metadata
            additionalProperties: false
      messages:
        - role: user
          content: "Write an API response: request req_2abc3def has an invalid email."
      YAML
      ```

      ```python Python
      from pydantic import BaseModel

      client = Anthropic()


      class Payload(BaseModel):
          message: str


      class APIError(BaseModel):
          code: str
          detail: str


      class Metadata(BaseModel):
          request_id: str


      class APIResponse(BaseModel):
          status: str
          data: Payload
          errors: list[APIError] | None = None
          metadata: Metadata


      response = client.messages.parse(
          model="claude-opus-5-5",
          max_tokens=1024,
          output_format=APIResponse,
          messages=[
              {
                  "role": "user",
                  "content": "Write an API response: request req_2abc3def has an invalid email.",
              }
          ],
      )

      print(response.parsed_output)
      ```

      ```typescript TypeScript
      import { z } from "zod";
      import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

      const client = new Anthropic();

      const APIResponseSchema = z.object({
        status: z.string(),
        data: z.object({ message: z.string() }),
        errors: z.array(z.object({ code: z.string(), detail: z.string() })).optional(),
        metadata: z.object({ request_id: z.string() })
      });

      const response = await client.messages.parse({
        model: "claude-opus-5-5",
        max_tokens: 1024,
        output_config: { format: zodOutputFormat(APIResponseSchema) },
        messages: [
          {
            role: "user",
            content: "Write an API response: request req_2abc3def has an invalid email."
          }
        ]
      });

      console.log(response.parsed_output);
      ```

      ```csharp C#
      AnthropicClient client = new();

      var parameters = new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages =
          [
              new UserMessageParam
              {
                  Content = "Write an API response: request req_2abc3def has an invalid email.",
              },
          ],
          OutputConfig = new OutputConfig
          {
              Format = new JsonOutputFormat
              {
                  Schema = new Dictionary<string, JsonElement>
                  {
                      ["type"] = JsonSerializer.SerializeToElement("object"),
                      ["properties"] = JsonSerializer.SerializeToElement(new
                      {
                          status = new { type = "string" },
                          data = new
                          {
                              type = "object",
                              properties = new { message = new { type = "string" } },
                              required = new[] { "message" },
                              additionalProperties = false,
                          },
                          errors = new
                          {
                              type = "array",
                              items = new
                              {
                                  type = "object",
                                  properties = new
                                  {
                                      code = new { type = "string" },
                                      detail = new { type = "string" },
                                  },
                                  required = new[] { "code", "detail" },
                                  additionalProperties = false,
                              },
                          },
                          metadata = new
                          {
                              type = "object",
                              properties = new { request_id = new { type = "string" } },
                              required = new[] { "request_id" },
                              additionalProperties = false,
                          },
                      }),
                      ["required"] = JsonSerializer.SerializeToElement(new[] { "status", "data", "metadata" }),
                      ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
                  },
              },
          },
      };

      var message = await client.Messages.Create(parameters);
      Console.WriteLine(message);
      ```

      ```go Go
      client := anthropic.NewClient()

      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
      	Model:     anthropic.ModelClaudeOpus5_5,
      	MaxTokens: 1024,
      	OutputConfig: anthropic.OutputConfigParam{
      		Format: anthropic.JSONOutputFormatParam{
      			Schema: map[string]any{
      				"type":                 "object",
      				"additionalProperties": false,
      				"properties": map[string]any{
      					"status": map[string]any{
      						"type": "string",
      					},
      					"data": map[string]any{
      						"type":                 "object",
      						"additionalProperties": false,
      						"properties": map[string]any{
      							"message": map[string]any{"type": "string"},
      						},
      						"required": []string{"message"},
      					},
      					"errors": map[string]any{
      						"type": "array",
      						"items": map[string]any{
      							"type":                 "object",
      							"additionalProperties": false,
      							"properties": map[string]any{
      								"code":   map[string]any{"type": "string"},
      								"detail": map[string]any{"type": "string"},
      							},
      							"required": []string{"code", "detail"},
      						},
      					},
      					"metadata": map[string]any{
      						"type":                 "object",
      						"additionalProperties": false,
      						"properties": map[string]any{
      							"request_id": map[string]any{"type": "string"},
      						},
      						"required": []string{"request_id"},
      					},
      				},
      				"required": []string{"status", "data", "metadata"},
      			},
      		},
      	},
      	Messages: []anthropic.MessageParam{
      		anthropic.NewUserMessage(anthropic.NewTextBlock(
      			"Write an API response: request req_2abc3def has an invalid email.",
      		)),
      	},
      })
      if err != nil {
      	log.Fatal(err)
      }
      for _, block := range response.Content {
      	switch variant := block.AsAny().(type) {
      	case anthropic.TextBlock:
      		fmt.Println(variant.Text)
      	}
      }
      ```

      ```java Java
      import com.fasterxml.jackson.annotation.JsonProperty;

      static class Payload {
          @JsonProperty("message")
          public String message;
      }

      static class APIError {
          @JsonProperty("code")
          public String code;

          @JsonProperty("detail")
          public String detail;
      }

      static class Metadata {
          @JsonProperty("request_id")
          public String requestId;
      }

      static class APIResponse {
          @JsonProperty("status")
          public String status;

          @JsonProperty("data")
          public Payload data;

          @JsonProperty("errors")
          public List<APIError> errors;

          @JsonProperty("metadata")
          public Metadata metadata;
      }

      void main() {
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          StructuredMessageCreateParams<APIResponse> params = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(1024L)
              .outputConfig(APIResponse.class)
              .addUserMessage("Write an API response: request req_2abc3def has an invalid email.")
              .build();

          StructuredMessage<APIResponse> response = client.messages().create(params);
          APIResponse result = response.content().stream()
              .flatMap(block -> block.text().stream())
              .findFirst().orElseThrow().text();
          IO.println(result.status + ": " + result.data.message);
      }
      ```

      ```php PHP
      use Anthropic\Lib\Attributes\Constrained;
      use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
      use Anthropic\Lib\Contracts\StructuredOutputModel;

      $client = new Client();

      class Payload implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          public string $message;
      }

      class APIError implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          public string $code;
          public string $detail;
      }

      class Metadata implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          public string $request_id;
      }

      class APIResponse implements StructuredOutputModel
      {
          use StructuredOutputModelTrait;

          public string $status;
          public Payload $data;
          #[Constrained(itemClass: APIError::class)]
          public ?array $errors;
          public Metadata $metadata;
      }

      $message = $client->messages->create(
          maxTokens: 1024,
          messages: [
              [
                  'role' => 'user',
                  'content' => 'Write an API response: request req_2abc3def has an invalid email.',
              ],
          ],
          model: 'claude-opus-5-5',
          outputConfig: ['format' => APIResponse::class],
      );

      $result = $message->parsedOutput();
      if ($result instanceof APIResponse) {
          echo "{$result->status}: {$result->data->message}\n";
      }
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      class Payload < Anthropic::BaseModel
        required :message, String
      end

      class APIError < Anthropic::BaseModel
        required :code, String
        required :detail, String
      end

      class Metadata < Anthropic::BaseModel
        required :request_id, String
      end

      class APIResponse < Anthropic::BaseModel
        required :status, String
        required :data, Payload
        optional :errors, Anthropic::ArrayOf[APIError]
        required :metadata, Metadata
      end

      message = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_5,
        max_tokens: 1024,
        output_config: { format: APIResponse },
        messages: [
          { role: "user", content: "Write an API response: request req_2abc3def has an invalid email." }
        ]
      )
      puts message.parsed_output
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Uso rigoroso degli strumenti

Per imporre la conformità a JSON Schema sugli input degli strumenti con il campionamento vincolato dalla grammatica, consulta [Uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use).

### Usare entrambe le funzionalità insieme

Gli output JSON e l’uso rigoroso degli strumenti risolvono problemi diversi e funzionano insieme:

* Gli **output JSON** controllano il formato della risposta di Claude (cosa dice Claude).
* L’**uso rigoroso degli strumenti** convalida i parametri degli strumenti (come Claude chiama le tue funzioni).

Quando vengono combinati, Claude può chiamare strumenti con parametri garantiti come validi E restituire risposte JSON strutturate. Questo è utile per i flussi di lavoro agentici in cui servono sia chiamate agli strumenti affidabili sia output finali strutturati.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [
        {
          "role": "user",
          "content": "Help me plan a trip to Paris departing May 15, 2026"
        }
      ],
      "output_config": {
        "format": {
          "type": "json_schema",
          "schema": {
            "type": "object",
            "properties": {
              "summary": {"type": "string"},
              "next_steps": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["summary", "next_steps"],
            "additionalProperties": false
          }
        }
      },
      "tools": [
        {
          "name": "search_flights",
          "strict": true,
          "input_schema": {
            "type": "object",
            "properties": {
              "destination": {"type": "string"},
              "date": {"type": "string", "format": "date"}
            },
            "required": ["destination", "date"],
            "additionalProperties": false
          }
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  messages:
    - role: user
      content: Help me plan a trip to Paris departing May 15, 2026
  # Output JSON: formato di risposta strutturato
  output_config:
    format:
      type: json_schema
      schema:
        type: object
        properties:
          summary:
            type: string
          next_steps:
            type: array
            items:
              type: string
        required: [summary, next_steps]
        additionalProperties: false
  # Uso degli strumenti rigoroso: parametri degli strumenti garantiti
  tools:
    - name: search_flights
      strict: true
      input_schema:
        type: object
        properties:
          destination:
            type: string
          date:
            type: string
            format: date
        required: [destination, date]
        additionalProperties: false
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[
          {
              "role": "user",
              "content": "Help me plan a trip to Paris departing May 15, 2026",
          }
      ],
      # Output JSON: formato di risposta strutturato
      output_config={
          "format": {
              "type": "json_schema",
              "schema": {
                  "type": "object",
                  "properties": {
                      "summary": {"type": "string"},
                      "next_steps": {"type": "array", "items": {"type": "string"}},
                  },
                  "required": ["summary", "next_steps"],
                  "additionalProperties": False,
              },
          }
      },
      # Uso degli strumenti rigoroso: parametri degli strumenti garantiti
      tools=[
          {
              "name": "search_flights",
              "strict": True,
              "input_schema": {
                  "type": "object",
                  "properties": {
                      "destination": {"type": "string"},
                      "date": {"type": "string", "format": "date"},
                  },
                  "required": ["destination", "date"],
                  "additionalProperties": False,
              },
          }
      ],
  )

  print(response)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Help me plan a trip to Paris departing May 15, 2026" }],
    // Output JSON: formato di risposta strutturato
    output_config: {
      format: {
        type: "json_schema",
        schema: {
          type: "object",
          properties: {
            summary: { type: "string" },
            next_steps: { type: "array", items: { type: "string" } }
          },
          required: ["summary", "next_steps"],
          additionalProperties: false
        }
      }
    },
    // Uso degli strumenti rigoroso: parametri degli strumenti garantiti
    tools: [
      {
        name: "search_flights",
        description: "Search for available flights to a destination on a specific date",
        strict: true,
        input_schema: {
          type: "object",
          properties: {
            destination: { type: "string" },
            date: { type: "string", format: "date" }
          },
          required: ["destination", "date"],
          additionalProperties: false
        }
      }
    ]
  });

  // Claude potrebbe chiamare prima lo strumento (tool_use) o rispondere con JSON (testo)
  console.log("Stop reason:", response.stop_reason);
  for (const block of response.content) {
    switch (block.type) {
      case "tool_use":
        console.log(`Tool call: ${block.name}(${JSON.stringify(block.input)})`);
        break;
      case "text":
        console.log("Response:", block.text);
        break;
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Messages = [new UserMessageParam { Content = "Help me plan a trip to Paris departing May 15, 2026" }],
      // Output JSON: formato di risposta strutturato
      OutputConfig = new OutputConfig
      {
          Format = new JsonOutputFormat
          {
              Schema = new Dictionary<string, JsonElement>
              {
                  ["type"] = JsonSerializer.SerializeToElement("object"),
                  ["properties"] = JsonSerializer.SerializeToElement(new
                  {
                      summary = new { type = "string" },
                      next_steps = new { type = "array", items = new { type = "string" } },
                  }),
                  ["required"] = JsonSerializer.SerializeToElement(new[] { "summary", "next_steps" }),
                  ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
              },
          },
      },
      // "Strict tool use" (uso rigoroso degli strumenti): parametri degli strumenti garantiti
      Tools =
      [
          new Tool
          {
              Name = "search_flights",
              Strict = true,
              InputSchema = new InputSchema(new Dictionary<string, JsonElement>
              {
                  ["properties"] = JsonSerializer.SerializeToElement(new Dictionary<string, object>
                  {
                      ["destination"] = new { type = "string" },
                      ["date"] = new { type = "string", format = "date" },
                  }),
                  ["required"] = JsonSerializer.SerializeToElement(new[] { "destination", "date" }),
                  ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
              }),
          }
      ],
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Help me plan a trip to Paris departing May 15, 2026")),
  	},
  	// Output JSON: formato di risposta strutturato
  	OutputConfig: anthropic.OutputConfigParam{
  		Format: anthropic.JSONOutputFormatParam{
  			Schema: map[string]any{
  				"type":                 "object",
  				"additionalProperties": false,
  				"properties": map[string]any{
  					"summary":    map[string]any{"type": "string"},
  					"next_steps": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
  				},
  				"required": []string{"summary", "next_steps"},
  			},
  		},
  	},
  	// Uso degli strumenti rigoroso: parametri degli strumenti garantiti
  	Tools: []anthropic.ToolUnionParam{
  		{OfTool: &anthropic.ToolParam{
  			Name:   "search_flights",
  			Strict: anthropic.Bool(true),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"destination": map[string]any{"type": "string"},
  					"date":        map[string]any{"type": "string", "format": "date"},
  				},
  				Required: []string{"destination", "date"},
  				ExtraFields: map[string]any{
  					"additionalProperties": false,
  				},
  			}}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.Content)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Output JSON: formato di risposta strutturato
  JsonOutputFormat.Schema outputSchema = JsonOutputFormat.Schema.builder()
      .putAdditionalProperty("type", JsonValue.from("object"))
      .putAdditionalProperty("properties", JsonValue.from(Map.of(
          "summary", Map.of("type", "string"),
          "next_steps", Map.of("type", "array", "items", Map.of("type", "string"))
      )))
      .putAdditionalProperty("required", JsonValue.from(List.of("summary", "next_steps")))
      .putAdditionalProperty("additionalProperties", JsonValue.from(false))
      .build();

  // Uso degli strumenti rigoroso: parametri degli strumenti garantiti
  InputSchema toolSchema = InputSchema.builder()
      .properties(JsonValue.from(Map.of(
          "destination", Map.of("type", "string"),
          "date", Map.of("type", "string", "format", "date")
      )))
      .putAdditionalProperty("required", JsonValue.from(List.of("destination", "date")))
      .putAdditionalProperty("additionalProperties", JsonValue.from(false))
      .build();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(1024L)
      .addUserMessage("Help me plan a trip to Paris departing May 15, 2026")
      .outputConfig(OutputConfig.builder()
          .format(JsonOutputFormat.builder()
              .schema(outputSchema)
              .build())
          .build())
      .addTool(Tool.builder()
          .name("search_flights")
          .description("Search for available flights to a destination on a specific date")
          .strict(true)
          .inputSchema(toolSchema)
          .build())
      .build();

  Message response = client.messages().create(params);
  IO.println(response);
  ```

  ```php PHP
  use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
  use Anthropic\Lib\Contracts\StructuredOutputModel;
  use Anthropic\Messages\ToolUseBlock;

  $client = new Client();

  class TripPlan implements StructuredOutputModel
  {
      use StructuredOutputModelTrait;

      public string $summary;
      public array $next_steps;
  }

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => 'Help me plan a trip to Paris departing May 15, 2026']
      ],
      model: 'claude-opus-5-5',
      // Output JSON: formato di risposta strutturato
      outputConfig: ['format' => TripPlan::class],
      // Uso degli strumenti rigoroso: parametri degli strumenti garantiti
      tools: [
          [
              'name' => 'search_flights',
              'strict' => true,
              'input_schema' => [
                  'type' => 'object',
                  'properties' => [
                      'destination' => ['type' => 'string'],
                      'date' => ['type' => 'string', 'format' => 'date']
                  ],
                  'required' => ['destination', 'date'],
                  'additionalProperties' => false
              ]
          ]
      ],
  );

  // Claude potrebbe prima chiamare lo strumento (tool_use) o rispondere con JSON (text)
  $plan = $message->parsedOutput();
  if ($plan instanceof TripPlan) {
      echo $plan->summary, "\n";
  } elseif ($toolUse = array_find($message->content, fn($block) => $block instanceof ToolUseBlock)) {
      echo "Tool call: {$toolUse->name}(", json_encode($toolUse->input), ")\n";
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    messages: [
      { role: "user", content: "Help me plan a trip to Paris departing May 15, 2026" }
    ],
    # Output JSON: formato di risposta strutturato
    output_config: {
      format: {
        type: :json_schema,
        schema: {
          type: "object",
          properties: {
            summary: { type: "string" },
            next_steps: { type: "array", items: { type: "string" } }
          },
          required: ["summary", "next_steps"],
          additionalProperties: false
        }
      }
    },
    # Uso degli strumenti rigoroso: parametri degli strumenti garantiti
    tools: [
      {
        name: "search_flights",
        strict: true,
        input_schema: {
          type: "object",
          properties: {
            destination: { type: "string" },
            date: { type: "string", format: "date" }
          },
          required: ["destination", "date"],
          additionalProperties: false
        }
      }
    ]
  )
  puts message
  ```
</CodeGroup>

## Considerazioni importanti

### Compilazione della grammatica e cache

Gli output strutturati usano il campionamento vincolato con artefatti di grammatica compilati. Questo introduce alcune caratteristiche prestazionali di cui tenere conto:

* **Latenza della prima richiesta:** la prima volta che usi uno schema specifico, c’è una “latency” (latenza) aggiuntiva mentre la grammatica viene compilata.
* **Cache automatica:** le grammatiche compilate vengono memorizzate nella cache per 24 ore dall’ultimo utilizzo, rendendo le richieste successive molto più veloci.
* **Invalidazione della cache:** la cache viene invalidata se modifichi la struttura del JSON schema oppure, quando usi sia gli output strutturati sia l’uso degli strumenti, l’insieme degli strumenti nella tua richiesta. Modificare solo i campi `name` o `description` non invalida la cache.

### Modifica del prompt e costi dei token

Quando usi gli output strutturati, Claude riceve automaticamente un “system prompt” (prompt di sistema) aggiuntivo che spiega il formato di output previsto. Ciò significa che:

* Il conteggio dei token di input è leggermente più alto.
* Il prompt iniettato ti costa token come qualsiasi altro prompt di sistema.
* Modificare il parametro `output_config.format` invalida qualsiasi [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) per quel thread di conversazione.

### Limitazioni di JSON Schema

Gli output strutturati supportano JSON Schema standard con alcune limitazioni. Sia gli output JSON sia l’uso rigoroso degli strumenti condividono queste limitazioni.

<Accordion title="Funzionalità supportate">
  * Tutti i tipi di base: object, array, string, integer, number, boolean, null
  * `enum` e `const` (solo stringhe, numeri, booleani o null), con un’[avvertenza sulle maiuscole](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#invalid-outputs)
  * `anyOf` e `allOf`, eccetto gli usi elencati in “Non supportato”
  * `$ref`, `$defs` e `definitions`
  * Proprietà `default` per tutti i tipi supportati
  * `required` e `additionalProperties` (deve essere impostato su `false` per gli oggetti)
  * Formati delle stringhe: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`
  * `minItems` per gli array (supportati solo i valori 0 e 1)
</Accordion>

<Accordion title="Non supportato">
  * Schemi ricorsivi
  * `oneOf` (usa invece `anyOf`)
  * `not`
  * `anyOf` nello stesso oggetto schema di parole chiave come `type` o `properties` (le annotazioni come `title` e `description` sono consentite)
  * `allOf` con schemi in conflitto (ad esempio, valori `type` diversi)
  * `allOf` con due o più schemi quando uno di essi contiene direttamente `$ref`, `anyOf` o `allOf`
  * Tipi complessi all’interno degli enum
  * `$ref` esterno (ad esempio, `'$ref': 'http://...'`)
  * Vincoli numerici (come `minimum`, `maximum`, `multipleOf`)
  * Vincoli sulle stringhe (`minLength`, `maxLength`)
  * Vincoli sugli array oltre a `minItems` pari a 0 o 1
  * `additionalProperties` impostato su un valore diverso da `false` (consulta [Oggetti con chiavi arbitrarie](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#objects-with-arbitrary-keys))

  Se usi una funzionalità non supportata, riceverai un errore 400 con i dettagli.
</Accordion>

<Accordion title="Supporto dei pattern (regex)">
  **Funzionalità regex supportate:**

  * Corrispondenza completa (`^...$`) e corrispondenza parziale
  * Quantificatori: `*`, `+`, `?`, casi semplici di `{n,m}`
  * Classi di caratteri: `[]`, `.`, `\d`, `\w`, `\s`
  * Gruppi: `(...)`

  **Non supportate:**

  * Riferimenti all’indietro ai gruppi (ad esempio, `\1`, `\2`)
  * Asserzioni lookahead/lookbehind (ad esempio, `(?=...)`, `(?!...)`)
  * Confini di parola: `\b`, `\B`
  * Quantificatori `{n,m}` complessi con intervalli ampi

  I pattern regex semplici funzionano bene. I pattern complessi potrebbero causare errori 400.
</Accordion>

<Tip>
  Gli helper dell’SDK possono trasformare schemi con [vincoli non supportati dall’API](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#json-schema-limitations). Consulta [Come funziona la trasformazione dell’SDK](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#how-sdk-transformation-works).
</Tip>

#### Oggetti con chiavi arbitrarie

Elenca ogni chiave di un oggetto, in `properties` oppure come campo della classe o dello schema che passi all’SDK. Poiché `additionalProperties` deve essere `false`, Claude può restituire solo le chiavi che elenchi.

L’API accetta un oggetto con `properties` vuoto o mancante, ma Claude può restituire solo `{}` per esso. Un tipo map, dizionario o record non elenca alcuna chiave, quindi gli SDK Python e TypeScript lo inviano come oggetto con `properties` vuoto. Gli SDK Java e Ruby sollevano invece un errore.

Se non conosci le chiavi in anticipo, usa invece un array. Assegna a ogni elemento una `key` e un `value`, come in questo schema:

```json
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}
```

### Ordinamento delle proprietà

Quando usi gli output strutturati, le proprietà negli oggetti mantengono l’ordine definito nel tuo schema, con un’importante avvertenza: **le proprietà obbligatorie compaiono per prime, seguite dalle proprietà facoltative**.

Ad esempio, dato questo schema:

```json
{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}
```

L’output ordina le proprietà in questo modo:

1. `name` (obbligatoria, nell’ordine dello schema)
2. `email` (obbligatoria, nell’ordine dello schema)
3. `notes` (facoltativa, nell’ordine dello schema)
4. `age` (facoltativa, nell’ordine dello schema)

Ciò significa che l’output potrebbe apparire così:

```json
{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}
```

Se l’ordine delle proprietà nell’output è importante per la tua applicazione, contrassegna tutte le proprietà come obbligatorie oppure tieni conto di questo riordinamento nella tua logica di parsing.

### Output non validi

Sebbene gli output strutturati garantiscano la conformità allo schema nella maggior parte dei casi, esistono scenari in cui l’output potrebbe non corrispondere al tuo schema:

**Rifiuti** (`stop_reason: "refusal"`)

Claude mantiene le sue proprietà di sicurezza e utilità anche quando usa gli output strutturati. Se Claude rifiuta una richiesta per motivi di sicurezza:

* La risposta ha `stop_reason: "refusal"`.
* Riceverai un codice di stato 200.
* Ti verranno addebitati i token generati.
* L’output potrebbe non corrispondere al tuo schema perché il messaggio di rifiuto ha la precedenza sui vincoli dello schema.

Una proprietà che richiede il “thinking” (ragionamento) del modello o un ragionamento passo dopo passo potrebbe portare a un rifiuto `reasoning_extraction`. Chiedi invece una breve spiegazione. Consulta [Mantieni il ragionamento nei blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).

**Limite di token raggiunto** (`stop_reason: "max_tokens"`)

Se la risposta viene troncata perché ha raggiunto il limite `max_tokens`:

* La risposta ha `stop_reason: "max_tokens"`.
* L’output potrebbe essere incompleto e non corrispondere al tuo schema.
* Riprova con un valore `max_tokens` più alto per ottenere l’output strutturato completo.

**Maiuscole/minuscole dei valori enum**

Gli output strutturati non garantiscono l’uso delle maiuscole nei valori stringa di `enum` e `const`: Claude potrebbe restituire un valore che differisce dal tuo schema solo per le maiuscole, tipicamente nella prima lettera di una parola che segue uno spazio. Ad esempio, dato questo schema:

```json
{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}
```

L’output potrebbe contenere `"Conversation Topic 3"` (“T” maiuscola) anche se quel valore esatto non è presente nell’enum. La risposta si completa normalmente, senza errori e senza uno `stop_reason` speciale. Questo vale sia per gli output JSON sia per l’uso rigoroso degli strumenti. Confronta i valori enum senza distinzione tra maiuscole e minuscole ed evita valori enum che differiscono solo per le maiuscole.

### Limiti di complessità dello schema

Gli output strutturati funzionano compilando i tuoi JSON schema in una grammatica che vincola l’output di Claude. Schemi più complessi producono grammatiche più grandi che richiedono più tempo per essere compilate. Per proteggersi da tempi di compilazione eccessivi, l’API applica diversi limiti di complessità.

#### Limiti espliciti

I seguenti limiti si applicano a tutte le richieste con `output_config.format` o `strict: true`:

| Limite                           | Valore | Descrizione                                                                                                                                                                                                         |
| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Strumenti rigorosi per richiesta | 20     | Numero massimo di strumenti con `strict: true`. Gli strumenti non rigorosi non vengono conteggiati ai fini di questo limite.                                                                                        |
| Parametri facoltativi            | 24     | Totale dei parametri facoltativi in tutti gli schemi degli strumenti rigorosi e negli schemi di output JSON. Ogni parametro non elencato in `required` viene conteggiato ai fini di questo limite.                  |
| Parametri con tipi unione        | 16     | Totale dei parametri che usano `anyOf` o array di tipi (ad esempio, `"type": ["string", "null"]`) in tutti gli schemi rigorosi. Sono particolarmente onerosi perché generano un costo di compilazione esponenziale. |

<Note>
  Questi limiti si applicano al totale combinato di tutti gli schemi rigorosi in una singola richiesta. Ad esempio, se hai quattro strumenti rigorosi con sei parametri facoltativi ciascuno, raggiungerai il limite di 24 parametri anche se nessun singolo strumento sembra complesso.
</Note>

#### Limiti interni aggiuntivi

Oltre ai limiti espliciti della tabella precedente, esistono limiti interni aggiuntivi sulla dimensione della grammatica compilata. Questi limiti esistono perché la complessità dello schema non si riduce a una singola dimensione: funzionalità come parametri facoltativi, tipi unione, oggetti annidati e numero di strumenti interagiscono tra loro in modi che possono rendere la grammatica compilata sproporzionatamente grande.

Quando questi limiti vengono superati, riceverai un errore 400 con il messaggio “Schema is too complex for compilation.” Questi errori indicano che la complessità combinata dei tuoi schemi supera ciò che può essere compilato in modo efficiente, anche se ogni singolo limite della tabella precedente è rispettato. Come ultima misura di sicurezza, l’API applica anche un **timeout di compilazione di 180 secondi**. Gli schemi che superano tutti i controlli espliciti ma producono grammatiche compilate molto grandi potrebbero raggiungere questo timeout.

#### Suggerimenti per ridurre la complessità dello schema

Se stai raggiungendo i limiti di complessità, prova queste strategie nell’ordine:

1. **Contrassegna come rigorosi solo gli strumenti critici.** Se hai molti strumenti, riserva l’uso rigoroso degli strumenti a quelli in cui le violazioni dello schema causano problemi reali e affidati all’aderenza naturale di Claude per gli strumenti più semplici.

2. **Riduci i parametri facoltativi.** Rendi i parametri `required` dove possibile. Ogni parametro facoltativo raddoppia approssimativamente una porzione dello spazio degli stati della grammatica. Se un parametro ha sempre un valore predefinito ragionevole, valuta di renderlo obbligatorio e di far fornire esplicitamente quel valore predefinito a Claude.

3. **Semplifica le strutture annidate.** Oggetti profondamente annidati con campi facoltativi aumentano la complessità. Appiattisci le strutture dove possibile.

4. **Suddividi in più richieste.** Se hai molti strumenti rigorosi, valuta di suddividerli in richieste separate o in subagenti.

Per problemi persistenti con schemi validi, [contatta il supporto](https://support.claude.com/en/articles/9015913-how-to-get-support) fornendo la definizione del tuo schema.

## Migrazione dalla beta

Il parametro `output_format` è stato spostato in `output_config.format` e gli header beta non sono più necessari. Il parametro `output_format` è deprecato. Per usarlo comunque, aggiungi l’header beta `structured-outputs-2025-11-13`. Senza di esso, l’API restituisce un errore 400.

Nell’SDK Python (v1.0 e successive), un dizionario di schema passato come `output_format={...}` solleva un `TypeError`. Usa invece `output_config`. Un modello Pydantic passato come `output_format=Model` a `parse()` o `stream()` funziona senza modifiche e senza header beta, perché l’SDK lo invia come `output_config`. Consulta [Usare un JSON schema grezzo](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#using-a-raw-json-schema) per la forma aggiornata dell’API.

## Compatibilità delle funzionalità

**Funziona con:**

* **[Elaborazione batch](https://platform.claude.com/docs/it/build-with-claude/batch-processing):** elabora output strutturati su larga scala con uno sconto del 50 percento
* **[Conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting):** conta i token senza compilazione
* **[Streaming](https://platform.claude.com/docs/it/build-with-claude/streaming):** trasmetti in streaming gli output strutturati come le normali risposte
* **[Uso combinato](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#using-both-features-together):** usa gli output JSON (`output_config.format`) e l’uso rigoroso degli strumenti (`strict: true`) insieme nella stessa richiesta

**Incompatibile con:**

* **[Citazioni](https://platform.claude.com/docs/it/build-with-claude/citations):** le citazioni richiedono di intercalare blocchi di citazione con il testo, il che è in conflitto con i vincoli rigorosi del JSON schema. L’API restituisce un errore 400 se le citazioni sono abilitate con `output_config.format`. Per estrarre dati strutturati con una citazione per ogni valore, consulta [Ottenere dati strutturati con citazioni](https://platform.claude.com/docs/it/build-with-claude/citations#get-structured-data-with-citations).
* **Precompilazione dei messaggi:** la precompilazione è incompatibile con gli output JSON.

<Tip>
  **Ambito della grammatica:** le grammatiche si applicano solo all’output diretto di Claude, non alle chiamate di uso degli strumenti, ai risultati degli strumenti o ai tag di ragionamento (quando si usa il [ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking)). Lo stato della grammatica si reimposta tra le sezioni, consentendo a Claude di ragionare liberamente pur producendo un output strutturato nella risposta finale.
</Tip>

## Disponibilità

La funzionalità Output strutturati è disponibile su tutti i modelli e idonea per preparazione HIPAA.

### Supporto API

#### [Messages API](https://platform.claude.com/docs/it/build-with-claude/working-with-messages)

* Disponibilità: Disponibile

| Stato       | Piattaforme cloud               | Modelli                                                                |
| ----------- | ------------------------------- | ---------------------------------------------------------------------- |
| Disponibile | Tutte le piattaforme supportate | [Tutti i modelli](https://platform.claude.com/docs/it/models/overview) |

#### [Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview)

* Disponibilità: Non disponibile

### Gestione dei dati

[Panoramica sulla gestione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#feature-eligibility)

| Elemento | Conservazione zero dei dati                                                                                                                                                                                                                                                                                                                                                                       | HIPAA                                                                                                                                                                                                                                  |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stato    | Idoneo (con riserva; esclude [Modelli coperti](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#model-specific-data-retention-requirements))                                                                                                                                                                                                                              | Idoneo                                                                                                                                                                                                                                 |
| Dettagli | I tuoi prompt e gli output di Claude non vengono archiviati. Solo lo JSON schema viene memorizzato nella cache, per un massimo di 24 ore dall’ultimo utilizzo. Ciò copre anche l’uso rigoroso degli strumenti (`strict: true` sugli strumenti), che usa la stessa pipeline grammaticale. [Scopri di più](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#data-retention) | Le PHI non devono essere incluse nelle definizioni di JSON schema; consulta le linee guida sulla gestione delle PHI. [Scopri di più](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#phi-handling-guidelines) |

Endpoint applicabili:

* `/v1/messages`

I prompt e le risposte vengono elaborati con ZDR quando si usano gli output strutturati. Tuttavia, il JSON schema stesso viene temporaneamente memorizzato nella cache per un massimo di 24 ore dall’ultimo utilizzo a scopo di ottimizzazione. Nessun dato di prompt o di risposta viene conservato oltre la risposta dell’API.

Gli output strutturati sono idonei HIPAA, ma **le PHI non devono essere incluse nelle definizioni dei JSON schema**. L’API compila i JSON schema in grammatiche che vengono memorizzate nella cache separatamente dal contenuto dei messaggi, e questi schemi memorizzati nella cache non ricevono le stesse protezioni PHI dei prompt e delle risposte. Non includere PHI nei nomi delle proprietà dello schema, nei valori `enum`, nei valori `const` o nelle espressioni regolari `pattern`. Le PHI devono comparire solo nel contenuto dei messaggi (prompt e risposte), dove sono protette dalle garanzie HIPAA.

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Citazioni" icon="book-bookmark" href="https://platform.claude.com/docs/it/build-with-claude/citations">
    Fai in modo che Claude citi le sue fonti quando risponde a domande sui documenti forniti.
  </Card>

  <Card title="Uso rigoroso degli strumenti" icon="check" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use">
    Imponi la conformità a JSON Schema sugli input degli strumenti di Claude con il campionamento vincolato dalla grammatica.
  </Card>

  <Card title="Uso degli strumenti con Claude" icon="wrench" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview">
    Collega Claude a strumenti e API esterni. Scopri dove vengono eseguiti gli strumenti e come funziona il ciclo agentico.
  </Card>

  <Card title="Prezzi" icon="calculator" href="https://platform.claude.com/docs/it/about-claude/pricing">
    Scopri la struttura dei prezzi di Anthropic per modelli e funzionalità.
  </Card>
</CardGroup>
