Guida introduttiva all'utilizzo dell'API per Claude

Questa guida è progettata per fornire a Claude le nozioni di base sull'utilizzo dell'API Claude. Fornisce spiegazioni ed esempi di ID modello/API messaggi di base, utilizzo di strumenti, streaming, extended thinking e nient'altro.

Modelli

Modello più intelligente: Claude Opus 4.7: claude-opus-4-7
Modello intelligente: Claude Sonnet 4.6: claude-sonnet-4-6
Per attività veloci ed economiche: Claude Haiku 4.5: claude-haiku-4-5-20251001

Chiamata dell'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-7",
    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-7",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Turni conversazionali multipli

L'API Messages è senza stato, il che significa che invii sempre la cronologia conversazionale completa all'API. Puoi utilizzare questo modello per costruire una conversazione nel tempo. I turni conversazionali precedenti non devono necessariamente provenire effettivamente da Claude. Puoi utilizzare messaggi sintetici di assistant.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-7",
    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 pre-compilare 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.

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 ("},
    ],
)

Visione

Claude può leggere sia testo che immagini nelle richieste. Sia i tipi di origine base64 che url sono supportati per le immagini, insieme ai tipi di media image/jpeg, image/png, image/gif e image/webp.

Extended thinking

Extended thinking può talvolta aiutare Claude con compiti molto difficili. Sui modelli precedenti a Claude Opus 4.7, la temperatura deve essere impostata a 1 quando extended thinking è abilitato.

Extended thinking è supportato nei seguenti modelli:

• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (deprecato) (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

Come funziona extended thinking

Quando extended thinking è 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.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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?",
        }
    ],
)

# The response will contain summarized thinking blocks and text blocks
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Il parametro budget_tokens determina il numero massimo di token che Claude è autorizzato a utilizzare per il suo processo di ragionamento interno. Nei modelli Claude 4, questo limite si applica ai token di thinking completo, non all'output riassunto. Budget più grandi possono migliorare la qualità della risposta abilitando 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 thinking è completo.

Extended thinking con utilizzo di strumenti

Extended thinking può essere utilizzato insieme all'utilizzo di strumenti, permettendo a Claude di ragionare sulla selezione degli strumenti e l'elaborazione dei risultati.

Limitazioni importanti:

1. Limitazione della scelta dello strumento: Supporta solo tool_choice: {"type": "auto"} (predefinito) o tool_choice: {"type": "none"}.
2. Preservazione dei blocchi thinking: Durante l'utilizzo di strumenti, devi passare i blocchi thinking all'API per l'ultimo messaggio dell'assistente.

Preservazione dei blocchi thinking

Thinking interleaved

Extended thinking con utilizzo di strumenti nei modelli Claude 4 supporta thinking interleaved, che consente a Claude di pensare tra le chiamate di strumenti. Per abilitare sui modelli Claude 4, 4.5 e Sonnet 4.6, aggiungi l'intestazione beta interleaved-thinking-2025-05-14 alla tua richiesta API.

Con thinking interleaved e SOLO con thinking interleaved (non regular extended thinking), il budget_tokens può superare il parametro max_tokens, poiché budget_tokens in questo caso rappresenta il budget totale su tutti i blocchi thinking all'interno di un turno dell'assistente.

Utilizzo di strumenti

Specifica degli strumenti client

Gli strumenti client sono specificati nel parametro tools di primo livello 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"]
  }
}

Migliori pratiche per le definizioni di strumenti

Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante per le prestazioni dello strumento. 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

Considera l'utilizzo 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 modelli di input previsti. Vedi Providing tool use examples 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"]
  }
}

Controllo dell'output di Claude

Forzare l'utilizzo di 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 dice 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 strumenti ogni volta che desideri che il modello restituisca un output JSON che segua uno schema fornito.

Catena di ragionamento

Quando si utilizzano strumenti, Claude spesso mostrerà il suo "catena di ragionamento", cioè 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" }
    }
  ]
}

Utilizzo parallelo di 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à 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 tool use.
• name: Il nome dello strumento utilizzato.
• input: Un oggetto contenente l'input passato allo strumento.

Quando ricevi una risposta tool use, 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 del motivo di arresto max_tokens

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

Gestione del motivo di arresto pause_turn

Quando si utilizzano strumenti server come web search, 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 dei problemi 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 es. parametri obbligatori mancanti), ripeti la richiesta con valori description più dettagliati nelle definizioni dei tuoi strumenti.

Streaming dei messaggi

Quando crei un Message, puoi impostare "stream": true per trasmettere in streaming incrementalmente la risposta utilizzando server-sent events (SSE).

Streaming con SDK

Tipi di evento

Ogni server-sent event include un tipo di evento denominato e dati JSON associati. Ogni stream utilizza il seguente flusso di evento:

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, indicando modifiche di primo livello all'oggetto Message finale.
4. Un evento message_stop finale.

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

Tipi di delta del blocco 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 si utilizza extended thinking con 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-7", "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"}