SDK Python

L'SDK Python di Anthropic fornisce un accesso pratico alla REST API di Anthropic dalle applicazioni Python. Supporta operazioni sia sincrone che asincrone, streaming e integrazioni con Amazon Bedrock, Vertex AI, Microsoft Foundry e Claude Platform su AWS.

Installazione

pip install anthropic

Per integrazioni specifiche per piattaforma o prestazioni asincrone migliorate, installa con gli extra:

# Per il supporto di Amazon Bedrock
pip install "anthropic[bedrock]"

# Per il supporto di Vertex AI
pip install "anthropic[vertex]"

# Per il supporto di Claude Platform su AWS
pip install "anthropic[aws]"

# Il supporto per Microsoft Foundry è incluso nel pacchetto base

# Per prestazioni asincrone migliorate con aiohttp
pip install "anthropic[aiohttp]"

Requisiti

È richiesto Python 3.9 o versione successiva.

Utilizzo

import os
from anthropic import Anthropic

client = Anthropic(
    # Questo è il valore predefinito e può essere omesso
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)

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

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione.

Utilizzo asincrono

import os
import asyncio
from anthropic import AsyncAnthropic

client = AsyncAnthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)


async def main() -> None:
    message = await client.messages.create(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Hello, Claude",
            }
        ],
        model="claude-opus-4-8",
    )
    print(message.content)


asyncio.run(main())

Utilizzo di aiohttp per una migliore concorrenza

Per prestazioni asincrone migliorate, puoi utilizzare il backend HTTP aiohttp invece del predefinito httpx:

import os
import asyncio
from anthropic import AsyncAnthropic, DefaultAioHttpClient


async def main() -> None:
    async with AsyncAnthropic(
        api_key=os.environ.get("ANTHROPIC_API_KEY"),
        http_client=DefaultAioHttpClient(),
    ) as client:
        message = await client.messages.create(
            max_tokens=1024,
            messages=[
                {
                    "role": "user",
                    "content": "Hello, Claude",
                }
            ],
            model="claude-opus-4-8",
        )
        print(message.content)


asyncio.run(main())

Risposte in streaming

L'SDK fornisce supporto per le risposte in streaming utilizzando Server-Sent Events (SSE).

client = Anthropic()

stream = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-4-8",
    stream=True,
)
for event in stream:
    print(event.type)

Il client asincrono utilizza esattamente la stessa interfaccia:

client = AsyncAnthropic()

stream = await client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-4-8",
    stream=True,
)
async for event in stream:
    print(event.type)

Helper per lo streaming

L'SDK fornisce anche helper per lo streaming che utilizzano context manager e forniscono accesso al testo accumulato e al messaggio finale:

async def main() -> None:
    async with client.messages.stream(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Say hello there!",
            }
        ],
        model="claude-opus-4-8",
    ) as stream:
        async for text in stream.text_stream:
            print(text, end="", flush=True)
        print()

        message = await stream.get_final_message()
        print(message.to_json())


asyncio.run(main())

Lo streaming con client.messages.stream(...) espone vari helper tra cui l'accumulazione ed eventi specifici dell'SDK.

In alternativa, puoi utilizzare client.messages.create(..., stream=True) che restituisce solo un iterabile degli eventi nello stream e utilizza meno memoria (non costruisce un oggetto messaggio finale per te).

Conteggio dei token

Puoi vedere l'utilizzo esatto per una determinata richiesta tramite la proprietà di risposta usage:

message = client.messages.create(...)
print(message.usage)
# Usage(input_tokens=25, output_tokens=13)

Puoi anche contare i token prima di effettuare una richiesta:

count = client.messages.count_tokens(
    model="claude-opus-4-8", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens)  # 10

Uso degli strumenti

Questo SDK fornisce supporto per l'uso degli strumenti, noto anche come function calling. Per maggiori dettagli, consulta Uso degli strumenti con Claude.

Helper per gli strumenti

L'SDK fornisce helper per definire ed eseguire strumenti come pure funzioni Python. Il decoratore @beta_tool genera lo schema dello strumento dalla firma della funzione e dalla docstring:

import json
from anthropic import Anthropic, beta_tool

client = Anthropic()


@beta_tool
def get_weather(location: str) -> str:
    """Get the weather for a given location.

    Args:
        location: The city and state, for example, San Francisco, CA
    Returns:
        A JSON-encoded string with the location, temperature, and weather condition.
    """
    return json.dumps(
        {
            "location": location,
            "temperature": "68°F",
            "condition": "Sunny",
        }
    )


# Usa il tool_runner per gestire automaticamente le chiamate agli strumenti
runner = client.beta.messages.tool_runner(
    max_tokens=1024,
    model="claude-opus-4-8",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

A ogni iterazione viene effettuata una richiesta API. Se Claude vuole chiamare uno degli strumenti forniti, questo viene chiamato automaticamente e il risultato viene restituito direttamente al modello nell'iterazione successiva.

Batch di messaggi

Questo SDK fornisce supporto per la Message Batches API sotto client.messages.batches.

Creazione di un batch

Message Batches accetta un array di richieste, dove ogni oggetto ha un identificatore custom_id e gli stessi params di richiesta della Messages API standard:

client.messages.batches.create(
    requests=[
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-8",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello, world"}],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-8",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hi again, friend"}],
            },
        },
    ]
)

Ottenere i risultati da un batch

Una volta che un Message Batch è stato elaborato, indicato da .processing_status == 'ended', puoi accedere ai risultati con .batches.results():

client = anthropic.Anthropic()
batch_id = "batch_abc123"
result_stream = client.messages.batches.results(batch_id)
for entry in result_stream:
    if entry.result.type == "succeeded":
        print(entry.result.message.content)

Caricamento di file

I parametri di richiesta che corrispondono a caricamenti di file possono essere passati in molte forme diverse:

• Un oggetto PathLike (ad esempio, pathlib.Path)
• Una tupla di (filename, content, content_type)
• Un oggetto file-like BinaryIO

from pathlib import Path
from anthropic import Anthropic

client = Anthropic()

# Carica usando un percorso di file
client.beta.files.upload(
    file=Path("/path/to/file"),
)

# Carica usando i byte
client.beta.files.upload(
    file=("file.txt", b"my bytes", "text/plain"),
)

Il client asincrono utilizza esattamente la stessa interfaccia. Se passi un'istanza PathLike, il contenuto del file viene letto automaticamente in modo asincrono.

Gestione degli errori

Quando la libreria non è in grado di connettersi all'API, o se l'API restituisce un codice di stato non di successo (ovvero una risposta 4xx o 5xx), viene sollevata una sottoclasse di APIError:

import anthropic
# ...
try:
    message = client.messages.create(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Hello, Claude",
            }
        ],
        model="claude-opus-4-8",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx
except anthropic.RateLimitError as e:
    print("A 429 status code was received; we should back off a bit.")
except anthropic.APIStatusError as e:
    print("Another non-200-range status code was received")
    print(e.status_code)
    print(e.response)

I codici di errore sono i seguenti:

ID delle richieste

Per maggiori informazioni sul debug delle richieste, consulta Request ID.

Tutte le risposte oggetto nell'SDK forniscono una proprietà _request_id che viene aggiunta dall'header di risposta request-id in modo che tu possa registrare rapidamente le richieste non riuscite e segnalarle ad Anthropic.

message = client.messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-4-8",
)
print(message._request_id)  # e.g., req_018EeWyXxfu5pfWkrYcMdjWG

Tentativi di ripetizione

Alcuni errori vengono ritentati automaticamente 2 volte per impostazione predefinita, con un breve backoff esponenziale. Gli errori di connessione (ad esempio, a causa di un problema di connettività di rete), 408 Request Timeout, 409 Conflict, 429 Rate Limit e gli errori interni >=500 vengono tutti ritentati per impostazione predefinita.

Puoi utilizzare l'opzione max_retries per configurare o disabilitare questo comportamento:

# Configura il valore predefinito per tutte le richieste:
client = Anthropic(
    max_retries=0,  # default is 2
)

# Oppure, configura per singola richiesta:
client.with_options(max_retries=5).messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-4-8",
)

Timeout

Per impostazione predefinita le richieste vanno in timeout dopo 10 minuti. Puoi configurare questo comportamento con un'opzione timeout, che accetta un float o un oggetto httpx.Timeout:

import httpx
from anthropic import Anthropic

# Configura il valore predefinito per tutte le richieste:
client = Anthropic(
    timeout=20.0,  # 20 seconds (default is 10 minutes)
)

# Controllo più granulare:
client = Anthropic(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Sovrascrivi per singola richiesta:
client.with_options(timeout=5.0).messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-4-8",
)

In caso di timeout, viene sollevato un APITimeoutError.

Nota che le richieste che vanno in timeout verranno ritentate due volte per impostazione predefinita.

Richieste lunghe

Evita di impostare un valore max_tokens elevato senza utilizzare lo streaming. Alcune reti potrebbero interrompere le connessioni inattive dopo un certo periodo di tempo, il che può causare il fallimento della richiesta o il timeout senza ricevere una risposta da Anthropic.

L'SDK solleverà un ValueError se si prevede che una richiesta non in streaming richieda più di circa 10 minuti. Passare stream=True o sovrascrivere l'opzione timeout a livello di client o di richiesta disabilita questo errore.

Una latenza di richiesta prevista più lunga del timeout per una richiesta non in streaming comporterà la terminazione della connessione da parte del client e un nuovo tentativo senza ricevere una risposta.

L'SDK imposta un'opzione TCP socket keep-alive per ridurre l'impatto dei timeout delle connessioni inattive su alcune reti. Questo può essere sovrascritto passando un'opzione http_client personalizzata al client.

Paginazione automatica

I metodi di elenco nell'API di Claude sono paginati. Puoi utilizzare la sintassi for per iterare attraverso gli elementi di tutte le pagine:

client = Anthropic()

all_batches = []
# Recupera automaticamente altre pagine secondo necessità.
for batch in client.messages.batches.list(limit=20):
    all_batches.append(batch)
print(all_batches)

Per l'iterazione asincrona:

async def main() -> None:
    all_batches = []
    async for batch in client.messages.batches.list(limit=20):
        all_batches.append(batch)
    print(all_batches)


asyncio.run(main())

In alternativa, puoi utilizzare i metodi .has_next_page(), .next_page_info() o .get_next_page() per un controllo più granulare nel lavorare con le pagine:

first_page = await client.messages.batches.list(limit=20)

if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.data)}")

# Rimuovi `await` per l'uso non asincrono.

Oppure lavorare direttamente con i dati restituiti:

first_page = await client.messages.batches.list(limit=20)

print(f"next page cursor: {first_page.last_id}")
for batch in first_page.data:
    print(batch.id)

# Rimuovi `await` per l'uso non asincrono.

Header predefiniti

L'SDK invia automaticamente l'header anthropic-version impostato su 2023-06-01.

Se necessario, puoi sovrascriverlo impostando header predefiniti sull'oggetto client o per singola richiesta.

# Imposta header predefiniti per tutte le richieste sul client
client = Anthropic(
    default_headers={"anthropic-version": "My-Custom-Value"},
)

# Oppure sovrascrivi per singola richiesta
client.messages.with_raw_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-4-8",
    extra_headers={"anthropic-version": "My-Custom-Value"},
)

Sistema di tipi

Parametri di richiesta

I parametri di richiesta annidati sono TypedDict. Le risposte sono modelli Pydantic che hanno anche metodi helper per operazioni come la serializzazione in JSON (v1, v2).

Richieste e risposte tipizzate forniscono completamento automatico e documentazione all'interno del tuo editor. Se desideri vedere gli errori di tipo in VS Code per aiutarti a individuare i bug in anticipo, imposta python.analysis.typeCheckingMode su basic.

Modelli di risposta

Per convertire un modello Pydantic in un dizionario, utilizza i metodi helper:

message = client.messages.create(...)

# Converti in stringa JSON
json_str = message.to_json()

# Converti in dizionario
data = message.to_dict()

Gestione di campi null vs mancanti

Nelle risposte, puoi distinguere tra campi che sono esplicitamente null e campi che non sono stati restituiti (mancanti):

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
if response.my_field is None:
    if "my_field" not in response.model_fields_set:
        print("field was not in the response")
    else:
        print("field was null")

Utilizzo avanzato

Accesso ai dati di risposta grezzi (ad esempio, header)

La Response "grezza" restituita da httpx è accessibile tramite la proprietà .with_raw_response sul client. Questo è utile per accedere agli header di risposta o ad altri metadati:

client = Anthropic()

response = client.messages.with_raw_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-4-8",
)

print(response.headers.get("request-id"))
message = (
    response.parse()
)  # get the object that `messages.create()` would have returned
print(message.content)

Questi metodi restituiscono un oggetto APIResponse.

Streaming del corpo della risposta

L'approccio .with_raw_response legge avidamente l'intero corpo della risposta quando effettui la richiesta. Per eseguire invece lo streaming del corpo della risposta, utilizza .with_streaming_response, che richiede un context manager e legge il corpo della risposta solo quando chiami .read(), .text(), .json(), .iter_bytes(), .iter_text(), .iter_lines() o .parse(). Nel client asincrono, questi sono metodi asincroni.

with client.messages.with_streaming_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-4-8",
) as response:
    print(response.headers.get("request-id"))

    for line in response.iter_lines():
        print(line)

Il context manager è necessario affinché la risposta venga chiusa in modo affidabile.

Logging

L'SDK utilizza il modulo logging della libreria standard.

Puoi abilitare il logging impostando la variabile d'ambiente ANTHROPIC_LOG su debug o info:

export ANTHROPIC_LOG=debug

Effettuare richieste personalizzate/non documentate

Questa libreria è tipizzata per un accesso pratico all'API documentata. Se hai bisogno di accedere a endpoint, parametri o proprietà di risposta non documentati, la libreria può comunque essere utilizzata.

Endpoint non documentati

Per effettuare richieste a endpoint non documentati, puoi utilizzare client.get, client.post e altri verbi HTTP. Le opzioni sul client, come i tentativi di ripetizione, verranno rispettate quando si effettuano queste richieste.

import httpx

response = client.post(
    "/foo",
    cast_to=httpx.Response,
    body={"my_param": True},
)

print(response.json())

Parametri di richiesta non documentati

Se vuoi inviare esplicitamente un parametro extra, puoi farlo con le opzioni di richiesta extra_query, extra_body ed extra_headers.

Proprietà di risposta non documentate

Per accedere a proprietà di risposta non documentate, puoi accedere ai campi extra come response.unknown_prop. Puoi anche ottenere tutti i campi extra sul modello Pydantic come dict con response.model_extra.

Configurazione del client HTTP

Puoi sovrascrivere direttamente il client httpx per personalizzarlo per il tuo caso d'uso, incluso il supporto per proxy e transport:

import httpx
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    # Oppure usa la variabile d'ambiente `ANTHROPIC_BASE_URL`
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Puoi anche personalizzare il client per singola richiesta utilizzando with_options():

client.with_options(http_client=DefaultHttpxClient(...))

Gestione delle risorse HTTP

Per impostazione predefinita la libreria chiude le connessioni HTTP sottostanti ogni volta che il client viene sottoposto a garbage collection. Puoi chiudere manualmente il client utilizzando il metodo .close() se lo desideri, oppure con un context manager che chiude all'uscita.

with Anthropic() as client:
    message = client.messages.create(...)

# Il client HTTP viene chiuso automaticamente

Funzionalità beta

Le funzionalità beta sono disponibili prima del rilascio generale per ottenere feedback anticipato e testare nuove funzionalità. Puoi verificare la disponibilità di tutte le capacità e gli strumenti di Claude nella panoramica di build with Claude.

Puoi accedere alla maggior parte delle funzionalità API beta tramite la proprietà beta del client. Per abilitare una particolare funzionalità beta, devi aggiungere l'header beta appropriato al campo betas quando crei un messaggio.

Ad esempio, per utilizzare la Files API:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": "file_abc123",
                    },
                },
            ],
        },
    ],
    betas=["files-api-2025-04-14"],
)

Integrazioni con piattaforme

Tutte e cinque le classi client sono incluse nel pacchetto base anthropic:

Il client AnthropicAWS è in beta. Passa workspace_id al costruttore o imposta la variabile d'ambiente ANTHROPIC_AWS_WORKSPACE_ID.

Utilizza AnthropicBedrockMantle per i nuovi progetti; AnthropicBedrock rimane per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

Versionamento semantico

Questo pacchetto segue generalmente le convenzioni SemVer, anche se alcune modifiche non retrocompatibili possono essere rilasciate come versioni minori:

1. Modifiche che influenzano solo i tipi statici, senza interrompere il comportamento a runtime.
2. Modifiche agli elementi interni della libreria che sono tecnicamente pubblici ma non destinati o documentati per uso esterno.
3. Modifiche che non si prevede abbiano un impatto sulla stragrande maggioranza degli utenti nella pratica.

Determinare la versione installata

Se hai eseguito l'aggiornamento all'ultima versione ma non vedi le nuove funzionalità che ti aspettavi, il tuo ambiente Python sta probabilmente ancora utilizzando una versione precedente. Puoi determinare la versione utilizzata a runtime con:

print(anthropic.__version__)

Risorse aggiuntive

• Repository GitHub
• Riferimento API
• Messaggi in streaming
• Uso degli strumenti con Claude