Claude Platform Docs
Riferimento APISupporto e configurazione

Migrazione alla versione API 2026-10-21

Aggiorna un'integrazione con la Claude API dalla versione API 2023-06-01 alla 2026-10-21: la versione dell'SDK da installare e le modifiche al codice da apportare.

Questa guida elenca le modifiche al codice necessarie per passare dalla versione API 2023-06-01 alla 2026-10-21. I passaggi di aggiornamento indicano cosa fare, in ordine.

Passaggi di aggiornamento

  1. Passa alla 2026-10-21

    Se usi un SDK, le tue richieste usano la versione API che era corrente quando è stata rilasciata la versione major del tuo SDK. Le versioni indicate per il tuo linguaggio sono le prime a usare 2026-10-21, quindi aggiorna a quelle. Se chiami l'API senza un SDK, imposta l'header anthropic-version su 2026-10-21.

    Aggiorna il pacchetto anthropic alla versione 2.0.0.

    Rilascia l'aggiornamento insieme alle correzioni del passaggio successivo.

  2. Aggiorna il tuo codice per le modifiche incompatibili

    Esamina le modifiche incompatibili e aggiorna il tuo codice per ciascuna che ti riguarda. Apporta anche le modifiche al codice richieste dalla nuova versione dell'SDK o della CLI.

  3. Testa con la 2026-10-21

    Testa la tua integrazione con 2026-10-21 prima del rilascio.

Modifiche incompatibili

Messages API

Queste modifiche si applicano alle richieste alla Messages API (POST /v1/messages), al conteggio dei token e a ogni richiesta in un Message Batch creato con 2026-10-21.

I blocchi document nei messaggi assistant restituiscono un errore

Ti riguarda se invii blocchi document direttamente nei messaggi assistant.

In 2026-10-21, una richiesta che inserisce un blocco document direttamente in un messaggio assistant restituisce un errore 400. Invia invece i documenti nei messaggi user. Un documento annidato all'interno di un altro blocco, come il risultato di uno strumento web fetch restituito da Claude, è ancora accettato.

Le citazioni nei messaggi user restituiscono un errore

Ti riguarda se invii citations su blocchi text nei messaggi user, anche all'interno di blocchi search_result.

In 2026-10-21, una richiesta che invia un blocco text con un array citations non vuoto in un messaggio user restituisce un errore 400. Rimuovi citations da quei blocchi. Le citazioni sui blocchi text nei messaggi assistant, come le risposte precedenti di Claude che rimandi indietro, sono ancora accettate, così come l'impostazione "citations": {"enabled": true} su documenti e risultati di ricerca.

I parametri di campionamento sono stati rimossi

Ti riguarda se invii temperature, top_p o top_k nelle richieste Messages o nelle richieste Message Batch.

In 2026-10-21, una richiesta che invia temperature, top_p o top_k restituisce un errore 400, anche con il valore predefinito del parametro.

Rimuovi i tre parametri dalle tue richieste.

A partire dalle ultime versioni major, l'SDK e la CLI non hanno più i tre parametri.

Senza questi parametri, una richiesta esegue il campionamento con i loro valori predefiniti, inclusa una temperature di 1.0, come una richiesta 2023-06-01 che li omette. I modelli che già accettano solo i valori predefiniti, come i modelli Claude 4.7 e successivi, eseguono il campionamento come prima. Sui modelli che accettano altri valori, come Claude Sonnet 4.6, una richiesta che abbassava temperature per ottenere un output più coerente perde quell'effetto. Nessun'altra impostazione lo sostituisce. Se una richiesta si basa su un valore non predefinito, smetti di inviare il parametro oppure mantieni quella richiesta su 2023-06-01.

Admin API e Claude Enterprise Analytics API

Ti riguarda se il tuo codice legge i campi di risposta dell'Admin API o della Claude Enterprise Analytics API riportati nelle tabelle seguenti.

In 2026-10-21, le risposte dell'Admin API e della Claude Enterprise Analytics API non includono più i vecchi nomi dei campi rinominati. Usa invece i nuovi nomi.

Admin API:

EndpointVecchio nomeNuovo nome
Gruppi RBAC: creazione, elenco, recupero e aggiornamentorolesrole_ids
Membri dei gruppi RBAC: elenco e aggiunta, e la risposta alla rimozione di un membrogroup_idrbac_group_id
Ruoli RBAC: elenco e recuperonamedisplay_name
Limiti di velocità dell'organizzazione e del workspace: elenco, e la risposta all'impostazione dei limiti di velocità di un workspacegroup_typegroup.type
Chiavi API: elenco, recupero e aggiornamentoworkspace_idscope (valori diversi; vedi workspace_id sulle chiavi API)

Claude Enterprise Analytics API:

EndpointVecchio nomeNuovo nome
Report per utente di utilizzo e costiactor.emailactor.email_address
Riepiloghi delle attivitàsummariesdata

Il parametro di query group_type sugli endpoint di elenco dei limiti di velocità e il filtro workspace_id sull'endpoint di elenco delle chiavi API restano invariati.

workspace_id sulle chiavi API

Ti riguarda se il tuo codice legge workspace_id sulle chiavi API.

In 2023-06-01, il workspace_id di una chiave API è l'ID del workspace a cui la chiave è associata, oppure null per una chiave associata al Default Workspace e per una chiave non associata a un singolo workspace (una chiave per tutti i workspace).

In 2026-10-21, workspace_id è stato rimosso. Leggi invece scope: per una chiave associata a un workspace, incluso il Default Workspace, scope.workspace_id è l'ID reale di quel workspace, e una chiave per tutti i workspace ha uno scope pari a {"type": "organization"}, senza workspace_id.

Se il tuo codice trattava un workspace_id null come il Default Workspace, confronta invece scope.workspace_id con l'ID del tuo Default Workspace. Per trovare quell'ID, chiama List Workspaces con include_default=true e prendi il workspace denominato "Default".

Modifiche all'SDK e alla CLI

Le versioni precedenti dell'SDK e della CLI inviavano anthropic-version: 2023-06-01 con ogni richiesta. Le versioni indicate in Passa alla 2026-10-21 inviano 2026-10-21. Anche a loro si applicano le modifiche descritte in Modifiche incompatibili: i parametri rimossi e i vecchi nomi dei campi sono spariti anche dai tipi dell'SDK e dai flag e dall'output della CLI.

Versione API su Amazon Bedrock e Google Cloud

Il client dell'SDK per Google Cloud's Agent Platform indica la versione nel corpo della richiesta anziché in un header. Invia anthropic_version: 2026-10-21, dove le versioni precedenti inviavano vertex-2023-10-16, e nessun header anthropic-version.

Il client Amazon Bedrock fa lo stesso. Invia anthropic_version: 2026-10-21, dove le versioni precedenti inviavano bedrock-2023-05-31, e nessun header anthropic-version. I modelli precedenti a Claude Opus 4.7 non supportano ancora la versione API 2026-10-21 su Bedrock, e una richiesta che la indica potrebbe ricevere un errore 400. Se ne usi uno, resta per ora sulla versione precedente dell'SDK, oppure aggiorna e invia tu stesso bedrock-2023-05-31.

Questo si applica a AnthropicVertex, AsyncAnthropicVertex, AnthropicBedrock e AsyncAnthropicBedrock.

Per inviare bedrock-2023-05-31, passa extra_body={"anthropic_version": "bedrock-2023-05-31"} con ogni richiesta.

MessageParam è un'unione con un tipo per ruolo

Nelle versioni precedenti, MessageParam era un unico tipo per ogni ruolo. Ora ogni ruolo ha un proprio tipo: UserMessageParam, AssistantMessageParam e SystemMessageParam. BetaMessageParam è suddiviso allo stesso modo, in BetaUserMessageParam, BetaAssistantMessageParam e BetaSystemMessageParam. Le richieste inviate dall'SDK hanno gli stessi campi e valori di prima.

Un messaggio scritto come letterale dict, come {"role": "user", "content": "Hello"}, non richiede modifiche.

Nella v1, anthropic.types.MessageParam era un unico TypedDict. Nella v2 è un'unione dei tre tipi, e anthropic.types.beta.BetaMessageParam è un'unione dei suoi tre. Entrambi i nomi funzionano ancora nelle annotazioni, come list[MessageParam].

Chiamare uno dei due nomi ora solleva un TypeError, e un type checker lo segnala. Scrivi il messaggio come dict:

# Prima
message = MessageParam(role="user", content="Hello")

# Dopo
message: MessageParam = {"role": "user", "content": "Hello"}

Anche creare una sottoclasse di uno dei due nomi solleva un TypeError. Crea una sottoclasse del tipo per il ruolo, come UserMessageParam.

Le modifiche rimanenti riguardano solo il controllo dei tipi. Un dict il cui role è una variabile che può contenere più di un ruolo non corrisponde a nessun tipo dell'unione, quindi costruisci il dict per un ruolo alla volta:

# Prima
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    return {"role": role, "content": text}


# Dopo
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    if role == "user":
        return {"role": "user", "content": text}
    return {"role": "assistant", "content": text}

Altre due si applicano solo a BetaMessageParam:

  • clear_at e output_config sono chiavi di BetaSystemMessageParam, quindi un messaggio user o assistant non può averle.
  • content è facoltativo in BetaSystemMessageParam, quindi pyright segnala message["content"]. Leggilo con message.get("content"), oppure verifica prima che message["role"] non sia "system".

Gli enum a un solo valore sono costanti

Questa modifica riguarda gli SDK C#, Go, Java, PHP e Ruby e un flag della CLI. Nelle versioni precedenti, un campo obbligatorio che può contenere un solo valore aveva un proprio tipo enum con un unico membro. Questi campi ora sono costanti e i tipi enum non esistono più. Il JSON che l'SDK invia e legge è lo stesso.

--type è facoltativo in ant beta:sessions:resources add. file è l'unico valore che --type può assumere lì, quindi la v2 lo invia per te. I comandi che passano ancora --type file continuano a funzionare, quindi non c'è nulla da modificare.

La compattazione lato client è stata rimossa dal tool runner

Questa modifica riguarda gli SDK TypeScript e Ruby. La compattazione lato client nel tool runner è stata rimossa a favore della compattazione lato server, che riassume la conversazione all'interno dell'API anziché con una richiesta aggiuntiva dal client.

L'opzione compactionControl e il modulo @anthropic-ai/sdk/lib/tools/CompactionControl non esistono più. L'opzione ha smesso di funzionare nella v0.129.0, dove passarla generava un AnthropicError. Non è presente nel tipo dei parametri, quindi TypeScript la segnala come proprietà sconosciuta.

Per continuare a compattare automaticamente a una soglia di token:

// Prima
const runner = client.beta.messages.toolRunner({
  // ...
  compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});

// Dopo
const runner = client.beta.messages.toolRunner({
  // ...
  betas: ["compact-2026-01-12"],
  context_management: {
    edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
  }
});

Per decidere tu quando compattare la conversazione, chiama runner.compactBeforeNextTurn().

La soglia di attivazione deve essere di almeno 50.000 token. Consulta compattazione per le altre opzioni (pause_after_compaction, instructions personalizzate).

Text Completions è stata rimossa

La API legacy Text Completions è stata rimossa dagli SDK TypeScript, Go, Java e Ruby e dalla CLI. I modelli e le funzionalità più recenti non la supportano. Usa invece la Messages API.

Il comando ant completions create non esiste più.

# Prima
ant completions create \
  --model "$MODEL" \
  --max-tokens-to-sample 1024 \
  --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:'

# Dopo
ant messages create \
  --model "$MODEL" \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

Il testo della risposta si sposta dal campo completion a content.0.text, quindi uno script che passava --transform completion passa invece --transform content.0.text.

Anche ant messages create accetta --stream, ma i suoi eventi hanno un'altra forma: il testo arriva in delta.text degli eventi content_block_delta, quindi --transform content.0.text non si applica a uno stream.

betas è stato rimosso dai metodi Models non beta

I metodi Models non beta non accettano più betas, e i comandi ant models non accettano più --beta. Per inviare header beta, chiama gli stessi metodi su client.beta.models, oppure ant beta:models nella CLI. Nell'SDK, questi metodi restituiscono BetaModelInfo dove quelli non beta restituiscono ModelInfo.

client.models.retrieve() e client.models.list() non accettano più betas (passarlo genera un TypeError, e un type checker lo segnala), e anthropic.types.ModelListParams non ha più una chiave betas.

# Prima
page = client.models.list(betas=[beta])

# Dopo
page = client.beta.models.list(betas=[beta])

Le chiavi API vengono inviate come Authorization: Bearer

L'SDK e la CLI inviano la tua chiave API come Authorization: Bearer <key> anziché nell'header X-Api-Key, quindi modifica qualsiasi proxy o gateway che legge o imposta X-Api-Key affinché usi Authorization, oppure invia tu stesso la chiave in X-Api-Key. La Claude API accetta una chiave in entrambi gli header, quindi un programma che comunica direttamente con l'API non richiede modifiche.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

Authorization è l'header che auth_token usa già.

Questo vale per l'argomento api_key e la variabile d'ambiente ANTHROPIC_API_KEY di Anthropic e AsyncAnthropic, e per api_key e ANTHROPIC_AWS_API_KEY di AnthropicAWS. AnthropicFoundry invia ancora la sua chiave come x-api-key, e AnthropicBedrockMantle inviava già un bearer token.

Se un proxy o gateway legge X-Api-Key

Riporta la chiave nell'header originale con una funzione auth sul client HTTP. Viene eseguita su ogni richiesta inviata dal client, inclusi i tentativi ripetuti:

import httpx2
from anthropic import Anthropic, DefaultHttpxClient


def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request


client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

AsyncAnthropic accetta la stessa funzione, in http_client=DefaultAsyncHttpxClient(auth=send_x_api_key).

Se impostavi o rimuovevi X-Api-Key su una richiesta

Questa modifica riguarda gli SDK Python, TypeScript, Go, PHP e Ruby.

Se rimuovevi X-Api-Key affinché una richiesta inviasse solo un token di autenticazione, elimina quel codice anziché modificarlo, perché rimuovere Authorization rimuoverebbe il token. Un client contiene una sola credenziale, quindi assicurati che sia il token: se nessuna viene passata nel codice e sono impostate sia ANTHROPIC_API_KEY sia ANTHROPIC_AUTH_TOKEN, il client usa la chiave.

Il codice che passa extra_headers={"X-Api-Key": omit} per escludere la chiave da una richiesta non ottiene più questo effetto. Passa invece extra_headers={"Authorization": omit}.

extra_headers={"X-Api-Key": other_key} non sostituisce più la chiave del client: vengono inviate entrambe le chiavi. Per inviare un'altra chiave con una singola richiesta, passa extra_headers={"Authorization": f"Bearer {other_key}"}.

Un client contiene una sola credenziale

Una chiave API e un "auth token" (token di autenticazione) ora condividono un header, quindi un client SDK contiene una sola credenziale. Se nel codice non ne viene passata nessuna, il client segue l'ordine di precedenza delle credenziali.

La v1 inviava sia una chiave API sia un auth token quando il client li aveva entrambi, ciascuno nel proprio header. La credenziale è una tra api_key, auth_token, credentials, config o profile.

  • Passane al massimo una. Due o più nel costruttore, o in una singola chiamata a copy() o with_options(), sollevano ValueError. None non conta. La v1 sollevava TypeError, e solo per due tra credentials, config e profile.
  • Quella che passi è l'unica. Come nella v1, il client non ne cerca un'altra nell'ambiente o su disco.
  • Se non ne passi nessuna, viene usata solo la prima di queste che risulta impostata: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, il profilo indicato da ANTHROPIC_PROFILE, le variabili di "workload identity federation" (federazione delle identità dei carichi di lavoro), il profilo attivo su disco (quello indicato dal file active_config, altrimenti default). Quando le prime due sono entrambe impostate, il client registra un avviso una sola volta. La v1 usava il profilo attivo prima delle variabili di federazione quando ANTHROPIC_CONFIG_DIR era impostata o esisteva un file active_config; imposta ANTHROPIC_PROFILE per continuare a usarlo.
  • copy() e with_options() sostituiscono. Una credenziale che passi sostituisce quella del client, qualunque sia il tipo dell'una o dell'altra. Un base URL e gli header provenienti dalla config o dal profilo della vecchia credenziale vengono rimossi con essa, e vengono usati quelli della nuova credenziale. Un base URL che hai passato tu rimane.
client = Anthropic(api_key=key, auth_token=token)

# Prima: inviava `X-Api-Key: <key>` e `Authorization: Bearer <token>`
# Dopo:  solleva `ValueError`

I client delle piattaforme mantengono le proprie regole. AnthropicAWS accetta auth_token insieme ad api_key senza errori, e invia la chiave.

Le docstring di Anthropic.__init__ e Anthropic.copy in _client.py contengono i dettagli.

Se facevi affidamento sull'invio di entrambe, ad esempio un token per un gateway e una chiave per l'API dietro di esso, passa il token come auth_token e imposta X-Api-Key in default_headers. Fai in modo che il gateway rimuova il proprio header Authorization prima di inoltrare la richiesta. La Claude API si aspetta una sola credenziale per richiesta.

Modifiche in un singolo SDK o nella CLI

Ciascuna di queste modifiche riguarda un singolo SDK o la CLI.

--api-key e --auth-token sono stati rimossi. ant non accetta più una chiave API o un auth token come valore di un flag, perché un valore sulla riga di comando è visibile nella cronologia della shell e negli elenchi dei processi. Entrambi i flag stampano un avviso di deprecazione dalla v1.27.0. Un comando che ne passa ancora uno si interrompe con flag provided but not defined.

RimossoUsa invece
--api-key <key>ANTHROPIC_API_KEY, --api-key-stdin o ant auth login
--auth-token <token>ANTHROPIC_AUTH_TOKEN o --auth-token-stdin
# Prima
ant --api-key "$KEY" models list

# Dopo, dall'ambiente
export ANTHROPIC_API_KEY="$KEY"
ant models list

# Dopo, da un secret manager
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

--api-key-stdin e --auth-token-stdin leggono tutto lo standard input, quindi un comando che ne usa uno prende il corpo della richiesta dai flag.

ant auth status, il prompt di primo avvio di ant apply e la nota sulle fonti di autenticazione multiple ora chiamano queste credenziali ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN, mentre prima stampavano --api-key / ANTHROPIC_API_KEY e --auth-token / ANTHROPIC_AUTH_TOKEN.

La licenza è Apache 2.0

A partire da queste versioni, l'SDK e la CLI sono distribuiti con la Apache License, Version 2.0. Le versioni precedenti restano sotto la MIT License. Non sono necessarie modifiche al codice. Se tieni traccia delle licenze delle tue dipendenze, aggiorna le relative voci.

  • TypeScript: i pacchetti delle piattaforme (@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk e @anthropic-ai/google-cloud-sdk) cambiano licenza nelle rispettive release 1.0.0.
  • C#: gli altri pacchetti (Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud e Anthropic.Mcp) cambiano licenza nelle rispettive release 1.0.0.
  • Java: la modifica riguarda ogni artefatto com.anthropic.

Was this page helpful?