# Guida introduttiva all'API per Claude

> Questa guida è progettata per fornire a Claude le basi dell'utilizzo dell'API Claude. Fornisce spiegazioni ed esempi di ID modello/API messaggi di base, uso degli strumenti, streaming, pensiero esteso, e nient'altro.

# Guida introduttiva all'API per Claude

> Questa guida è progettata per fornire a Claude le basi dell'utilizzo dell'API Claude. Fornisce spiegazioni ed esempi di ID modello/API messaggi di base, uso degli strumenti, streaming, pensiero esteso, e nient'altro.

## Modelli

```
Modello più intelligente: Claude Sonnet 4.5: claude-sonnet-4-5-20250929
Per attività veloci e convenienti: Claude Haiku 4.5: claude-haiku-4-5-20251001
```

## Chiamare l'API

### Richiesta e risposta di base

```python  theme={null}
import anthropic
import os

message = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY")).messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Ciao, Claude"}
    ]
)
print(message)
```

```json  theme={null}
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ciao!"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}
```

### Turni conversazionali multipli

L'API Messages è stateless, il che significa che invii sempre l'intera cronologia conversazionale all'API. Puoi utilizzare questo pattern per costruire una conversazione nel tempo. I turni conversazionali precedenti non devono necessariamente provenire effettivamente da Claude — puoi utilizzare messaggi `assistant` sintetici.

```python  theme={null}
import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Ciao, Claude"},
        {"role": "assistant", "content": "Ciao!"},
        {"role": "user", "content": "Puoi descrivermi gli LLM?"}
    ],
)
print(message)
```

### Mettere parole in bocca a Claude

Puoi pre-riempire parte della risposta di Claude nell'ultima posizione dell'elenco dei messaggi di input. Questo può essere utilizzato per modellare la risposta di Claude. L'esempio seguente utilizza `"max_tokens": 1` per ottenere una singola risposta a scelta multipla da Claude.

```python  theme={null}
message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {"role": "user", "content": "Qual è il latino per Formica? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"},
        {"role": "assistant", "content": "La risposta è ("}
    ]
)
```

### Visione

Claude può leggere sia testo che immagini nelle richieste. Supportiamo sia i tipi di sorgente `base64` che `url` per le immagini, e i tipi di media `image/jpeg`, `image/png`, `image/gif`, e `image/webp`.

```python  theme={null}
import anthropic
import base64
import httpx

# Opzione 1: Immagine codificata in Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Cosa c'è nell'immagine sopra?"
                }
            ],
        }
    ],
)

# Opzione 2: Immagine referenziata tramite URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {
                    "type": "text",
                    "text": "Cosa c'è nell'immagine sopra?"
                }
            ],
        }
    ],
)
```

## Pensiero esteso

Il pensiero esteso può talvolta aiutare Claude con compiti molto difficili. Quando è abilitato, la temperatura deve essere impostata a 1.

Il pensiero esteso è supportato nei seguenti modelli:

* Claude Opus 4.1 (`claude-opus-4-1-20250805`)
* Claude Opus 4 (`claude-opus-4-20250514`)
* Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)

### Come funziona il pensiero esteso

Quando il pensiero esteso è attivato, Claude crea blocchi di contenuto `thinking` dove produce il suo ragionamento interno. La risposta dell'API includerà blocchi di contenuto `thinking`, seguiti da blocchi di contenuto `text`.

```python  theme={null}
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "Esistono un numero infinito di numeri primi tali che n mod 4 == 3?"
    }]
)

# La risposta conterrà blocchi di pensiero riassunti e blocchi di testo
for block in response.content:
    if block.type == "thinking":
        print(f"\nRiassunto del pensiero: {block.thinking}")
    elif block.type == "text":
        print(f"\nRisposta: {block.text}")
```

Il parametro `budget_tokens` determina il numero massimo di token che Claude può utilizzare per il suo processo di ragionamento interno. Nei modelli Claude 4, questo limite si applica ai token di pensiero completi, e non all'output riassunto. Budget più grandi possono migliorare la qualità della risposta consentendo un'analisi più approfondita per problemi complessi. Una regola: il valore di max\_tokens deve essere strettamente maggiore del valore di budget\_tokens in modo che Claude abbia spazio per scrivere la sua risposta dopo che il pensiero è completato.

## Pensiero esteso con uso degli strumenti

Il pensiero esteso può essere utilizzato insieme all'uso degli strumenti, permettendo a Claude di ragionare attraverso la selezione degli strumenti e l'elaborazione dei risultati.

Limitazioni importanti:

1. **Limitazione della scelta degli strumenti**: Supporta solo `tool_choice: {"type": "auto"}` (predefinito) o `tool_choice: {"type": "none"}`.
2. **Preservare i blocchi di pensiero**: Durante l'uso degli strumenti, devi passare i blocchi `thinking` di nuovo all'API per l'ultimo messaggio dell'assistente.

### Preservare i blocchi di pensiero

```python  theme={null}
# Prima richiesta - Claude risponde con pensiero e richiesta di strumento
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Che tempo fa a Parigi?"}
    ]
)

# Estrai il blocco di pensiero e il blocco di uso dello strumento
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 pensiero e il risultato dello strumento
continuation = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Che tempo fa a Parigi?"},
        # Nota che il thinking_block viene passato insieme 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"Temperatura attuale: {weather_data['temperature']}°F"
        }]}
    ]
)
```

### Pensiero interlacciato

Il pensiero esteso con uso degli strumenti nei modelli Claude 4 supporta il pensiero interlacciato, che consente a Claude di pensare tra le chiamate agli strumenti. Per abilitarlo, aggiungi l'header beta `interleaved-thinking-2025-05-14` alla tua richiesta API.

```python  theme={null}
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    messages=[{
        "role": "user",
        "content": "Qual è il ricavo totale se abbiamo venduto 150 unità del prodotto A a $50 ciascuna?"
    }],
    betas=["interleaved-thinking-2025-05-14"]
)
```

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

## Uso degli Strumenti

### Specificare strumenti client

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

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

```json  theme={null}
{
  "name": "get_weather",
  "description": "Ottieni il tempo attuale in una determinata località",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "La città e lo stato, ad es. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "L'unità di temperatura, 'celsius' o 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}
```

### Migliori pratiche per le definizioni degli strumenti

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

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

Esempio di una buona descrizione dello strumento:

```json  theme={null}
{
  "name": "get_stock_price",
  "description": "Recupera il prezzo attuale delle azioni per un determinato simbolo ticker. Il simbolo ticker deve essere un simbolo valido per una società quotata in borsa su una borsa valori statunitense principale come NYSE o NASDAQ. Lo strumento restituirà l'ultimo prezzo di scambio in USD. Dovrebbe essere utilizzato quando l'utente chiede del prezzo attuale o più recente di un'azione specifica. Non fornirà altre informazioni sull'azione o sulla società.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Il simbolo ticker dell'azione, ad es. AAPL per Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}
```

## Controllare l'output di Claude

### Forzare l'uso degli strumenti

Puoi forzare Claude a utilizzare uno strumento specifico specificando lo strumento nel campo `tool_choice`:

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

Quando lavori con il parametro tool\_choice, abbiamo quattro opzioni possibili:

* `auto` permette a Claude di decidere se chiamare uno qualsiasi degli strumenti forniti o meno (predefinito).
* `any` dice a Claude che deve utilizzare uno degli strumenti forniti.
* `tool` ci permette di forzare Claude a utilizzare sempre uno strumento particolare.
* `none` impedisce a Claude di utilizzare qualsiasi strumento.

### Output JSON

Gli strumenti non devono necessariamente essere funzioni client — puoi utilizzare gli strumenti ogni volta che vuoi che il modello restituisca un output JSON che segue uno schema fornito.

### Catena di pensiero

Quando utilizza gli strumenti, Claude mostrerà spesso la sua "catena di pensiero", cioè il ragionamento passo dopo passo che utilizza per scomporre il problema e decidere quali strumenti utilizzare.

```json  theme={null}
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Per rispondere a questa domanda, farò: 1. Utilizzare lo strumento get_weather per ottenere il tempo attuale a San Francisco. 2. Utilizzare lo strumento get_time per ottenere l'ora attuale nel fuso orario America/Los_Angeles, che copre San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}
```

### Uso parallelo degli strumenti

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

## Gestire i blocchi di contenuto di uso degli strumenti e risultato degli strumenti

### Gestire i risultati dagli strumenti client

La risposta avrà un `stop_reason` di `tool_use` e uno o più blocchi di contenuto `tool_use` che includono:

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

Quando ricevi una risposta di uso dello strumento, dovresti:

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

```json  theme={null}
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 gradi"
    }
  ]
}
```

### Gestire il motivo di arresto `max_tokens`

Se la risposta di Claude viene interrotta a causa del raggiungimento del limite `max_tokens` durante l'uso degli strumenti, riprova la richiesta con un valore `max_tokens` più alto.

### Gestire il motivo di arresto `pause_turn`

Quando si utilizzano strumenti server come la ricerca web, l'API può restituire un motivo di arresto `pause_turn`. Continua la conversazione passando 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  theme={null}
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: il servizio API meteo non è disponibile (HTTP 500)",
      "is_error": true
    }
  ]
}
```

### Nome dello strumento non valido

Se il tentativo di utilizzo di uno strumento da parte di Claude non è valido (ad es. parametri richiesti mancanti), riprova la richiesta con valori `description` più dettagliati nelle tue definizioni degli strumenti.

## Streaming dei Messaggi

Quando crei un Messaggio, puoi impostare `"stream": true` per trasmettere incrementalmente la risposta utilizzando eventi inviati dal server (SSE).

### Streaming con SDK

```python  theme={null}
import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Ciao"}],
    model="claude-sonnet-4-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

### Tipi di eventi

Ogni evento inviato dal server include un tipo di evento denominato e dati JSON associati. Ogni stream utilizza 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 livello superiore all'oggetto `Message` finale.
4. Un evento finale `message_stop`.

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

### Tipi di delta dei blocchi di contenuto

#### Delta del testo

```json  theme={null}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Ciao amic" }
}
```

#### Delta JSON di input

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

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

#### Delta del pensiero

Quando si utilizza il pensiero esteso con streaming:

```json  theme={null}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Lasciami risolvere questo passo dopo passo..."
  }
}
```

### Esempio di richiesta di streaming di base

```json  theme={null}
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-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": "Ciao"}}

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