AIREITERAnthropic Python SDK v1.0 è arrivato su PyPI il 20 agosto 2026 e, per la maggior parte dei progetti, le chiamate esistenti continueranno a funzionare senza modifiche. Il rischio vero è però meno evidente: il layer HTTP passa da httpx a httpx2. Di conseguenza tracer, agenti APM e mock di test che intercettano httpx possono continuare a girare senza però registrare più nessuna richiesta dell'SDK. Una suite verde dopo l'upgrade, da sola, dimostra molto meno di quanto sembri.
Tre release in due giorni, poi il salto alla 1.0
La cronologia delle release PyPI di anthropic riassume bene la sequenza: 0.123.0, 0.124.0 e 0.125.0 sono uscite tutte il 19 agosto 2026; il giorno successivo è arrivata la 1.0.0, pubblicata tramite il consueto Trusted Publishing.
Secondo le note di rilascio ufficiali, le novità sono queste:
- Il layer HTTP passa da
httpxahttpx2, fork mantenuto e compatibile a livello di API. - Serve Python 3.10 o successivo; i classifier includono le versioni dalla 3.10 alla 3.14.
- Viene eliminata una parte dell'API deprecata da tempo: la vecchia Text Completions API, i parametri
temperature,top_petop_knei metodi Messages, oltre acompaction_controllato client nel tool runner. AnthropicBedrockora genera un errore se non è configurata una regione AWS, anziché usare silenziosamenteus-east-1come valore predefinito.
Il tag GitHub v1.0.0 parla di "upgrade to httpx2 and some minor breaking changes". C'è inoltre un effetto collaterale facile da non notare nelle release note: l'avviso beta è sparito dagli helper parse, stream e tool_runner. Il numero 1.0, senza più riserve sulla beta, indica che Anthropic considera ormai stabile questa superficie API.
Il passaggio da httpx a httpx2 nella pratica
Se create il client senza personalizzazioni, probabilmente non cambierà nulla. Se invece intervenite sul layer HTTP, dovrete rivedere tutto.
La differenza dipende da ciò che passate al client. I valori numerici restano validi: Anthropic(timeout=30.0) si comporta come prima. Gli oggetti no: passando un normale httpx.Client tramite http_client=, il costruttore ora solleva un TypeError, senza attendere la prima richiesta. Client personalizzati, timeout e transport devono quindi essere creati con httpx2; i timeout rappresentati da oggetti httpx.Timeout diventano invece anthropic.Timeout oppure httpx2.Timeout.
# 0.x
client = Anthropic(http_client=httpx.Client(proxy="http://proxy:8080"))
# 1.0
client = Anthropic(http_client=DefaultHttpxClient(proxy="http://proxy:8080"))DefaultHttpxClient e DefaultAsyncHttpxClient non cambiano né nome né comportamento: continuano a mantenere i valori consigliati dall'SDK per timeout, pooling e redirect, ora basandosi su httpx2. L'annuncio di un dipendente Anthropic, l'ingegnere platform devx @cjav_dev, indica lo stesso punto di partenza consigliato a tutti: il file MIGRATION.md ufficiale, che documenta ogni modifica con esempi prima e dopo.
Non è la prima volta che accade. La guida alla migrazione httpx2 dell'SDK Python di OpenAI ha seguito in precedenza un percorso praticamente identico: stesso fork, stesso schema di helper DefaultHttpx2Client e gli stessi avvisi sulla compatibilità con respx. I team che hanno già migrato openai possono riutilizzare quasi integralmente la loro procedura.
Tutto ciò che v1.0 elimina
| Rimosso in v1.0 | Alternativa consigliata |
|---|---|
client.completions.create() (Text Completions) | client.messages.create() |
Costanti HUMAN_PROMPT / AI_PROMPT | Blocchi di contenuto nel formato Messages |
temperature, top_p, top_k nelle firme dei metodi | extra_body={"temperature": ...} per i modelli legacy che li accettano ancora |
messages.parse(stream=True) | messages.stream(...) |
tool_runner(compaction_control=...) | Configurazione della compattazione lato server |
Alias anthropic.Transport, anthropic.ProxiesTypes | Tipi di transport di httpx2 |
body= nei metodi di richiesta low-level | content= |
Dizionario schema output_format nelle API beta | output_config={"format": ...} (gli helper di structured output accettano ancora output_format=MyModel) |
Controlli isinstance(stream, anthropic.Stream) | Verificare il tipo concreto MessageStream |
Due note a margine sulla tabella. Pydantic v1 e v2 rimangono entrambi supportati, quindi le classi di modello non sono un problema. Inoltre, il merge degli header è ora case-insensitive: se avete mai impostato due volte lo stesso header usando maiuscole e minuscole differenti, il comportamento cambia. È un caso limite, ma non produce errori quando si manifesta.
Modifiche async che colpiscono solo chi usa le raw response
Le modifiche asincrone sono circoscritte, ma possono essere spiacevoli per chi utilizza .with_raw_response. Nel client async, parse(), read(), text() e json() richiedono ora await. Nel client sincrono, .text e .content passano da proprietà a metodi. Nessuna delle due varianti fallisce all'importazione: quella sync genera apertamente un attribute error; quella async può fallire in modo più subdolo, lasciandovi in mano una coroutine mai eseguita perché non avete fatto await.
Inoltre, gli oggetti request e response inclusi nelle eccezioni e nei risultati raw sono ora tipi httpx2. L'accesso agli attributi resta per lo più identico, ma controlli come isinstance(x, httpx.Response) e le annotazioni di tipo vanno aggiornati. È esattamente il genere di problema che pyright e mypy possono individuare.
Il problema di migrazione che non compare nei dashboard
È il punto che il changelog riduce a una sola frase, ma che il vostro monitoraggio potrebbe non perdonare. Come spiega la guida alla migrazione di Anthropic, gli strumenti che osservano o simulano il traffico HTTP intercettando httpx — OpenTelemetry, Sentry, respx, pytest-httpx, vcrpy — possono continuare a funzionare dopo l'upgrade mentre smettono silenziosamente di vedere le richieste dell'SDK. Continuano a essere importati, eseguiti e a produrre report; semplicemente non osservano più il traffico che non passa dalla libreria su cui applicano le patch. I test basati su questi mock possono quindi passare a vuoto se non verificano che l'intercettazione sia avvenuta davvero: nessuna richiesta raggiunge il mock e nulla fallisce.
La soluzione di compatibilità è httpx2.alias_httpx(), da chiamare il prima possibile durante l'avvio dell'applicazione o della suite di test. La documentazione Python SDK specifica che deve avvenire prima di qualsiasi import di httpx. In questo modo httpx2 viene esposto anche con il nome httpx, consentendo agli strumenti di patching di continuare a operare. La guida di migrazione sconsiglia però di richiamarlo nel codice di una libreria: va fatto soltanto dall'entry point dell'applicazione.
"Un avvio pulito non dimostra che le chiamate AI siano ancora tracciate o sottoposte a mock." — @MarMarLabs, post pubblicato il giorno dopo la release
Vale la pena leggere il post per intero: suggerisce di trattare questo errore invisibile come primo test di migrazione. Eseguite l'upgrade, poi verificate intenzionalmente che vengano registrate almeno una chiamata tracciata e una chiamata simulata. Nello stesso thread vengono segnalati anche gli altri rischi silenziosi: i transport personalizzati da migrare manualmente a httpx2 e il requisito minimo di Python 3.10, che può far fallire l'installazione sulle immagini CI meno recenti.
Il codice che continua a funzionare senza modifiche
Per molte codebase, la risposta più onesta è: non c'è niente da fare. La migrazione HTTP non vi riguarda se non costruite client, transport o oggetti timeout personalizzati. In particolare, non cambiano:
- Le chiamate
client.messages.create(...)con parametri standard: stessa richiesta e stessi modelli di risposta. - I timeout numerici e i valori predefiniti dell'SDK: 2 retry con backoff esponenziale per errori di connessione, 408, 409, 429 e 5xx; timeout predefinito di 10 minuti.
- Il routing tramite
base_url. Se puntate l'SDK a un gateway o a un relay compatibile con l'API, come l'endpoint Claude API di AIReiter, v1.0 non modifica quel livello: cambia il client, non l'URL. - I modelli Pydantic v1 e v2, gli helper per lo streaming SSE e le interfacce di upload file.
L'unico requisito rigido è Python 3.10+. Tutto il resto dell'elenco "sicuro" presuppone prima di superare questa soglia.
Un ordine di migrazione che regge alla code review
- Fissate deliberatamente la versione: se non siete pronti,
anthropic>=0.125,<1mantiene la situazione attuale finché non pianificate il lavoro. - Cercate nella codebase
import httpxehttpx.: ogni risultato nel codice vicino all'SDK è un elemento da migrare. - Eseguite
/claude-api upgrade pythonin Claude Code, il comando consigliato nell'annuncio di release di @cjav_dev, per ottenere un diff generato delle modifiche necessarie al progetto. - Ricostruite client personalizzati, transport e timeout usando
httpx2oppure gli helperDefaultHttpxClient. - Aggiungete
httpx2.alias_httpx()all'entry point dell'applicazione se qualcosa applica patch ahttpx. - Eseguite pyright o mypy: le modifiche di tipo introdotte da httpx2 emergono come errori nelle annotazioni e negli
isinstance. - In CI, verificate una richiesta tracciata e una richiesta mockata per ogni suite di test. I log verdi all'avvio non sono una prova.
FAQ su Anthropic Python SDK v1.0
Anthropic Python SDK v1 esiste davvero o è ancora alla serie 0.x?
Esiste. anthropic 1.0.0 è stato pubblicato su PyPI il 20 agosto 2026, con tag v1.0.0 su GitHub, dopo la 0.125.0 uscita il giorno precedente. La pagina del progetto su PyPI indirizza ora gli utenti della serie 0.x verso la guida alla migrazione v1.
Come passo temperature, top_p o top_k dopo v1.0?
Non sono più presenti nelle firme dei metodi. Per i modelli legacy che li accettano ancora lato server, passate extra_body={"temperature": 0.7}. Tenete presente che i modelli attuali restituiscono comunque un 400 per valori di sampling diversi da quelli predefiniti: è un cambiamento avvenuto a livello di modello, non nell'SDK.
I test con respx, pytest-httpx o vcrpy funzionano ancora?
Non con il client predefinito dell'SDK, e non genereranno errori: non intercetteranno nulla. Potete chiamare httpx2.alias_httpx() prima di qualsiasi import di httpx durante l'avvio dei test, oppure spostare i mock su httpx2.MockTransport. Una release di respx che applica patch solo al vecchio httpx non può intercettare il traffico dell'SDK.
Cosa fa /claude-api upgrade python?
È un comando di Claude Code, consigliato nell'annuncio dell'ingegnere devx di Anthropic @cjav_dev, che analizza un progetto basato su anthropic 0.x e produce un diff di migrazione — import, oggetti timeout, chiamate raw response — così potete esaminare le modifiche invece di scoprirle dai traceback.
Restare alla 0.125 o passare alla 1.0
Non esiste una risposta valida per tutti: ecco il compromesso reale. Restare sotto la 1.0 conserva esattamente come sono mock, tracer e transport personalizzati, ma vi lascia su un SDK precedente alla stabilità, la cui policy di versioning consente modifiche incompatibili con le versioni precedenti nelle release minori. Inoltre, la superficie deprecata da cui dipendete — completions e parametri di sampling — è ormai ufficialmente un peso morto. Passare alla 1.0 offre invece un'API stabile e non più beta, al prezzo di svolgere ora l'audit completo del layer HTTP anziché rimandarlo. Il criterio decisivo è quanto codice HTTP possedete: un servizio con una sola chiamata standard Anthropic() si aggiorna senza difficoltà, mentre una piattaforma con transport personalizzati e suite respx deve eseguire i controlli sugli errori silenziosi prima del rilascio.
Per approfondire: le Skills API uscite dalla beta nella stessa settimana e i prezzi di Sonnet 5 diventati permanenti il 10 agosto, entrambi parte dello stesso periodo di release di Claude Platform.