Claude in Microsoft Foundry

Questa guida ti mostra come configurare ed effettuare chiamate API a Claude in Microsoft Foundry utilizzando uno degli SDK client di Anthropic o richieste HTTP dirette. Quando accedi a Claude in Microsoft Foundry, l'utilizzo di Claude ti viene fatturato nell'Azure Marketplace. Puoi usare i modelli Claude, tra cui Claude Fable 5.1, Claude Opus 5, Claude Opus 4.8 e Claude Sonnet 5, e funzionalità come la "context window" (finestra di contesto) da 1M di token, gestendo al contempo i costi tramite la tua sottoscrizione Azure.

Claude è disponibile nei tipi di deployment Global Standard e US Data Zone Standard nelle risorse Foundry, con fatturazione in Claude Consumption Units tramite l'Azure Marketplace. Visita Prezzi di Claude in Microsoft Foundry per i dettagli.

Opzioni di hosting

I modelli Claude in Microsoft Foundry sono disponibili in due opzioni di hosting. Scegli l'opzione di hosting quando configuri il deployment.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Una sottoscrizione Azure attiva
• Accesso al portale Foundry
• L'Azure CLI installata (necessaria per l'esempio cURL con Entra ID, facoltativa altrimenti)
• Un ruolo Azure RBAC che ti consenta di usare la risorsa, come Foundry User (in precedenza Azure AI User) o Cognitive Services User

Installa un SDK

Gli SDK client di Anthropic supportano Foundry tramite un pacchetto o una classe client specifici per la piattaforma. Gli esempi in questa pagina mostrano anche richieste con cURL e con la CLI ant. Per configurare la CLI, consulta la guida rapida alla CLI.

pip install -U "anthropic"

# Per l'autenticazione con Entra ID, installa anche la libreria Azure Identity
pip install azure-identity

Provisioning

Foundry utilizza una gerarchia a due livelli: le risorse contengono la configurazione di sicurezza e fatturazione, mentre i deployment sono le istanze del modello che chiami tramite l'API. Creerai prima una risorsa Foundry, quindi uno o più deployment di Claude al suo interno.

Provisioning delle risorse Foundry

Crea una risorsa Foundry, necessaria per usare e gestire i servizi in Azure. Puoi seguire queste istruzioni per creare una risorsa Foundry. In alternativa, puoi iniziare creando un progetto Foundry, il che comporta la creazione di una risorsa Foundry.

Per effettuare il provisioning della tua risorsa:

1. Vai al portale Foundry.
2. Crea una nuova risorsa Foundry o selezionane una esistente.
3. Configura la gestione degli accessi usando chiavi API emesse da Azure oppure Entra ID (in precedenza Azure Active Directory) per il controllo degli accessi basato sui ruoli.
4. Facoltativamente, configura la risorsa come parte di una rete privata (Azure Virtual Network) per limitare l'accesso di rete alla tua risorsa.
5. Prendi nota del nome della risorsa. Lo userai come {resource} negli endpoint API (ad esempio, https://{resource}.services.ai.azure.com/anthropic/v1/*).

Creazione dei deployment Foundry

Dopo aver creato la risorsa, distribuisci un modello Claude per renderlo disponibile alle chiamate API. Questi passaggi descrivono il nuovo portale Foundry (l'interruttore New Foundry è attivo):

1. Accedi al portale Foundry. Dalla home page del portale, seleziona Discover nella navigazione in alto a destra, quindi Models nel riquadro sinistro per aprire il catalogo dei modelli.
2. Cerca e seleziona un modello Claude (ad esempio, claude-opus-5). Ogni modello appare una sola volta nel catalogo, indipendentemente dal numero di opzioni di hosting supportate.
3. Nella scheda del modello, seleziona Deploy, quindi Custom settings per aprire il riquadro delle impostazioni di deployment. Se invece scegli Default settings, il deployment viene configurato automaticamente come Ospitato su Azure per i modelli disponibili in entrambe le opzioni di hosting.
4. Al tuo primo deployment di Claude, esamina i termini dell'Azure Marketplace, seleziona un settore e seleziona Agree and Proceed per accettare i termini e sottoscrivere l'offerta dell'Azure Marketplace.
5. Configura il deployment:
   • Nome del deployment: per impostazione predefinita corrisponde all'ID del modello, ma puoi personalizzarlo (ad esempio, my-claude-deployment). Il nome del deployment non può essere modificato dopo la creazione.
   • Ambito regionale: seleziona Global oppure, per i modelli ospitati su Azure, Data Zone. Selezionando Data Zone viene creato un deployment US Data Zone Standard, che mantiene l'inferenza all'interno degli Stati Uniti ed equivale a impostare inference_geo: "us" sulla Claude API.
   • Versione del modello: espandi Model version settings e seleziona una versione dal menu a discesa Model version. Ogni opzione di hosting è elencata come versione del modello separata, etichettata con la relativa opzione di hosting (ad esempio, versione 1 per Ospitato su Anthropic, versione 2 per Ospitato su Azure).
6. Seleziona Deploy e attendi il completamento del provisioning.
7. Una volta completato il deployment, seleziona Build nella navigazione in alto a destra, quindi Models nel riquadro sinistro e apri il tuo deployment. La scheda Details mostra il Target URI (l'URL del tuo endpoint) e la Key (la tua chiave API).

Se l'interruttore New Foundry è disattivato, ti trovi nel layout classico del portale. Lì, apri Model catalog nel riquadro sinistro per trovare e distribuire un modello, e apri Models + endpoints (sotto My assets) per visualizzare i tuoi deployment e i dettagli dei relativi endpoint.

Autenticazione

Claude in Microsoft Foundry supporta due metodi di autenticazione: chiavi API e token Entra ID. Entrambi i metodi utilizzano endpoint ospitati su Azure nel formato https://{resource}.services.ai.azure.com/anthropic/v1/*.

Autenticazione con chiave API

Dopo aver effettuato il provisioning della tua risorsa Claude su Foundry, puoi ottenere una "API key" (chiave API) dal portale Foundry:

1. Nel portale Foundry, seleziona Build nella navigazione in alto a destra, quindi Models nel riquadro sinistro.
2. Apri il tuo deployment di Claude e seleziona la scheda Details.
3. Copia il valore Key (e prendi nota del Target URI per il tuo endpoint).
4. Usa l'header api-key oppure x-api-key nelle tue richieste, oppure forniscilo all'SDK.

Gli SDK per Foundry richiedono una chiave API e un nome di risorsa oppure un URL di base. Gli SDK C#, Java, PHP, Python e TypeScript leggono automaticamente questi valori dalle seguenti variabili d'ambiente, se definite:

• ANTHROPIC_FOUNDRY_API_KEY - La tua chiave API
• ANTHROPIC_FOUNDRY_RESOURCE - Il nome della tua risorsa (ad esempio, example-resource)
• ANTHROPIC_FOUNDRY_BASE_URL - Alternativa al nome della risorsa: l'URL di base completo (ad esempio, https://example-resource.services.ai.azure.com/anthropic/). L'SDK C# non legge questa variabile: costruisce sempre l'URL di base a partire dal nome della risorsa.

Esempio con chiave API:

import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    api_key=os.environ.get("ANTHROPIC_FOUNDRY_API_KEY"),
    resource="example-resource",  # your resource name
)

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

Autenticazione Microsoft Entra

L'autenticazione Entra ID ti consente di gestire gli accessi con Azure RBAC, integrarti con la gestione delle identità della tua organizzazione ed evitare di gestire manualmente le chiavi API. Per usare i token Entra ID:

1. Abilita l'autenticazione Microsoft Entra ID per la tua risorsa Foundry.
2. Ottieni un token di accesso da Entra ID.
3. Usa il token nell'header Authorization: Bearer {TOKEN}.

Esempio con Entra ID:

from anthropic import AnthropicFoundry
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Ottieni il token Microsoft Entra ID usando il pattern del token provider
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

# Crea il client con autenticazione Entra ID
client = AnthropicFoundry(
    resource="example-resource",  # your resource name
    azure_ad_token_provider=token_provider,  # Use token provider for Entra ID auth
)

# Effettua la richiesta
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)

ID di correlazione delle richieste

Foundry include identificatori di richiesta negli header di risposta HTTP per il debug e il tracciamento. Quando contatti il supporto, fornisci sia il valore request-id sia il valore apim-request-id (Azure API Management) per aiutare i team a individuare e analizzare rapidamente la tua richiesta nei sistemi sia di Anthropic sia di Azure.

Supporto delle funzionalità

Claude in Microsoft Foundry supporta la maggior parte delle funzionalità di Claude. Puoi trovare tutte le funzionalità attualmente supportate nella Panoramica delle funzionalità.

Finestra di contesto

Claude Fable 5.1, Claude Fable 5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6 dispongono di una finestra di contesto da 1M di token su Microsoft Foundry. Gli altri modelli Claude, incluso Claude Sonnet 4.5, dispongono di una finestra di contesto da 200k token.

Funzionalità di Claude non supportate per Claude in Microsoft Foundry

• Admin API
• Strumento Advisor
• Claude Managed Agents
• Compliance API
• Models API
• Message Batches API
• Fallback lato server (il parametro fallbacks; usa invece il pattern di fallback lato client)
• Toolset per computer use e browser use (computer_toolset_20260801 e browser_toolset_20260801 non sono attualmente disponibili su Microsoft Foundry; le versioni beta dello strumento computer use rimangono disponibili)

Funzionalità aggiuntive non supportate quando ospitato su Azure

Le seguenti funzionalità sono disponibili per i deployment ospitati su Anthropic ma non sono supportate per i deployment ospitati su Azure:

• Esecuzione di codice
• Versioni degli strumenti web search e web fetch successive a web_search_20250305 e web_fetch_20250910. I deployment ospitati su Azure supportano solo queste versioni di base, quindi il filtraggio dinamico, l'inclusione delle risposte e il bypass della cache non sono disponibili.
• Agent Skills
• Chiamata programmatica degli strumenti
• Files API

Le richieste che utilizzano queste funzionalità su un deployment ospitato su Azure restituiscono intenzionalmente un errore 400 Bad Request. Claude Code rileva i deployment ospitati su Azure e adatta automaticamente il proprio set di funzionalità.

Risposte API

Le risposte API di Claude in Microsoft Foundry seguono il formato di risposta standard della Claude API. Questo include l'oggetto usage nel corpo delle risposte, che fornisce informazioni dettagliate sul consumo di token per le tue richieste. L'oggetto usage è coerente su tutte le piattaforme (Claude API, Amazon Bedrock, Claude Platform on AWS, Foundry e Google Cloud).

Per i dettagli sugli header di risposta specifici di Foundry, consulta ID di correlazione delle richieste.

ID dei modelli API e deployment

I termini del ciclo di vita (Deprecato, Ritirato) sono definiti in Deprecazioni dei modelli. Microsoft Foundry segue il calendario del ciclo di vita della Claude API.

I seguenti modelli Claude sono disponibili tramite Foundry:

Per impostazione predefinita, i nomi dei deployment corrispondono agli ID dei modelli mostrati nella tabella precedente. Tuttavia, puoi creare deployment personalizzati con nomi diversi nel portale Foundry per gestire configurazioni, versioni o limiti di velocità differenti. Usa il nome del deployment (non necessariamente l'ID del modello) nelle tue richieste API.

Fatturazione

Claude in Microsoft Foundry viene fatturato tramite l'Azure Marketplace. L'utilizzo è espresso in Claude Consumption Units (CCU), misurato su base oraria e fatturato mensilmente in via posticipata sulla tua fattura Azure. Le CCU non sono crediti prepagati. Non esiste alcun saldo o impegno in CCU.

Per il prezzo delle CCU, i meccanismi di conversione e le tariffe per token di ciascun modello, consulta Prezzi di Claude in Microsoft Foundry.

Migrazione tra opzioni di hosting

Per spostare un deployment esistente da un'opzione di hosting all'altra:

1. Crea un nuovo deployment dell'altra versione di hosting del modello (Ospitato su Azure o Ospitato su Anthropic). Può trovarsi nella stessa risorsa Foundry o in una nuova.
2. Aggiorna la tua applicazione in modo che passi il nuovo nome del deployment nel parametro model.
3. Elimina il vecchio deployment una volta che il traffico è stato spostato.

Se il nuovo deployment si trova nella stessa risorsa Foundry, l'URL dell'endpoint e l'autenticazione restano invariati. Se hai creato una nuova risorsa, aggiorna l'endpoint e le credenziali della tua applicazione in modo che puntino a essa.

Monitoraggio e logging

Azure fornisce monitoraggio e logging per il tuo utilizzo di Claude tramite i pattern standard di Azure:

• Azure Monitor: monitora l'utilizzo dell'API, la latenza e i tassi di errore
• Azure Log Analytics: interroga e analizza i log di richieste/risposte
• Cost Management: monitora e prevedi i costi associati all'utilizzo di Claude

Anthropic consiglia di registrare la tua attività su una base mobile di almeno 30 giorni per comprendere i pattern di utilizzo e indagare eventuali problemi.

Risoluzione dei problemi

Errori di autenticazione

Errore: 401 Unauthorized o Invalid API key

• Soluzione: verifica che la tua chiave API sia corretta. Puoi trovarla nel portale Foundry nella scheda Details del tuo deployment (sotto Build > Models).
• Soluzione: se usi Microsoft Entra ID, assicurati che il tuo token di accesso sia valido e non sia scaduto. I token in genere scadono dopo 1 ora.

Errore: 403 Forbidden

• Soluzione: il tuo account Azure potrebbe non disporre delle autorizzazioni necessarie. Assicurati di avere assegnato il ruolo Azure RBAC appropriato (ad esempio, Foundry User (in precedenza Azure AI User) o Cognitive Services User).

Limitazione della velocità

Errore: 429 Too Many Requests

• Soluzione: hai superato il tuo "rate limit" (limite di velocità). Implementa una logica di backoff esponenziale e di ripetizione dei tentativi nella tua applicazione.
• Soluzione: valuta la possibilità di richiedere un aumento dei limiti di velocità tramite il portale Azure o il supporto Azure.

Header dei limiti di velocità

Foundry non include nelle risposte gli header standard dei limiti di velocità di Anthropic (anthropic-ratelimit-tokens-limit, anthropic-ratelimit-tokens-remaining, anthropic-ratelimit-tokens-reset, anthropic-ratelimit-input-tokens-limit, anthropic-ratelimit-input-tokens-remaining, anthropic-ratelimit-input-tokens-reset, anthropic-ratelimit-output-tokens-limit, anthropic-ratelimit-output-tokens-remaining e anthropic-ratelimit-output-tokens-reset). Gestisci invece la limitazione della velocità tramite gli strumenti di monitoraggio di Azure.

Errori di modello e deployment

Errore: Model not found o Deployment not found

• Soluzione: verifica di usare il nome del deployment corretto. Se non hai creato un deployment personalizzato, usa l'ID del modello predefinito (ad esempio, claude-opus-5).
• Soluzione: assicurati che il modello/deployment sia disponibile nella tua regione Azure.

Errore: Invalid model parameter

• Soluzione: il parametro model deve contenere il nome del tuo deployment, che può essere personalizzato nel portale Foundry. Verifica che il deployment esista e sia configurato correttamente.

Passaggi successivi

Risorse aggiuntive