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. 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

Scegliere gli agenti ospitati rispetto agli agenti basati su prompt quando è necessario:

  • Porta il tuo codice - usa qualsiasi framework (Framework degli agenti, LangGraph, Kernel Semantico o codice personalizzato) piuttosto che definizioni di sola richiesta.
  • Usare protocolli personalizzati - accettare webhook o payload di tipo non OpenAI tramite il protocollo di invocazioni.
  • 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 crea un pacchetto dell'agente come immagine di un container e lo si carica nel Registro Azure Container. Quando si esegue il deployment, il servizio Agent esegue il pull dell'immagine, effettua il provisioning delle risorse di calcolo, assegna un'identità dell'agente Entra dedicata ed espone un endpoint dedicato. In fase di esecuzione, il codice agente gestisce le richieste dai client e può chiamare i modelli Foundry, gli strumenti della casella degli strumenti foundry e i servizi downstream di 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.

Importante

Quando si usano agenti ospitati con altri prodotti e servizi Microsoft, è necessario leggere tutta la documentazione pertinente per tali prodotti e servizi e comprendere i rischi e le considerazioni di conformità correlati. Se si usano agenti ospitati con server, agenti, codice o modelli di terze parti che non sono modelli di Azure Direct ("Sistemi di terze parti"), è possibile farlo a proprio rischio. I sistemi di terze parti sono prodotti non Microsoft ai sensi delle condizioni del prodotto Microsoft e sono disciplinati dalle proprie condizioni di licenza di terze parti. L'utente è responsabile di qualsiasi utilizzo e costi associati. Esaminare tutti i dati condivisi con e ricevuti da sistemi di terze parti. Tenere presente le procedure di terze parti per la gestione, la condivisione, la conservazione e la posizione dei dati. È responsabilità dell'utente gestire se i dati vengono trasmessi al di fuori dei limiti geografici e di conformità di Azure dell'organizzazione e di eventuali implicazioni correlate. Microsoft non ha alcuna responsabilità per l'utente o altri utenti in relazione all'uso di sistemi di terze parti e l'utente è responsabile dell'implementazione di mitigazioni di intelligenza artificiale responsabili, ad esempio metaprompt, filtri di contenuto o altri sistemi di sicurezza.

Concetti chiave

Agenti ospitati

Gli agenti ospitati sono applicazioni IA agentiche in contenitori eseguite sul servizio agente. A differenza degli agenti basati su prompt, definiti interamente tramite prompt e configurazione degli strumenti nel portale di Foundry, gli agenti ospitati sono il proprio codice creato 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à.

Protocolli: risposte e chiamate

I contenitori dell'agente ospitato espongono uno o entrambi i protocolli. Ogni protocollo viene fornito da una libreria leggera che gestisce il server HTTP, i controlli di integrità e l'integrazione openTelemetry.

Quale protocollo è necessario usare?

Scenario Protocollo Perché
Chatbot o assistente per conversazioni Risposte La piattaforma gestisce la cronologia delle conversazioni, gli eventi di streaming e il ciclo di vita della sessione, usando qualsiasi SDK compatibile con OpenAI come client.
Domande e risposte a più turni con RAG o strumenti Risposte Threading integrato dell'ID conversazione e gestione dei risultati degli strumenti.
Elaborazione in background e asincrona Risposte background: true con il polling e l'annullamento gestiti dalla piattaforma, senza codice personalizzato necessario.
Agente pubblicato in Teams o M365 Risposte + Attività Il protocollo Responses alimenta la logica dell'agente; il protocollo Activity gestisce l'integrazione del canale Teams.
Ricevitore webhook (GitHub, Stripe, Jira e così via) Invocazioni Il sistema esterno invia il proprio formato di payload: non è possibile modificarlo in modo che corrisponda a /responses.
Elaborazione non conversazionale (classificazione, estrazione, batch) Invocazioni L'input è costituito da dati strutturati, non da un messaggio di chat. JSON arbitrario in, JSON arbitrario out.
Protocollo di streaming personalizzato (AG-UI e così via) Invocazioni AG-UI e altri protocolli agent-UI non sono compatibili con OpenAI. È necessario un controllo SSE non elaborato.
Ponte di protocollo (GitHub Copilot, sistemi proprietari) Invocazioni Il chiamante ha un proprio protocollo che non esegue il mapping a /responses.

Suggerimento

Non sei sicuro? Iniziare con le risposte. È sempre possibile aggiungere un endpoint chiamate in un secondo momento. Un agente ospitato può supportare entrambi i protocolli contemporaneamente.

Confronto tra protocolli

Risposte Invocazioni
Ideale per La maggior parte degli agenti: la piattaforma gestisce la cronologia delle conversazioni, il ciclo di vita di streaming e l'esecuzione in background Agenti che necessitano di controllo HTTP completo, payload personalizzati o flussi di lavoro asincroni a esecuzione prolungata
Payload Contratto compatibile con OpenAI /responses JSON arbitrario tramite /invocazioni: si definisce uno schema
Client SDK Qualsiasi SDK compatibile con OpenAI (Python, JS, C#) funziona correttamente Client personalizzato: si definisce il contratto
Cronologia delle sessioni Gestione della piattaforma tramite ID conversazione È possibile gestire le sessioni (in memoria, Cosmos DB e così via)
Streaming ResponseEventStream gestito dalla piattaforma con eventi del ciclo di vita SSE non elaborato: formatta e scrivi direttamente gli eventi
Background/long-running Integrato (in background: true + polling gestito dalla piattaforma) Rilevamento manuale delle attività ed endpoint di polling personalizzati

Protocolli aggiuntivi

Gli agenti ospitati supportano anche il protocollo Attività per l'integrazione del canale Teams e M365 (in genere usata insieme alle risposte) e il protocollo A2A per la delega da agente a agente. Tutti e quattro i protocolli, ovvero risposte, chiamate, attività e A2A, possono essere combinati in un singolo agente.

Identità e endpoint dell'agente

Ogni agente ospitato distribuito in un progetto Foundry ottiene la propria identità dell'agente Entra dedicata e un endpoint dedicato, 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/v1/responses
  • Invocazioni: {project_endpoint}/agents/{name}/endpoint/protocols/invocations

Gli endpoint attivi dipendono dai protocolli dichiarati nella definizione della versione dell'agente (impostato in agent.yaml quando si usa azd o tramite container_protocol_versions quando si usa l'SDK).

Sono coinvolte due identità:

Identity Scope Scopo
Identità Entra dell'agente (per agente) Creato automaticamente in fase di distribuzione Identità con cui il contenitore dell'agente esegue l'autenticazione in fase di esecuzione. Usato per la chiamata al modello, l'accesso agli strumenti e i servizi downstream di Azure.
Identità gestita del progetto (a livello di progetto) Assegnata dal sistema nel progetto Foundry Usato dalla piattaforma per le operazioni dell'infrastruttura, ad esempio Lettore del repository del registro dei contenitori. Questa non è l'identità di runtime dell'agente.

Quando si esegue la distribuzione con azd, il ruolo RBAC richiesto (Azure AI User a livello di account) viene assegnato automaticamente all'identità Entra dell'agente. Per le risorse esterne, ad esempio archiviazione di Azure, assegnare manualmente il controllo degli accessi in base al ruolo all'identità Entra dell'agente.

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 fornisce calcolo su richiesta e ripristina su di esso lo stato persistente.

  • Persistenza dello stato: il contenuto di $HOME e /files viene salvato in modo permanente tra turni e periodi di inattività. Quando l'elaborazione diventa inattiva e viene ristabilita (in un'infrastruttura nuova o esistente), lo stato della sessione viene ripristinato automaticamente.
  • Isolamento: ogni sessione è isolata da altre sessioni.
  • Ciclo di vita automatico: le sessioni vengono create al primo utilizzo. La piattaforma attiva e disattiva automaticamente le risorse di calcolo.
  • Durata sessione: le sessioni vengono mantenute per un massimo di 30 giorni. 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.
  • API di gestione delle sessioni: elencare le sessioni, terminare le sessioni e caricare o scaricare file per sessione.

Conversazioni

Un identificativo di conversazione è un record durevole della cronologia delle conversazioni (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 con ciascun protocollo

Protocollo di risposte: l'ID 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 della 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

State Che succede
Attive Il calcolo è in esecuzione. Le richieste vengono instradate verso di esso. Sono disponibili i contenuti di $HOME e /files.
Inattivo Nessuna richiesta per 15 minuti. Il calcolo è stato deprovisionato. Lo stato della sessione ($HOME, /files) è persistente.
Ripreso Viene nuovamente fatto riferimento allo stesso ID sessione. La piattaforma fornisce nuove risorse di calcolo e ripristina lo stato persistente.

Sicurezza e gestione dei dati

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

Importante

Se si usa il servizio agente Foundry per ospitare agenti che interagiscono con modelli, server o agenti di terze parti, è possibile farlo a proprio rischio. È consigliabile esaminare tutti i dati condivisi con modelli, server o agenti di terze parti e comprendere le procedure di terze parti per la conservazione e la posizione dei dati. È responsabilità dell'utente gestire se i dati vengono trasmessi al di fuori dei limiti geografici e di conformità di Azure dell'organizzazione e di eventuali implicazioni correlate.

  • 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 Microsoft services, 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

Controllo delle versioni

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. È anche possibile suddividere il traffico tra le versioni per le distribuzioni canary o blu-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.

Casella degli strumenti di fonderia

Gli agenti ospitati accedono agli strumenti gestiti da Foundry (Code Interpreter, Ricerca Web, Ricerca intelligenza artificiale di Azure, OpenAPI, connessioni MCP personalizzate, A2A) tramite un endpoint MCP della casella degli strumenti 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 toolbox basata sulle finalità 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 allocazioni di CPU e memoria comprese tra 0,25 vCPU / 0,5 GiB e 2 vCPU / 4 GiB.

Rete privata

Gli agenti ospitati supportano la distribuzione all'interno delle risorse Foundry isolate dalla rete. Per altre informazioni, vedere Configurare le reti virtuali. ** Si noti che l'Azure Container Registry che contiene l'immagine dell'agente deve rimanere attualmente raggiungibile tramite l'endpoint pubblico; al momento, l'Azure Container Registry protetto da rete privata non è supportato.

Limiti, prezzi e disponibilità (anteprima)

Gli agenti ospitati sono attualmente in anteprima.

Limitazioni durante l'anteprima

Limite Scope Valore predefinito Adjustable
Numero massimo di sessioni simultanee attive per sottoscrizione per regione 50 Sì, con richieste di quota al supporto tecnico Microsoft

Pricing

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à della regione

Gli agenti ospitati sono attualmente disponibili nelle aree seguenti:

  • Australia orientale
  • Canada Central
  • Stati Uniti centro-settentrionali
  • Svezia centrale

Annotazioni

Questo elenco verrà aggiornato man mano che diventano disponibili altre aree.

Passaggi successivi

Attività Link
Compilare e distribuire il primo agente ospitato Guida introduttiva: Implementare il primo agente ospitato
Eseguire la distribuzione con Foundry SDK Distribuire un agente ospitato usando Foundry SDK
Aggiornare, eliminare, richiamare o trasmettere i log Gestire gli agenti ospitati
Configurare la traccia e il monitoraggio Abilitare la traccia nel progetto
Valutare le prestazioni dell'agente Valutatori di agenti
Pubblicare in Teams, M365 o app personalizzate Applicazioni dell'agente
Esplora gli esempi di codice Esempi python · Esempi di C#

Contenuti correlati

  • Last updated on