Gestire modelli e strumenti nel livello AI Gateway (anteprima)

SI APPLICA A: livello gateway di IA (anteprima)

Usa il livello AI Gateway (anteprima) per gestire i modelli e gli strumenti richiamati da applicazioni e agenti. Importare modelli per fornire un endpoint governato per le richieste di modello. Aggiungi server MCP per esporre strumenti approvati attraverso un endpoint Model Context Protocol (MCP) gestito. Applicazioni e agenti si autenticano al gateway con le chiavi di accesso di runtime. Il gateway utilizza l'autenticazione back-end configurata per ciascun provider di modelli o back-end dello strumento.

Prerequisiti

• Un'istanza di livello gateway di IA.
• Autorizzazione a gestire l'istanza di livello AI Gateway.
• Accesso al modello di provider o al backend che intendi aggiungere.
• Per l'autenticazione back-end con identità gestita, l'autorizzazione ad assegnare il ruolo richiesto alla risorsa back-end.

Modelli di importazione

Usa la procedura guidata Aggiungi modelli per collegare il livello AI Gateway a Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic o endpoint personalizzati. Il gateway serve ogni modello sugli endpoint supportati dal suo backend, sotto il prefisso https://<gateway>.azure-api.net/default/models. Il segmento di percorso successivo è il formato API del fornitore. Ad esempio, i modelli compatibili OpenAI sono serviti in .../default/models/openai/v1 (come /chat/completions e /responses), e i modelli Anthropic in .../default/models/anthropic/v1/messages. I campi di connessione richiesti dal wizard variano a seconda del provider.

Scegli Importa da Foundry quando il tuo modello gira in una risorsa Microsoft Foundry, che include le implementazioni di Azure OpenAI e Azure AI Services — il wizard scopre automaticamente le implementazioni della risorsa. Scegli Aggiungi un modello personalizzato per AWS Bedrock, Google Vertex, OpenAI, Anthropic o qualsiasi altro endpoint supportato, dove inserisci tu stesso i nomi dell'endpoint e dei modelli.

Usa l'identità gestita quando il provider supporta l'autenticazione back-end di Microsoft Entra ID, come Microsoft Foundry. Concedere all'identità del gateway il ruolo richiesto sulla risorsa backend prima dell'importazione. Altrimenti, fornisci la chiave API o il segreto del fornitore durante l'importazione. Il gateway conserva e protegge la credenziali.

I chiamanti si riferiscono al modello con il nome del modello nel model campo:

{
  "model": "gpt-5.6-sol",
  "messages": [
    {
      "role": "user",
      "content": "Summarize the incident report."
    }
  ]
}

Il model valore è il nome del modello indicato dal modello importato.

Per aggiungere modelli, apri la pagina Modelli e seleziona Aggiungi modelli. Scegli come vuoi connetterti.

Importazione da Microsoft Foundry

1. Seleziona Importa da Foundry.
2. Su Seleziona risorsa, scegli l'abbonamento e la risorsa Foundry. Il wizard elenca le implementazioni dei modelli in quella risorsa.
3. In Dettagli provider, immetti il nome del provider e il nome visualizzato, aggiungi una descrizione facoltativa e scegli il metodo di autenticazione: Identità gestita (scelta consigliata, quando disponibile) o Basato su chiave.
4. Fare clic su Crea. Il gateway importa le distribuzioni della risorsa come modelli che i chiamanti richiedono per nome.

Aggiungere un modello personalizzato

1. Selezionare Aggiungi un modello personalizzato.
2. Su Provider, inserisci un nome visualizzato e il nome del provider, oltre a una descrizione opzionale.
3. Su Endpoint, inserisci l'URL base dell'endpoint, il nome dell'intestazione di autenticazione (ad esempio, Authorization), e la chiave API.
4. In Modelli, inserisci il nome di ciascun modello e seleziona gli endpoint supportati: completamenti chat di OpenAI, risposte di OpenAI, messaggi di Anthropic oppure Altro. Seleziona Aggiungi modello per ogni modello che definisci.
5. Fare clic su Crea.

Non esiste un passaggio di validazione separato. Il gateway imposta la connessione quando crei il provider. Dopo aver aggiunto un modello, puoi aggiornare la sua autenticazione o le politiche, oppure rimuoverlo quando non è più necessario.

Dopo che il modello è stato aggiunto, invia una richiesta di test tramite l'endpoint gateway:

curl "https://<gateway>.azure-api.net/default/models/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "api-key: <runtime-access-key>" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "user", "content": "Write a one-sentence status update." }
    ]
  }'

Se non hai ancora creato una chiave di accesso runtime, creala dalla pagina Chiavi . Le domande non richiedono credenziali dirette del fornitore. Usa le viste di monitoraggio per esaminare il volume delle richieste, la latenza, l'uso dei token e gli errori per nome del modello.

Pass-through dell'API per i messaggi di Anthropic

Provider diversi espongono formati API differenti e il gateway serve ciascuno seguendo il proprio percorso in /default/models. I modelli Anthropic utilizzano l'API Anthropic Messages in modalità passthrough: il gateway preserva il formato nativo di richiesta e risposta di Anthropic Messages e inoltra le chiamate a Anthropic a /default/models/anthropic/v1/messages. Usarlo quando le applicazioni già utilizzano l'Anthropic SDK o /v1/messages.

Per aggiungere un modello Anthropic, usa Aggiungi modelli>Aggiungi un modello personalizzato:

1. In Provider, immettere un nome visualizzato e il nome del provider per Anthropic.
2. Su Endpoint, imposta l'URL base dell'endpoint su https://api.anthropic.com, imposta il nome dell'intestazione di autenticazione su x-api-key, e inserisci la chiave API di Anthropic. Il gateway memorizza la chiave e la inietta nelle chiamate backend.
3. Su Models, inserisci il nome del modello Anthropic che i chiamanti inviano (ad esempio claude-fable-5), e seleziona l'endpoint dei messaggi Anthropic.
4. Fare clic su Crea. Il gateway espone i messaggi di Anthropic in modalità pass-through in /default/models/anthropic/v1/messages.

I client chiamano il percorso del gateway. Il gateway memorizza la credenziale, inserisce il backend x-api-key e inoltra ad Anthropic l'intestazione anthropic-version del chiamante.

curl -X POST "https://<gateway>.azure-api.net/default/models/anthropic/v1/messages" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "api-key: <runtime-access-key>" \
  -d '{"model":"claude-fable-5","max_tokens":256,"messages":[{"role":"user","content":"Write a product description for a trail running backpack."}]}'

Anthropic Python SDK funziona quando base_url è puntato sul percorso del gateway. Di default, l'SDK stock invia la credenziale nell'intestazione x-api-key , quindi passa la chiave di accesso runtime gateway nell'intestazione api-key usando default_headers. Il api_key="unused" valore soddisfa solo l'argomento richiesto dall'SDK; il gateway lo ignora e inietta la chiave Anthropic del backend memorizzata. Impostare model sul nome del modello Anthropic.

from anthropic import Anthropic

client = Anthropic(api_key="unused", base_url="https://<gateway>.azure-api.net/default/models/anthropic", default_headers={"api-key": "<runtime-access-key>"})
message = client.messages.create(model="claude-fable-5", max_tokens=256, messages=[{"role":"user","content":"Hello"}])
print(message.content[0].text)

Verificare i timeout e la gestione delle risposte prima della distribuzione in produzione, specialmente se i criteri ispezionano i corpi.

Aggiungere server MCP

Il livello AI Gateway consente ai team di piattaforma di pubblicare server MCP dietro un unico endpoint MCP gestito. Il flusso di lavoro di configurazione è: creare un server MCP, collegare uno o più backend ed esporre funzionalità selezionate come strumenti. Un singolo server MCP può combinare tre tipi di backend: server MCP remoti (per URL), strumenti generati da una specifica OpenAPI e connettori integrati per app SaaS comuni (più di 1.000 integrazioni precostruite, senza server da ospitare).

Usa server MCP quando gli agenti devono chiamare sistemi aziendali, strumenti per sviluppatori, knowledge store o API interne. Gli agenti si autenticano una volta sul gateway e non hanno bisogno di credenziali separate per ogni backend. Per ogni backend, scegli come il gateway si autentica ad esso: nessuno, chiave API, OAuth 2.0 o identità gestita.

Un singolo server MCP federa uno o più backend. Ogni backend mette a disposizione strumenti e il gateway assegna agli strumenti di ciascun backend uno spazio dei nomi basato sul nome del backend, in modo che strumenti con lo stesso nome provenienti da backend diversi non entrino in conflitto. Ad esempio, uno create_issue strumento di un backend chiamato github viene esposto agli agenti sotto il github namespace, distinto da uno create_issue strumento su un altro backend.

Ogni fonte contribuisce con strumenti in modo diverso:

• Server MCP — federa gli strumenti da un endpoint MCP remoto che già ospita.
• Specifica OpenAPI — trasforma le operazioni API selezionate in strumenti; il riassunto o la descrizione dell'operazione diventa la descrizione dello strumento.
• Connettore integrato — utilizza una connessione gestita a un'app SaaS come Office 365, SharePoint, GitHub o Salesforce. I connettori OAuth richiedono il consenso quando si configura la connessione.

Per creare un server MCP:

1. Nel portale AI Gateway a livelli, seleziona i server MCP.
2. Seleziona Aggiungi server MCP.
3. Su Source scegli un tipo di backend per iniziare: server MCP, specifica OpenAPI o connettore integrato. Puoi aggiungere altri backend dopo.
4. Dai al backend un nome unico. Il gateway aggiunge un prefisso agli strumenti back-end con il nome presente nel server MCP combinato.
5. Configura il backend e scegli come il gateway si autentica ad esso: nessuno, chiave API, OAuth 2.0 o Identità gestita. Per Chiave API, immettere il nome e il valore dell'intestazione; i valori inattivi sono crittografati.
6. Per federare più servizi dietro lo stesso endpoint, aggiungi un altro backend e ripeti.
7. Seleziona Conferma, e poi Crea.

Non esiste un passaggio separato per il test di connettività. Il gateway si configura e controlla ogni backend quando crei il server.

Il gateway crea un unico endpoint MCP che federa tutti i backend selezionati. I client chiamano l'endpoint governato e si autenticano con una chiave di accesso runtime.

Gli agenti chiamano il server MCP al:

https://<gateway>.azure-api.net/default/toolservers/<server-name>/mcp

Invia la chiave di accesso runtime nell'intestazione api-key . Indirizza qualsiasi client o framework per agenti compatibile con MCP a questo URL. Ad esempio, elenca gli strumenti disponibili con una richiesta JSON-RPC tools/list :

curl "https://<gateway>.azure-api.net/default/toolservers/<server-name>/mcp" \
  -H "Content-Type: application/json" \
  -H "api-key: <runtime-access-key>" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

import requests

url = "https://<gateway>.azure-api.net/default/toolservers/<server-name>/mcp"
response = requests.post(
    url,
    headers={"api-key": "<runtime-access-key>", "Content-Type": "application/json"},
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
print(response.json())

Se un sistema ha un'API REST ma non un server MCP, importa la sua descrizione OpenAPI. Seleziona le operazioni da esporre come strumenti, modifica nomi e descrizioni degli strumenti, configura un metodo di autenticazione backend supportato e crea l'asset MCP. Lo strumento di mappe del gateway chiama le operazioni REST.

Usa il gateway per i server MCP per centralizzare:

• Discovery — fornire un catalogo di server MCP approvati per sviluppatori e agenti.
• Autenticazione — i client si autenticano sul gateway. Il gateway memorizza le credenziali backend, quindi la configurazione del client non contiene segreti a monte.
• Esposizione degli strumenti — scegli quali operazioni backend ogni server pubblica come strumenti. In modalità anteprima, ogni chiave di accesso di runtime può richiamare tutte le risorse pubblicate nel gateway.
• Osservabilità — il gateway emette metriche di utilizzo dei token OpenTelemetry (OTLP) per il traffico dei modelli, che puoi inviare ad Application Insights o a un'altra destinazione OTLP. Il monitoraggio del traffico degli strumenti MCP (volume di richieste, latenza ed errori) è disponibile nel portale quando si utilizza Application Insights; L'esportazione di OpenTelemetry (OTLP) per il traffico degli strumenti MCP non è ancora disponibile.
• Governance — applica le stesse politiche al traffico MCP che usi per i modelli, come limiti di frequenza e sicurezza dei contenuti.

Dopo aver creato il server, configura l'accesso in runtime prima di condividerlo. Aggiungi politiche come la sicurezza dei contenuti, filtri IP e limiti di velocità di token e richieste, assegnate al gateway o a specifiche risorse pubblicate.

Contenuti correlati

• Panoramica dei livelli dell'AI Gateway
• Avvio rapido: creare un'istanza di livello AI Gateway
• Governare, proteggere e gestire il livello AI Gateway
• Configurare la rete privata