

Guida introduttiva all'uso dell'API per Claude

Questa guida è progettata per fornire a Claude le basi dell'utilizzo dell'API di Claude. Fornisce spiegazioni ed esempi sugli ID dei modelli/l'API messages di base, l'uso degli strumenti, lo streaming, il pensiero esteso e nient'altro.



Modelli

Smartest model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 4.6: claude-sonnet-4-6
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001



Chiamare l'API



Richiesta e risposta di base

import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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 devi sempre inviare 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.

import anthropic

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



Mettere parole in bocca a Claude

Puoi precompilare parte della risposta di Claude nell'ultima posizione della lista 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.

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. Sono supportati sia i tipi di sorgente base64 che url per le immagini, insieme ai media type image/jpeg, image/png, image/gif e image/webp.

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-opus-4-8",
    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(message.content[0].text)

# Opzione 2: immagine referenziata tramite URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url.content[0].text)



Pensiero esteso

L'"extended thinking" (pensiero esteso) può talvolta aiutare Claude con compiti molto difficili. Sui modelli precedenti a Claude Opus 4.7, la temperatura deve essere impostata a 1 quando il pensiero esteso è abilitato.

Il pensiero esteso è supportato nei seguenti modelli:

• Claude Opus 4.8 (claude-opus-4-8, solo pensiero adattivo)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)



Come funziona il pensiero esteso

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 conterrà blocchi di pensiero riassunti e blocchi di testo
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Quando si utilizza il pensiero esteso manuale (type: enabled), 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 e successivi, questo limite si applica ai token di pensiero completi e non all'output riassunto. Budget più ampi possono migliorare la qualità della risposta consentendo un'analisi più approfondita per problemi complessi. A meno che tu non stia utilizzando il pensiero intercalato, budget_tokens deve essere inferiore a max_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, 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 di pensiero: durante l'uso degli strumenti, devi passare i blocchi thinking all'API per l'ultimo messaggio dell'assistente.



Preservare i blocchi di pensiero

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 pensiero e la richiesta di strumento
response = client.messages.create(
    model="claude-opus-4-8",
    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 pensiero 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 pensiero e il risultato dello strumento
continuation = client.messages.create(
    model="claude-opus-4-8",
    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 sia il thinking_block sia il 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)



Pensiero intercalato

Il pensiero esteso con uso degli strumenti nei modelli Claude 4 supporta l'"interleaved thinking" (pensiero intercalato), che consente a Claude di pensare tra le chiamate agli strumenti. Per abilitarlo sui modelli Claude 4, 4.5 e Sonnet 4.6, aggiungi 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:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

Con il pensiero intercalato e SOLO con il pensiero intercalato (non con il pensiero esteso normale), budget_tokens può superare il parametro max_tokens, poiché budget_tokens in questo caso rappresenta il budget totale su tutti i blocchi di pensiero all'interno di un singolo 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:

{
  "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 nelle prestazioni degli strumenti. Le tue descrizioni dovrebbero spiegare ogni dettaglio sullo strumento, tra cui:

• Cosa fa lo strumento
• Quando dovrebbe essere usato (e quando non dovrebbe)
• 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 utilizzando il campo input_examples (beta). Questo aiuta Claude a comprendere i pattern di input previsti. 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 utilizzare uno strumento specifico specificando lo strumento nel campo tool_choice:

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

Quando si lavora con il parametro tool_choice, ci sono quattro opzioni possibili:

• auto consente a Claude di decidere se chiamare o meno gli strumenti forniti (predefinito).
• any indica a Claude che deve utilizzare uno degli strumenti forniti.
• tool forza 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 desideri che il modello restituisca un output JSON che segua uno schema fornito.



Catena di pensiero

Quando utilizza gli strumenti, Claude mostrerà spesso la sua "chain of thought" (catena di pensiero), ovvero il ragionamento passo dopo passo che utilizza per scomporre il problema e decidere quali strumenti utilizzare.

{
  "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ò utilizzare più strumenti per rispondere a una query dell'utente. Puoi disabilitare questo comportamento impostando disable_parallel_tool_use=true.



Gestione dei blocchi di contenuto tool use e tool result



Gestione dei risultati dagli strumenti client

La risposta avrà uno 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 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"
    }
  ]
}



Gestione dello stop reason max_tokens

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



Gestione dello stop reason pause_turn

Quando si utilizzano strumenti server come la ricerca web, l'API può restituire uno stop reason 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:

{
  "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 dello strumento non valido

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



Messaggi in streaming

Quando crei un Message, puoi impostare "stream": true per trasmettere in modo incrementale la risposta utilizzando "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-4-8",
) 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 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 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 pensiero

Quando si utilizza il pensiero esteso con lo streaming:

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



Esempio di richiesta di streaming di base

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "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"}