---
title: Introduzione all'uso dell'API per Claude
url: https://platform.claude.com/docs/it/claude_api_primer
description: Questa guida è pensata per fornire a Claude le basi dell'uso della Claude API. Fornisce spiegazioni ed esempi sugli ID dei modelli/l'API Messages di base, l'uso degli strumenti, lo streaming, il thinking e nient'altro.
---

# Introduzione all'uso dell'API per Claude

> Questa guida è pensata per fornire a Claude le basi dell'uso della Claude API. Fornisce spiegazioni ed esempi sugli ID dei modelli/l'API Messages di base, l'uso degli strumenti, lo streaming, il thinking e nient'altro.

## Modelli

```text wrap
Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2.5x Claude Opus 5.5 pricing: Claude Fable 5.1: claude-fable-5-1
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001
```

## Chiamare l'API

### Richiesta e risposta di base

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{"role": "user", "content": "Hello, Claude"}'
  ```

  ```python Python
  import anthropic

  message = anthropic.Anthropic().messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello, Claude"}],
  )
  print(message)
  ```
</CodeGroup>

```json Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}
```

### Turni conversazionali multipli

L'API Messages è stateless (senza stato), il che significa che invii sempre all'API l'intera cronologia della conversazione. Puoi usare questo schema per costruire una conversazione nel tempo. I turni conversazionali precedenti non devono necessariamente provenire effettivamente da Claude. Puoi usare messaggi `assistant` sintetici.

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  messages:
    - role: user
      content: Hello, Claude
    - role: assistant
      content: Hello!
    - role: user
      content: Can you describe LLMs to me?
  YAML
  ```

  ```python Python
  import anthropic

  message = anthropic.Anthropic().messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[
          {"role": "user", "content": "Hello, Claude"},
          {"role": "assistant", "content": "Hello!"},
          {"role": "user", "content": "Can you describe LLMs to me?"},
      ],
  )
  print(message)
  ```
</CodeGroup>

### Precompilare la risposta di Claude

Puoi precompilare ("prefill") parte della risposta di Claude nell'ultima posizione della lista dei messaggi di input. Usa questa tecnica per modellare la risposta di Claude. L'esempio seguente usa `"max_tokens": 1` per ottenere da Claude una singola risposta a scelta multipla.

<Note>
  I modelli Claude 4.6 e successivi e Claude Mythos Preview non supportano il prefill dei messaggi assistant; le richieste a questi modelli devono terminare con un messaggio user. Gli esempi seguenti usano un modello che supporta il prefill.
</Note>

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-4-5
  max_tokens: 1
  messages:
    - role: user
      content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"
    - role: assistant
      content: "The answer is ("
  YAML
  ```

  ```python Python
  import anthropic

  message = anthropic.Anthropic().messages.create(
      model="claude-sonnet-4-5",
      max_tokens=1,
      messages=[
          {
              "role": "user",
              "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
          },
          {"role": "assistant", "content": "The answer is ("},
      ],
  )
  print(message.content[0].text)
  ```
</CodeGroup>

### Visione

Claude può leggere sia testo che immagini nelle richieste. Per le immagini sono supportati sia il tipo di sorgente `base64` che `url`, insieme ai tipi di media `image/jpeg`, `image/png`, `image/gif` e `image/webp`.

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg"

  # Opzione 1: immagine codificata in Base64 (il prefisso @ codifica automaticamente i file binari in base64)
  curl -sSo vision-example.jpg "$IMAGE_URL"

  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  messages:
    - role: user
      content:
        - type: image
          source:
            type: base64
            media_type: image/jpeg
            data: "@./vision-example.jpg"
        - type: text
          text: What is in the above image?
  YAML

  # Opzione 2: immagine referenziata tramite URL
  ant messages create <<YAML
  model: claude-opus-5-5
  max_tokens: 1024
  messages:
    - role: user
      content:
        - type: image
          source:
            type: url
            url: $IMAGE_URL
        - type: text
          text: What is in the above image?
  YAML
  ```

  ```python Python
  import anthropic
  import base64
  import httpx2

  # Opzione 1: immagine codificata in Base64
  image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
  image_media_type = "image/jpeg"
  image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

  message = anthropic.Anthropic().messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "image",
                      "source": {
                          "type": "base64",
                          "media_type": image_media_type,
                          "data": image_data,
                      },
                  },
                  {"type": "text", "text": "What is in the above image?"},
              ],
          }
      ],
  )
  print(next(block.text for block in message.content if block.type == "text"))

  # Opzione 2: immagine referenziata tramite URL
  message_from_url = anthropic.Anthropic().messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "image",
                      "source": {
                          "type": "url",
                          "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                      },
                  },
                  {"type": "text", "text": "What is in the above image?"},
              ],
          }
      ],
  )
  print(next(block.text for block in message_from_url.content if block.type == "text"))
  ```
</CodeGroup>

## Ragionamento

Il "thinking" (ragionamento) a volte può aiutare Claude con compiti molto difficili. Il meccanismo attuale è il [ragionamento adattivo](https://platform.claude.com/docs/it/build-with-claude/thinking) (`thinking: {"type": "adaptive"}`): Claude determina quando e quanto ragionare, e tu controlli la profondità del ragionamento con il parametro [`effort`](https://platform.claude.com/docs/it/build-with-claude/effort) anziché con un budget di token. Il ragionamento adattivo è supportato sui modelli Claude 4.6 e successivi e su Claude Mythos Preview. Sui modelli Claude 5 e successivi e su Claude Mythos Preview, il ragionamento è attivo per impostazione predefinita quando il parametro `thinking` viene omesso.

La temperatura deve essere impostata a 1 (o lasciata non impostata) ogni volta che il ragionamento è abilitato, su tutti i modelli. Sui modelli Claude 4.7 e successivi e su Claude Mythos Preview, `temperature` è deprecato e viene accettato solo il suo valore predefinito, anche quando il ragionamento è disattivato.

Il ragionamento è supportato nei seguenti modelli:

* Claude Opus 5.5 (`claude-opus-5-5`, solo ragionamento adattivo, sempre attivo)
* Claude Sonnet 5.5 (`claude-sonnet-5-5`, solo ragionamento adattivo, attivo per impostazione predefinita; `thinking: {"type": "disabled"}` restituisce un errore 400, quindi invia `thinking: {"type": "between_tools"}` per disattivare il ragionamento iniziale)
* Claude Haiku 5.5 (`claude-haiku-5-5`, solo ragionamento adattivo, attivo per impostazione predefinita)
* Claude Fable 5.1 (`claude-fable-5-1`, solo ragionamento adattivo, sempre attivo)
* Claude Mythos 5.1 (`claude-mythos-5-1`, solo ragionamento adattivo, sempre attivo)
* Claude Fable 5 (`claude-fable-5`, solo ragionamento adattivo, sempre attivo)
* Claude Mythos 5 (`claude-mythos-5`, solo ragionamento adattivo, sempre attivo)
* Claude Opus 5 (claude-opus-5, solo ragionamento adattivo, attivo per impostazione predefinita)
* Claude Sonnet 5 (`claude-sonnet-5`, solo ragionamento adattivo, attivo per impostazione predefinita)
* Claude Opus 4.8 (claude-opus-4-8, solo ragionamento adattivo)
* Claude Opus 4.7 (`claude-opus-4-7`, solo ragionamento adattivo)
* Claude Opus 4.6 (`claude-opus-4-6`, ragionamento adattivo o manuale legacy)
* Claude Sonnet 4.6 (`claude-sonnet-4-6`, ragionamento adattivo o manuale legacy)
* Claude Opus 4.5 (`claude-opus-4-5-20251101`, solo ragionamento manuale legacy)
* Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`, [deprecato](https://platform.claude.com/docs/it/about-claude/model-deprecations), solo ragionamento manuale legacy)
* Claude Haiku 4.5 (`claude-haiku-4-5-20251001`, solo ragionamento manuale legacy)

<Note>
  Sui modelli Claude 4.7 e successivi, il ragionamento esteso manuale (`type: enabled` con un valore `budget_tokens`) non è supportato e restituisce un errore 400. Usa invece il [ragionamento adattivo](https://platform.claude.com/docs/it/build-with-claude/thinking) (`type: adaptive`).
</Note>

### Come funziona il thinking

Quando il thinking è attivo, Claude crea blocchi di contenuto `thinking` in cui emette il proprio ragionamento interno. La risposta dell'API include blocchi di contenuto `thinking`, seguiti da blocchi di contenuto `text`.

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create --transform content --format yaml <<'YAML'
  model: claude-opus-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
    display: summarized
  messages:
    - role: user
      content: Are there an infinite number of prime numbers such that n mod 4 == 3?
  YAML
  ```

  ```python Python
  import anthropic

  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=16000,
      thinking={"type": "adaptive", "display": "summarized"},
      messages=[
          {
              "role": "user",
              "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
          }
      ],
  )

  # La risposta contiene blocchi di ragionamento riassunti e blocchi di testo
  for block in response.content:
      match block.type:
          case "thinking":
              print(f"\nThinking summary: {block.thinking}")
          case "text":
              print(f"\nResponse: {block.text}")
  ```
</CodeGroup>

Il "manual extended thinking" (ragionamento esteso manuale) (`thinking: {"type": "enabled", "budget_tokens": N}`) è il meccanismo legacy. Funziona solo sui modelli da Claude 4 a 4.6 che supportano il thinking; i modelli Claude 4.7 e successivi rifiutano `type: enabled` con un errore 400 e usano invece l'[adaptive thinking](https://platform.claude.com/docs/it/build-with-claude/thinking). Con il ragionamento esteso manuale, `budget_tokens` imposta il numero massimo di token che Claude può usare per il proprio processo di ragionamento interno; il limite si applica ai token di thinking completi, non all'output riassunto. A meno che tu non stia usando il [ragionamento interlacciato](https://platform.claude.com/docs/it/claude_api_primer#interleaved-thinking), `budget_tokens` deve essere inferiore a `max_tokens` in modo che Claude abbia spazio per scrivere la sua risposta dopo il completamento del thinking.

## Thinking con l'uso degli strumenti

Il thinking può essere usato insieme al "tool use" (uso degli strumenti), consentendo a Claude di ragionare sulla selezione degli strumenti e sull'elaborazione dei risultati.

Limitazioni importanti:

1. **Limitazione sulla scelta dello strumento:** Con il ragionamento esteso manuale (`thinking: {"type": "enabled"}`), è supportato solo `tool_choice: {"type": "auto"}` (predefinito) o `tool_choice: {"type": "none"}`. Il ragionamento adattivo accetta l'uso forzato degli strumenti, tranne sui modelli elencati in [Forzare l'uso degli strumenti](https://platform.claude.com/docs/it/claude_api_primer#forcing-tool-use). Dove è accettata, una chiamata forzata a uno strumento salta il ragionamento: la risposta inizia con la chiamata allo strumento e non contiene alcun blocco `thinking`.
2. **Preservare i blocchi thinking:** Durante l'uso degli strumenti, devi ripassare all'API i blocchi `thinking` dell'ultimo messaggio assistant.

### Preservare i blocchi thinking

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  # Prima richiesta: cattura l'array di contenuto dell'assistente (blocchi thinking + tool_use,
  # con le firme intatte) come JSON compatto.
  ASSISTANT_CONTENT=$(ant messages create \
    --transform content --format jsonl <<'YAML'
  model: claude-opus-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
    display: summarized
  tools:
    - name: get_weather
      description: Get the current weather for a location.
      input_schema:
        type: object
        properties:
          location:
            type: string
            description: The city name.
        required: [location]
  messages:
    - role: user
      content: "What's the weather in Paris?"
  YAML
  )

  TOOL_USE_ID=$(printf '%s' "$ASSISTANT_CONTENT" \
    | jq -r '.[] | select(.type == "tool_use") | .id')

  # Seconda richiesta: ripassa i blocchi catturati invariati come messaggio
  # dell'assistente. Il blocco thinking deve accompagnare il blocco tool_use.
  ant messages create <<YAML
  model: claude-opus-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
    display: summarized
  tools:
    - name: get_weather
      description: Get the current weather for a location.
      input_schema:
        type: object
        properties:
          location:
            type: string
            description: The city name.
        required: [location]
  messages:
    - role: user
      content: "What's the weather in Paris?"
    - role: assistant
      content: $ASSISTANT_CONTENT
    - role: user
      content:
        - type: tool_result
          tool_use_id: $TOOL_USE_ID
          content: "Current temperature: 72°F"
  YAML
  ```

  ```python Python
  import anthropic

  client = anthropic.Anthropic()

  weather_tool = {
      "name": "get_weather",
      "description": "Get the current weather for a location.",
      "input_schema": {
          "type": "object",
          "properties": {"location": {"type": "string", "description": "The city name."}},
          "required": ["location"],
      },
  }

  weather_data = {"temperature": 72}

  # Prima richiesta - Claude risponde con il ragionamento e una richiesta di strumento
  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=16000,
      thinking={"type": "adaptive", "display": "summarized"},
      tools=[weather_tool],
      messages=[{"role": "user", "content": "What's the weather in Paris?"}],
  )

  # Estrai il blocco di ragionamento e il blocco di uso degli strumenti
  thinking_block = next(
      (block for block in response.content if block.type == "thinking"), None
  )
  tool_use_block = next(
      (block for block in response.content if block.type == "tool_use"), None
  )

  # Seconda richiesta - Includi il blocco di ragionamento e il risultato dello strumento
  continuation = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=16000,
      thinking={"type": "adaptive", "display": "summarized"},
      tools=[weather_tool],
      messages=[
          {"role": "user", "content": "What's the weather in Paris?"},
          # Nota che viene passato il thinking_block oltre al tool_use_block
          {"role": "assistant", "content": [thinking_block, tool_use_block]},
          {
              "role": "user",
              "content": [
                  {
                      "type": "tool_result",
                      "tool_use_id": tool_use_block.id,
                      "content": f"Current temperature: {weather_data['temperature']}°F",
                  }
              ],
          },
      ],
  )

  for block in continuation.content:
      if block.type == "text":
          print(block.text)
  ```
</CodeGroup>

### Ragionamento interlacciato

L'"interleaved thinking" (ragionamento interlacciato) consente a Claude di ragionare tra una chiamata agli strumenti e l'altra, riflettendo sui risultati degli strumenti prima di determinare il passo successivo.

<Info>
  Sui modelli con [ragionamento adattivo](https://platform.claude.com/docs/it/build-with-claude/thinking) (`thinking: {type: "adaptive"}`), il ragionamento interlacciato è abilitato automaticamente. Non è necessario alcun header beta. Sonnet 4.6 supporta sia l'header beta `interleaved-thinking-2025-05-14` con il ragionamento esteso manuale sia il ragionamento adattivo.
</Info>

Sui modelli meno recenti che usano il ragionamento esteso manuale (modelli Claude 4, 4.5 e Sonnet 4.6), abilita il ragionamento interlacciato aggiungendo l'header beta `interleaved-thinking-2025-05-14` alla tua richiesta API:

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML'
  model: claude-sonnet-4-6
  max_tokens: 16000
  thinking:
    type: enabled
    budget_tokens: 10000
  tools:
    - name: calculator
      description: Perform arithmetic calculations.
      input_schema:
        type: object
        properties:
          expression:
            type: string
            description: The math expression to evaluate.
        required:
          - expression
    - name: database_query
      description: Query the product database.
      input_schema:
        type: object
        properties:
          query:
            type: string
            description: The database query.
        required:
          - query
  messages:
    - role: user
      content: "What's the total revenue if we sold 150 units of product A at $50 each?"
  YAML
  ```

  ```python Python
  import anthropic

  client = anthropic.Anthropic()

  calculator_tool = {
      "name": "calculator",
      "description": "Perform arithmetic calculations.",
      "input_schema": {
          "type": "object",
          "properties": {
              "expression": {
                  "type": "string",
                  "description": "The math expression to evaluate.",
              }
          },
          "required": ["expression"],
      },
  }

  database_tool = {
      "name": "database_query",
      "description": "Query the product database.",
      "input_schema": {
          "type": "object",
          "properties": {
              "query": {"type": "string", "description": "The database query."}
          },
          "required": ["query"],
      },
  }

  response = client.beta.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=16000,
      thinking={"type": "enabled", "budget_tokens": 10000},
      tools=[calculator_tool, database_tool],
      messages=[
          {
              "role": "user",
              "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
          }
      ],
      betas=["interleaved-thinking-2025-05-14"],
  )

  for block in response.content:
      match block.type:
          case "thinking":
              print(f"Thinking: {block.thinking}")
          case "tool_use":
              print(f"Tool call: {block.name}({block.input})")
          case "text":
              print(f"Response: {block.text}")
  ```
</CodeGroup>

Con il ragionamento interlacciato e SOLO con il ragionamento interlacciato (non con il normale ragionamento esteso manuale), `budget_tokens` può superare il parametro `max_tokens`, poiché in questo caso `budget_tokens` rappresenta il budget totale su tutti i blocchi di ragionamento all'interno di un turno dell'assistente.

## Uso degli strumenti

### Specificare gli strumenti client

Gli strumenti client sono specificati nel parametro di primo livello `tools` della richiesta API. Ogni definizione di strumento include:

| Parametro      | Descrizione                                                                                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `name`         | Il nome dello strumento. Deve corrispondere all'espressione regolare `^[a-zA-Z0-9_-]{1,128}$`.                          |
| `description`  | Una descrizione dettagliata in testo semplice di cosa fa lo strumento, quando dovrebbe essere usato e come si comporta. |
| `input_schema` | Un oggetto [JSON Schema](https://json-schema.org/) che definisce i parametri previsti per lo strumento.                 |

```json
{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}
```

### Best practice per le definizioni degli strumenti

**Fornisci descrizioni estremamente dettagliate.** Questo è di gran lunga il fattore più importante per le prestazioni degli strumenti. Le tue descrizioni dovrebbero spiegare ogni dettaglio dello strumento, tra cui:

* Cosa fa lo strumento
* Quando dovrebbe essere usato (e quando no)
* Cosa significa ogni parametro e come influisce sul comportamento dello strumento
* Eventuali avvertenze o limitazioni importanti

**Considera l'uso di `input_examples` per strumenti complessi.** Per strumenti con oggetti annidati, parametri opzionali o input sensibili al formato, puoi fornire esempi concreti usando il campo `input_examples` (beta). Questo aiuta Claude a comprendere gli schemi di input attesi. Consulta [Fornire esempi di uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) per i dettagli.

Esempio di una buona descrizione di strumento:

```json
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}
```

## Controllare l'output di Claude

### Forzare l'uso degli strumenti

Puoi forzare Claude a usare uno strumento specifico indicandolo nel campo `tool_choice`:

```python
tool_choice = {"type": "tool", "name": "get_weather"}
```

Quando lavori con il parametro `tool_choice`, ci sono quattro opzioni possibili:

* `auto` consente a Claude di decidere se chiamare o meno uno degli strumenti forniti (predefinito).
* `any` indica a Claude che deve usare uno degli strumenti forniti.
* `tool` forza Claude a usare sempre uno strumento specifico.
* `none` impedisce a Claude di usare qualsiasi strumento.

Su Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, `any` e `tool` restituiscono un errore 400. Lascia `tool_choice` su `auto` e imposta `"strict": true` nella definizione dello strumento per garantire che qualsiasi chiamata effettuata da Claude corrisponda all'`input_schema` dello strumento. Consulta [Uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use).

### Output JSON

Gli strumenti non devono necessariamente essere funzioni client. Puoi usare gli strumenti ogni volta che vuoi che il modello restituisca un output JSON che segua uno schema fornito.

### Uso parallelo degli strumenti

Per impostazione predefinita, Claude può usare più strumenti per rispondere a una richiesta dell'utente. Puoi disabilitare questo comportamento impostando `disable_parallel_tool_use=true`.

## Gestire i blocchi di contenuto tool use e tool result

### Gestire i risultati degli strumenti client

La risposta ha uno `stop_reason` pari a `tool_use` e uno o più blocchi di contenuto `tool_use` che includono:

* `id`: Un identificatore univoco per questo specifico blocco di uso dello strumento.
* `name`: Il nome dello strumento in uso.
* `input`: Un oggetto contenente l'input passato allo strumento.

```json
{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}
```

Quando ricevi una risposta di uso degli strumenti, dovresti:

1. Estrarre `name`, `id` e `input` dal blocco `tool_use`.
2. Eseguire nel tuo codice lo strumento effettivo corrispondente a quel nome di strumento.
3. Continuare la conversazione inviando un nuovo messaggio con un `tool_result`:

```json
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}
```

### Gestire lo stop reason `max_tokens`

Se la risposta di Claude viene troncata perché raggiunge il limite `max_tokens` durante l'uso degli strumenti, riprova la richiesta con un valore `max_tokens` più alto.

### Gestire lo stop reason `pause_turn`

Quando usi strumenti server come la ricerca web, l'API può restituire uno stop reason `pause_turn`. Continua la conversazione ripassando la risposta in pausa così com'è in una richiesta successiva.

## Risoluzione degli errori

### Errore di esecuzione dello strumento

Se lo strumento stesso genera un errore durante l'esecuzione, restituisci il messaggio di errore con `"is_error": true`:

```json
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}
```

### Nome di strumento non valido

Se il tentativo di Claude di usare uno strumento non è valido (ad esempio, mancano parametri obbligatori), riprova la richiesta con valori `description` più dettagliati nelle tue definizioni degli strumenti.

## Streaming dei messaggi

Quando crei un Message, puoi impostare `"stream": true` per trasmettere la risposta in modo incrementale tramite "server-sent events" (eventi inviati dal server), o SSE.

### Streaming con gli SDK

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create --stream --format jsonl \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello"}' \
    | jq -rj 'select(.delta.type? == "text_delta") | .delta.text'
  ```

  ```python Python
  import anthropic

  client = anthropic.Anthropic()

  with client.messages.stream(
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello"}],
      model="claude-opus-5-5",
  ) as stream:
      for text in stream.text_stream:
          print(text, end="", flush=True)
  ```
</CodeGroup>

### Tipi di evento

Ogni server-sent event include un tipo di evento con nome e i dati JSON associati. Ogni stream usa il seguente flusso di eventi:

1. `message_start`: contiene un oggetto `Message` con `content` vuoto.
2. Una serie di blocchi di contenuto, ciascuno con `content_block_start`, uno o più eventi `content_block_delta` e `content_block_stop`.
3. Uno o più eventi `message_delta`, che indicano modifiche di primo livello all'oggetto `Message` finale.
4. Un evento finale `message_stop`.

**Attenzione:** I conteggi dei token mostrati nel campo `usage` dell'evento `message_delta` sono *cumulativi*.

### Tipi di delta dei blocchi di contenuto

#### Delta di testo

```json
{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}
```

#### Delta JSON di input

Per i blocchi di contenuto `tool_use`, i delta sono *stringhe JSON parziali*:

```json
{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}
```

#### Delta di thinking

Quando usi il thinking con lo streaming:

```json
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}
```

### Esempio di richiesta streaming di base

```sse
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}
```