Che cosa sono gli agenti ospitati?

Quando si creano applicazioni agentiche usando framework open source, in genere si gestiscono molti problemi trasversali: containerizzazione, configurazione del server Web, sicurezza, persistenza della memoria, ridimensionamento, strumentazione e rollback delle versioni. Queste attività diventano ancora più complesse in ambienti cloud eterogenei.

Gli agenti ospitati nel servizio Foundry Agent risolvono queste sfide per gli utenti di Microsoft Foundry. Gli agenti ospitati chiamano i modelli dal catalogo dei modelli Foundry per eseguire il ragionamento mentre il codice personalizzato gestisce l'orchestrazione. Usando questa piattaforma gestita, è possibile distribuire e gestire gli agenti di intelligenza artificiale in modo sicuro e su larga scala. È possibile usare il codice dell'agente personalizzato o un framework agente preferito con distribuzione e gestione semplificate.

Quando usare gli agenti ospitati

Scegli gli agenti ospitati anziché quelli basati su prompt quando devi:

• Porta il tuo codice: usa qualsiasi framework (Agent Framework, LangGraph, Kernel semantico o codice personalizzato) anziché definizioni basate solo su prompt.
• Usare protocolli personalizzati - accettare webhook o payload non OpenAI tramite il protocollo Invocations.
• Controllare le risorse di calcolo : specificare CPU e memoria per la sandbox dell'agente.
• Eseguire carichi di lavoro con stato: rendere persistenti i file e lo stato tra i vari turni tramite $HOME e l'endpoint /files.

Come funziona

Si impacchetta l'agente come immagine del contenitore e lo si carica in Registro Azure Container. Quando distribuisci, il servizio Agent esegue il pull dell'immagine, esegue il provisioning delle risorse di calcolo, assegna un Microsoft Entra ID dedicato (identità dell'agente) ed espone un endpoint dedicato. In fase di esecuzione, il codice dell'agente gestisce le richieste dai client e può chiamare i modelli Foundry, gli strumenti della casella degli strumenti e i servizi downstream Azure usando l'identità dell'agente. La piattaforma gestisce la scalabilità, la persistenza dello stato della sessione, l'osservabilità e la gestione del ciclo di vita.

Concetti chiave

Agenti ospitati

Gli agenti ospitati sono applicazioni di intelligenza artificiale agentiche containerizzate che vengono eseguite su Agent Service. A differenza degli agenti basati su prompt, definiti interamente tramite prompt e configurazione degli strumenti nel portale Foundry, gli agenti ospitati sono il tuo codice, pacchettizzato come immagine container. Si sceglie il framework, si controlla il comportamento di runtime e si distribuisce l'immagine nell'infrastruttura gestita da Microsoft.

La piattaforma gestisce automaticamente il ciclo di vita del contenitore in base all'attività, il provisioning delle risorse quando si crea una versione e il deprovisioning quando viene raggiunto il timeout di inattività.

Modello di isolamento

Gli agenti ospitati vengono eseguiti in sandbox isolate su macchine virtuali differenti per ogni sessione. Ogni sessione ottiene una sandbox dedicata con un file system permanente ($HOME e /files) abilitando la scalabilità a zero, la ripresa con stato e l'avvio a freddo prevedibile. Le sessioni sono isolate l'una dall'altra e lo stato viene ripristinato automaticamente quando una sessione viene ripresa dopo l'inattività.

Protocolli: risposte, invocazioni e invocazioni (WebSocket)

I contenitori dell'agente ospitato possono esporre uno o più protocolli. Ogni protocollo viene fornito da una libreria leggera che gestisce il server HTTP o WebSocket, i controlli di integrità e l'integrazione openTelemetry. I protocolli Risposte, Chiamate e Chiamate (WebSocket) sono disponibili in tutte le aree che supportano gli agenti ospitati.

Quale protocollo è necessario usare?

Confronto tra protocolli

Protocolli aggiuntivi

Gli agenti ospitati supportano anche il protocollo Activity per Teams e l'integrazione del canale Microsoft 365. Quando si usa il protocollo Risposte per la logica dell'agente e si pubblica in canali Microsoft 365, ad esempio Teams, la piattaforma collega automaticamente le risposte al protocollo Attività per la distribuzione di canali, senza cablaggi separati. Il protocollo A2A supporta la delega da agente a agente. I protocolli supportati possono essere combinati in un singolo agente.

Identità e endpoint dell'agente

Ogni agente ospitato distribuito in un progetto Foundry ottiene il proprio dedicated Microsoft Entra ID (identità agente) e dedicated endpoint, entrambi creati automaticamente in fase di distribuzione. Non è necessario configurare manualmente le identità gestite o il routing.

L'endpoint è disponibile immediatamente dopo la distribuzione. La pubblicazione non è necessaria per l'accesso a livello di codice:

• Risposte: {project_endpoint}/agents/{name}/endpoint/protocols/openai/responses
• Chiamate: {project_endpoint}/agents/{name}/endpoint/protocols/invocations
• Invocazioni (WebSocket): wss://{account}.services.ai.azure.com/api/projects/{project}/agents/{name}/endpoint/protocols/invocations_ws?api-version=v1
• A2A (versione di anteprima): {project_endpoint}/agents/{name}/endpoint/protocols/a2a

Gli endpoint attivi dipendono dai protocolli dichiarati nella definizione della versione dell'agente. Impostare questa definizione nel servizio azure.ai.agent in azure.yaml quando si utilizza azd, o tramite protocol_versions quando si utilizza SDK.

Sono coinvolte due identità:

Per impostazione predefinita, l'identità dell'agente può accedere all'inferenza del modello tramite l'endpoint del progetto e l'archiviazione della sessione. Per le risorse esterne (ad esempio una propria archiviazione di Azure), assegnare manualmente i ruoli RBAC al Microsoft Entra ID dell'agente. Per altre informazioni, vedere Accesso dell'agente oltre le impostazioni predefinite.

Se integrati tramite canali Microsoft 365 (ad esempio Teams), gli agenti ospitati possono operare in due modalità di gestione delle identità a seconda della modalità di chiamata:

• Scenari richiamati dall'utente (interattivo): se è presente un token utente, la piattaforma supporta i flussi OAuth 2.0 On-Behalf-Of (OBO). In questo caso, l'agente può invocare i servizi downstream per conto dell'utente utilizzando le autorizzazioni delegate dell'utente, in conformità ai criteri del tenant di Microsoft Entra ID.

• Scenari autonomi o in background: se non è disponibile alcun token utente, l'agente si autentica usando il proprio ID Microsoft Entra (identità dell'agente), in genere tramite l'identità gestita, per accedere ai servizi downstream.

In entrambi i casi, l'agente mantiene il proprio Microsoft Entra ID dedicato per l'autenticazione, l'autorizzazione e la verificabilità. Per altre informazioni, vedere Concetti relativi alle applicazioni agent e alle identità degli agenti.

Sessioni e conversazioni

Gli agenti ospitati usano sessioni e conversazioni per gestire lo stato. Il modo in cui funziona dipende dal protocollo.

Sessioni

Un ID sessione identifica una sessione logica con stato persistente, inclusi $HOME e file caricati tramite l'endpoint /files. La piattaforma effettua il provisioning dell'ambiente di calcolo su richiesta e ripristina lo stato persistente su di esso.

• Persistenza dello stato: il contenuto di $HOME e /files viene salvato in modo permanente tra turni e periodi di inattività. Quando le risorse di calcolo diventano inattive e vengono ripristinate (in una nuova infrastruttura o esistente), lo stato della sessione viene automaticamente recuperato.
• Isolamento: ogni sessione è isolata da altre sessioni.
• Ciclo di vita automatico: le sessioni vengono create al primo utilizzo. La piattaforma esegue automaticamente il provisioning e il deprovisioning dell'ambiente di calcolo.
• Durata sessione: il timeout di inattività è di 15 minuti, se non arriva alcuna richiesta all'interno di tale finestra, la piattaforma esegue il deprovisioning del calcolo e mantiene lo stato della sessione. Una sessione viene eliminata definitivamente dopo 30 giorni di inattività.
• API di gestione delle sessioni: elencare le sessioni, terminare le sessioni e caricare o scaricare file per sessione.

Conversazioni

Un ID della conversazione è un registro duraturo della cronologia della conversazione (messaggi, chiamate di strumenti e risposte) archiviato in Foundry.

• Persistenza: la cronologia delle conversazioni viene archiviata in Foundry e viene mantenuta indipendentemente dallo stato di calcolo.
• Accesso tra canali: gli utenti possono accedere alla stessa conversazione dal playground, dall'API, da Teams o da altri canali pubblicati.

Il funzionamento delle sessioni e delle conversazioni per ciascun protocollo

Protocollo di risposta: l'identificativo di conversazione è il concetto principale. La piattaforma gestisce automaticamente la cronologia delle conversazioni e associa un ID sessione a ogni conversazione. La piattaforma restituisce l'ID sessione al client, che può usarlo per caricare i file tramite l'endpoint /files, rendendo tali file disponibili per il calcolo della conversazione.

Protocollo di invocazione: l'ID sessione è il concetto principale. Il client gestisce direttamente l'ID sessione per mantenere lo stato tra le interazioni. Il client può caricare il contenuto tramite l'endpoint /files usando l'ID sessione per renderlo disponibile per la sessione. Non esiste una cronologia di conversazione gestita dalla piattaforma, ovvero lo stato viene gestito nel proprio codice.

Ciclo di vita di calcolo della sessione

Sicurezza e gestione dei dati

Considerare un agente ospitato come il codice dell'applicazione di produzione.

• Non inserire segreti nelle immagini del contenitore o nelle variabili di ambiente. Usare identità e connessioni gestite e archiviare i segreti in un archivio segreto gestito. Per indicazioni, vedere Impostare una connessione Key Vault.
• Prestare attenzione a strumenti e server non Microsoft. Se l'agente chiama gli strumenti supportati da non servizi Microsoft, alcuni dati potrebbero essere trasmessi a tali servizi. Esaminare i criteri di condivisione, conservazione e posizione dei dati per qualsiasi servizio non Microsoft connesso.

Dettagli della piattaforma

Versionamento

Ogni chiamata per creare una versione produce una versione dell'agente non modificabile, ovvero uno snapshot dell'immagine del contenitore, l'allocazione delle risorse, le variabili di ambiente e la configurazione del protocollo. Le distribuzioni fanno riferimento a una versione specifica. Per aggiornare l'agente, creare una nuova versione e la piattaforma la distribuisce. Si noti che le richieste di creare la versione dell'agente senza alcuna modifica ai parametri della versione dell'agente, ad esempio l'immagine del contenitore, le variabili di ambiente e così via, non comportano la creazione di una nuova versione. È possibile suddividere il traffico tra le versioni con implementazioni ponderate per supportare le distribuzioni di tipo canary e blue-green.

Le variabili di ambiente sono il meccanismo principale per passare la configurazione al contenitore in fase di esecuzione, ad esempio l'endpoint del progetto, il nome della distribuzione del modello e le impostazioni personalizzate. Vengono impostati per versione e non sono modificabili dopo la creazione della versione.

Osservabilità

Gli agenti ospitati offrono un'osservabilità integrata. La piattaforma inserisce automaticamente un stringa di connessione di Application Insights nel contenitore dell'agente tramite variabili di ambiente. Gli agenti che usano le librerie di protocolli generano tracce OpenTelemetry per impostazione predefinita, visualizzate nella risorsa di Application Insights collegata in Ricerca>transazioni o prestazioni.

Per indicazioni sulla configurazione e l'analisi, vedere Abilitare la traccia nel progetto.

Casella degli strumenti in Foundry

Gli agenti ospitati accedono agli strumenti gestiti da Foundry (Code Interpreter, Ricerca Web, Azure AI Search, OpenAPI, connessioni MCP personalizzate, A2A) tramite un endpoint MCP Toolbox MCP di cui è stato effettuato il provisioning nel progetto Foundry. Il codice dell'agente si connette a questo endpoint usando librerie client MCP standard. La piattaforma non inserisce automaticamente gli strumenti. Per informazioni dettagliate, vedere Gestire la casella degli strumenti basata su finalità in Foundry. Per connettere gli strumenti in un agente ospitato con supporto consolidato dell'autenticazione tra pass-through dell'identità OAuth, identità dell'agente, basata su chiavi e altro ancora, usare la casella degli strumenti in Foundry.

Supporto linguistico

Gli agenti ospitati supportano Python e C#. È possibile usare qualsiasi framework agente: le librerie di protocolli sono indipendenti dal framework. Per esempi che usano Microsoft Agent Framework, LangGraph e codice personalizzato, vedere il repository foundry-samples.

Dimensioni sandbox

Le sandbox dell'agente ospitato supportano le combinazioni di CPU e memoria seguenti:

Archiviazione delle sessioni

Ogni sessione ha un oggetto persistente $HOME. I suoi contenuti vengono preservati quando le risorse di calcolo vengono deallocate dopo 15 minuti di inattività e ripristinati quando la sessione riprende, così i file scritti in $HOME persistono durante i periodi di inattività. I file caricati tramite l'endpoint /files vengono scritti in $HOME e condividono la stessa risorsa di archiviazione. A ogni sessione è assegnata una quota disco totale fino a 20 GiB con 1 vCPU o più, che si riduce proporzionalmente per i livelli di CPU inferiori. Circa 20% di tale budget è riservato per l'uso del sistema e non è visibile o disponibile per l'agente. Il resto viene condiviso tra l'immagine del contenitore, $HOMEe qualsiasi altra posizione scrivibile nel contenitore.

Scalabilità e dimensionamento corretto

Gli agenti ospitati scalano per sessione, non per replica. La piattaforma crea una nuova sandbox isolata dalla macchina virtuale per ogni sessione su richiesta, la esegue per la durata della sessione (timeout di inattività 15 minuti, durata massima 30 giorni) e la rimuove al termine della sessione. Non c’è alcun conteggio delle repliche da configurare né alcun warm pool da dimensionare.

Poiché ogni sessione viene eseguita nel proprio sandbox, i valori di CPU e memoria impostati in una versione dell'agente descrivono una singola sessione, non il footprint aggregato dell'agente. La fatturazione si basa su CPU e memoria consumate nell’insieme di tutte le sessioni attive, quindi il sovradimensionamento moltiplica i costi per il numero di sessioni simultanee.

Per le dimensioni corrette, eseguire un carico di lavoro rappresentativo ed esaminare l'utilizzo delle risorse nella risorsa di Application Insights collegata:

1. Aprire la risorsa Di App Insights nel portale di Azure e selezionare Investigate>Performance.
2. Esaminare LA CPU, la memoria disponibile, la frequenza delle richieste e la durata media delle richieste nell'intervallo di tempo testato.

Confrontare i picchi osservati con la CPU e la memoria allocata. Se i picchi sostenuti superano circa il 70% dell’allocazione, aumenta l’allocazione della versione successiva dell’agente; se i picchi rimangono ben al di sotto di tale soglia, riducila per ridurre il costo. Ripetere sempre dopo una modifica, perché ogni nuova versione non è modificabile.

Rete privata

Gli agenti ospitati supportano la distribuzione all'interno delle risorse Foundry isolate dalla rete e possono usare un Rete virtuale di Azure fornito dal cliente per il traffico in uscita. Ciò consente agli agenti nelle distribuzioni foundry isolate dalla rete di raggiungere risorse private, ad esempio database o API interne. Per altre informazioni, vedere Configurare le reti virtuali.

Limiti, prezzi e disponibilità

Tariffe

La fatturazione del runtime di hosting gestito si basa sull'utilizzo delle risorse di CPU e memoria durante le sessioni attive. Per le tariffe correnti, vedere la pagina dei prezzi di Foundry.

Disponibilità dell'area

Gli agenti ospitati sono attualmente disponibili nelle aree seguenti:

• Stati Uniti orientali 2
• Stati Uniti centro-settentrionali
• Svezia centrale
• Canada centrale
• Canada East
• Asia sud-orientale
• Polonia centrale
• Sudafrica settentrionale
• Corea centrale
• India meridionale
• Brasile meridionale
• Stati Uniti occidentali
• Stati Uniti occidentali 3
• Norvegia orientale
• Giappone orientale
• Francia centrale
• Germania centro-occidentale
• Svizzera settentrionale
• Spagna centrale
• Australia orientale

Passaggi successivi

Contenuto correlato

• Componenti di runtime dell'agente
• Ciclo di vita di sviluppo dell'agente
• Concetti relativi all'identità dell'Agente in Microsoft Foundry
• Scoprire gli strumenti in Foundry Tools
• Documentazione di Registro Azure Container