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

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 4.5: claude-haiku-4-5-20251001

Chiamare l'API

Richiesta e risposta di base

import anthropic

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

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

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)

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.

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)

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.

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"))

Thinking

Il thinking (ragionamento) può talvolta aiutare Claude con compiti molto difficili. Il meccanismo attuale è l'adaptive thinking (thinking adattivo) (thinking: {"type": "adaptive"}): Claude decide quando e quanto pensare, e tu orienti la profondità del ragionamento con il parametro effort anziché con un budget di token. L'adaptive thinking è supportato sui modelli Claude 4.6 e successivi e su Claude Mythos Preview. Sui modelli Claude 5 e su Claude Mythos Preview, il thinking è 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 thinking è 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 thinking è disattivato.

Il thinking è 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)
• 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, solo ragionamento manuale legacy)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001, solo ragionamento manuale legacy)

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.

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

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. 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 l'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: Supporta solo tool_choice: {"type": "auto"} (predefinito) o tool_choice: {"type": "none"}.
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

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)

Interleaved thinking

L'"interleaved thinking" (ragionamento interlacciato) consente a Claude di pensare tra una chiamata di strumento e l'altra, ragionando sui risultati degli strumenti prima di decidere il passo successivo.

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

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

Con l'interleaved thinking e SOLO con l'interleaved thinking (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 per tutti i blocchi thinking all'interno di un singolo turno assistant.

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:

{
  "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 per i dettagli.

Esempio di una buona descrizione di strumento:

{
  "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 indicando lo strumento nel campo tool_choice:

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 particolare.
• 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.

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.

Catena di pensiero

Quando usa gli strumenti, Claude spesso mostra la sua "chain of thought" (catena di pensiero), cioè il ragionamento passo dopo passo che usa per scomporre il problema e determinare quali strumenti usare.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers 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ò 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 usato.
• 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 nel tuo codice lo strumento effettivo corrispondente a quel nome di strumento.
3. Continuare la conversazione inviando un nuovo messaggio con un tool_result:

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

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

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)

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

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

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

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

Esempio di richiesta streaming di base

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