Che cosa sono gli agenti ospitati?

Quando si compilano applicazioni agentiche usando framework open source, in genere si gestisce la containerizzazione, l'installazione del server Web, l'integrazione della sicurezza, la persistenza della memoria, il ridimensionamento dell'infrastruttura, la trasmissione dei dati, la strumentazione e i 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.

Prerequisiti

• Un progetto Microsoft Foundry
• Conoscenza di base della containerizzazione e di Docker
• Familiarità con Azure Container Registry
• Conoscenza del framework agente preferito (LangGraph, Microsoft Agent Framework o codice personalizzato)

Riepilogo

Gli agenti ospitati consentono di portare il proprio codice agente ed eseguirlo come servizio gestito containerizzato.

Usare questo articolo per:

• Comprendere cosa sono gli agenti ospitati e quando usarli.
• Pacchettizzare e testare l'agente in locale prima della distribuzione.
• Creare, gestire, pubblicare e monitorare gli agenti ospitati.

Per passare a un'attività, vedere:

• Imballare il codice e testarlo in locale
• Creare un agente ospitato
• Gestire gli agenti ospitati
• Pubblicare agenti ospitati nei canali
• Risolvere i problemi relativi agli endpoint dell'agente ospitato

Limiti, prezzi e disponibilità (anteprima)

Gli agenti ospitati sono attualmente in versione di anteprima.

• Supporto di rete privata: non è possibile creare agenti ospitati usando la configurazione standard per l'isolamento di rete all'interno delle risorse Foundry isolate dalla rete. Per informazioni dettagliate, vedere Configurare le reti virtuali.
• Limiti di anteprima: per l'elenco completo dei limiti di anteprima, vedere Limitazioni durante l'anteprima.
• Prezzi: per gli aggiornamenti sui prezzi, vedere la pagina dei prezzi di Foundry.

Disponibilità della regione

Gli agenti ospitati sono supportati nelle aree seguenti:

• Brasile meridionale
• Canada orientale
• Stati Uniti orientali
• Francia centrale
• Germania centro-occidentale
• Italia settentrionale
• Stati Uniti centro-settentrionali
• Sudafrica settentrionale
• Stati Uniti centro-meridionali
• India meridionale
• Spain Central
• Svezia centrale
• Canada Central
• Korea Central
• Sud-est asiatico
• Australia orientale
• Stati Uniti orientali 2
• Japan East
• Emirati Arabi Uniti settentrionali
• UK South
• Stati Uniti occidentali
• Stati Uniti occidentali 3
• Norway East
• Poland Central
• Svizzera settentrionale

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 Configurare una connessione di Key Vault.
• Prestare attenzione a strumenti e server non Microsoft. Se l'agente chiama strumenti supportati da servizi non 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.

Comprendere i concetti chiave

Agenti ospitati

Gli agenti ospitati sono applicazioni agenti di intelligenza artificiale containerizzati eseguite sul servizio Agent. A differenza degli agenti basati su prompt, gli sviluppatori compilano agenti ospitati tramite codice e li distribuiscono come immagini del contenitore nell'infrastruttura con pagamento in base al consumo gestita da Microsoft.

Gli agenti ospitati seguono un ciclo di vita standard: creare, avviare, aggiornare, arrestare ed eliminare. Ogni fase offre funzionalità specifiche e transizioni di stato che consentono di gestire in modo efficace le distribuzioni degli agenti.

Adattatore di hosting

L'adattatore host è un livello di astrazione del framework che consente di esporre i framework dell'agente supportati (o il codice personalizzato) come servizio HTTP per i test locali e le distribuzioni ospitate.

L'adattatore di hosting offre diversi vantaggi principali per gli sviluppatori:

Test locali semplificati: eseguire l'agente in locale e convalidare l'area di attacco HTTP prima di creare contenitori e distribuirli.

Conversione automatica dei protocolli: l'adattatore gestisce tutte le conversioni complesse tra i formati di richiesta e risposta foundry e le strutture di dati native del framework agente. Tali attività includono:

• Gestione delle conversazioni
• Serializzazione dei messaggi
• Generazione di eventi di streaming

Integrazione dell'osservabilità: esportare tracce, metriche e log usando OpenTelemetry.

Integrazione facile di Foundry: gli agenti sviluppati in locale funzionano con l'API Foundry Responses, la gestione delle conversazioni e i flussi di autenticazione.

Identità dell'agente

Gli agenti ospitati che non sono stati pubblicati su una risorsa di un'applicazione per agenti vengono eseguiti con l'identità gestita del progetto. Questa identità è l'identità gestita assegnata dal sistema del progetto Foundry e viene condivisa tra tutti gli agenti non pubblicati nel progetto.

Quando si pubblica un agente ospitato, Foundry effettua il provisioning di un'identità agente distinta separata dall'identità gestita del progetto. Dopo la pubblicazione, è necessario riconfigurare le autorizzazioni per tutte le risorse di Azure a cui accede l'agente, perché le autorizzazioni di identità gestite dal progetto non vengono trasferite automaticamente alla nuova identità dell'agente.

Funzionalità del servizio gestito

Il servizio agent gestisce:

• Provisioning e scalabilità automatica degli agenti
• Orchestrazione e gestione dello stato delle conversazioni
• Gestione delle identità (identità gestita del progetto per agenti non pubblicati, identità dell'agente dedicata per gli agenti pubblicati)
• Integrazione con strumenti e modelli Foundry
• Funzionalità predefinite di osservabilità e valutazione
• Sicurezza, conformità e governance di livello aziendale

Supporto del framework e del linguaggio

Pacchetti di adattatori pubblici

• Python: azure-ai-agentserver-core, azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph
• .NET: Azure.AI.AgentServer.Core, Azure.AI.AgentServer.AgentFramework

Dimensioni delle repliche degli agenti

Per gli agenti ospitati sono attualmente supportate solo le coppie di CPU e memoria seguenti. Questi valori definiscono le dimensioni della replica; un agente può eseguire più repliche.

Impacchettare il codice ed eseguire test localmente

Prima di eseguire la distribuzione in Microsoft Foundry, compilare e testare l'agente in locale:

1. Eseguire l'agente in locale: usare l'adattatore di hosting per impacchettare il codice dell'agente e avviare un server Web locale che rende disponibile l'agente come API REST.
2. Eseguire il test usando chiamate REST: il server locale viene eseguito in localhost:8088 e accetta richieste HTTP standard.
3. Creare l'immagine del contenitore: creare un'immagine del contenitore dal codice sorgente.
4. Usare l'interfaccia della riga di comando per sviluppatori di Azure: usare azd per semplificare il processo di creazione di pacchetti e distribuzione.

Eseguire il wrapping del codice dell'agente con l'adattatore di hosting e testare localmente

Agente di esempio creato con Microsoft Agent Framework

import os
from datetime import datetime
from zoneinfo import ZoneInfo
from dotenv import load_dotenv

load_dotenv(override=True)

from agent_framework import ai_function, ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.ai.agentserver.agentframework import from_agent_framework
from azure.identity import DefaultAzureCredential

# Configure these for your Azure AI Foundry project
PROJECT_ENDPOINT = os.getenv("PROJECT_ENDPOINT")  # e.g., "https://<resource>.services.ai.azure.com/api/projects/<project>"
MODEL_DEPLOYMENT_NAME = os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-4.1")  # Your model deployment name

@ai_function
def get_local_date_time(iana_timezone: str) -> str:
    """
    Get the current date and time for a given timezone.
    
    This is a LOCAL Python function that runs on the server - demonstrating how code-based agents
    can execute custom logic that prompt agents cannot access.
    
    Args:
        iana_timezone: The IANA timezone string (e.g., "America/Los_Angeles", "America/New_York", "Europe/London")
    
    Returns:
        The current date and time in the specified timezone.
    """
    try:
        tz = ZoneInfo(iana_timezone)
        current_time = datetime.now(tz)
        return f"The current date and time in {iana_timezone} is {current_time.strftime('%A, %B %d, %Y at %I:%M %p %Z')}"
    except Exception as e:
        return f"Error: Unable to get time for timezone '{iana_timezone}'. {str(e)}"

# Create the agent with a local Python tool
agent = ChatAgent(
    chat_client=AzureAIAgentClient(
        project_endpoint=PROJECT_ENDPOINT,
        model_deployment_name=MODEL_DEPLOYMENT_NAME,
        credential=DefaultAzureCredential(),
    ),
    instructions="You are a helpful assistant that can tell users the current date and time in any location. When a user asks about the time in a city or location, use the get_local_date_time tool with the appropriate IANA timezone string for that location.",
    tools=[get_local_date_time],
)

if __name__ == "__main__":
    from_agent_framework(agent).run()

Vedere il repository degli esempi per esempi di codice in LangGraph e codice personalizzato.

Quando si esegue l'agente in locale usando l'adattatore di hosting, viene avviato automaticamente un server Web in localhost:8088. È possibile testare l'agente usando qualsiasi client REST.

@baseUrl = http://localhost:8088

POST {{baseUrl}}/responses
Content-Type: application/json
{
    "input": "Where is Seattle?"
}

Questo approccio di test locale consente di:

• Convalidare il comportamento dell'agente prima della containerizzazione.
• Problemi di debug nell'ambiente di sviluppo.
• Testare rapidamente diversi scenari di input.
• Verificare la compatibilità dell'API con l'API Foundry Responses.

Creare un agente ospitato

Creare un agente ospitato usando l'estensione VS Code Foundry

È possibile usare l'estensione Foundry per Visual Studio Code per creare agenti ospitati.

Creare un agente ospitato usando l'interfaccia della riga di comando per sviluppatori di Azure

Gli sviluppatori possono utilizzare l'estensione CLI per Sviluppatori di Azure ai agent per il provisioning e la distribuzione senza interruzioni e rapide delle loro applicazioni agentiche su Microsoft Foundry.

Questa estensione semplifica la configurazione di risorse, modelli, strumenti e risorse di knowledge base di Foundry. Ad esempio, semplifica la configurazione di Azure Container Registry per l'utilizzo dei contenitori personali, Application Insights per il logging e il monitoraggio, un'identità gestita e il controllo degli accessi basato sui ruoli. In altre parole, fornisce tutto il necessario per iniziare a usare gli agenti ospitati nel servizio di Foundry Agent.

Questa estensione è attualmente disponibile in anteprima. Non usarlo per la produzione.

Per iniziare:

1. Installare l'interfaccia della riga di comando per sviluppatori di Azure nel dispositivo.

   Se è già installata l'interfaccia della riga di comando per sviluppatori di Azure, verificare se è installata la versione più recente di azd :

   azd version
   

   Per eseguire l'aggiornamento alla versione più recente, vedere Installare o aggiornare l'interfaccia della riga di comando per sviluppatori di Azure.

2. Se inizi completamente da zero senza risorse Foundry esistenti e vuoi semplificare l'infrastruttura e la gestione dei ruoli (RBAC) necessari, scarica il modello di avvio Foundry. Il modello installa automaticamente l'estensione ai agent . Quando richiesto, è possibile specificare un nome di ambiente che crea un gruppo di risorse denominato rg-<name-you-provide>.

   azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
   

   Per controllare tutte le estensioni installate:

   azd ext list
   

   Assicurarsi di avere installato la versione più recente dell'estensione dell'agente Foundry azd .

   Se si dispone di un progetto Foundry esistente in cui si vuole distribuire l'agente e si vuole effettuare il provisioning solo delle risorse aggiuntive necessarie per la distribuzione dell'agente, eseguire questo comando in un secondo momento:

   azd ai agent init --project-id /subscriptions/[SUBSCRIPTIONID]/resourceGroups/[RESOURCEGROUPNAME]/providers/Microsoft.CognitiveServices/accounts/[ACCOUNTNAME]/projects/[PROJECTNAME]
   

3. Inizializzare il modello configurando i parametri nella definizione dell'agente:

   azd ai agent init -m <repo-path-to-agent.yaml>
   

   Il repository GitHub per un agente che si vuole ospitare in Foundry contiene il codice dell'applicazione, le dipendenze a cui si fa riferimento, Dockerfile per la containerizzazione e il file che contiene la agent.yaml definizione dell'agente. Per configurare l'agente, impostare i valori per i parametri richiesti. Questa azione registra il tuo agente sotto Services in azure.yaml per il modello scaricato. È possibile iniziare a usare gli esempi in GitHub.

4. Per aprire e visualizzare tutti i file Bicep e di configurazione associati alle azddistribuzioni basate su, usare questo comando:

   code .
   

5. Creare un pacchetto, effettuare il provisioning e distribuire il codice dell'agente come applicazione gestita in Foundry:

   azd up
   

   Questo comando astrae l'esecuzione sottostante dei comandi azd infra generate, azd provisione azd deploy. Crea anche una versione e distribuzione dell'agente ospitato sul servizio Foundry Agent. Se si dispone già di una versione di un agente ospitato, azd crea una nuova versione dello stesso agente. Per altre informazioni, vedere la documentazione dell'interfaccia della riga di comando di Azure.

Per altre informazioni su come eseguire aggiornamenti non con controllo delle versioni, oltre all'avvio, all'arresto e all'eliminazione delle distribuzioni e delle versioni dell'agente ospitato, vedere la sezione relativa alla gestione di questo articolo.

Assicurati che il controllo degli accessi in base al ruolo sia abilitato per consentire a azd di effettuare il provisioning dei servizi e dei modelli. Per indicazioni sui ruoli di Foundry, consultare Controllo degli accessi basato sui ruoli nel portale Foundry. Per i ruoli predefiniti di Azure, vedere Ruoli predefiniti di Azure.

Ruoli e autorizzazioni

• Se si dispone di una risorsa Foundry esistente ed è necessario creare un nuovo progetto Foundry per distribuire un agente ospitato, sono necessari i ruoli proprietario dell'intelligenza artificiale di Azure .

• Se si ha un progetto esistente e si vuole creare la distribuzione del modello e il registro contenitori nel progetto, è necessario il ruolo Proprietario dell'intelligenza artificiale di Azure in Foundry oltre al ruolo Collaboratore nella sottoscrizione di Azure.

• Se hai tutto configurato nel progetto per distribuire un agente ospitato, hai bisogno della funzione Reader sull'account Foundry e della funzione Utente di Azure AI nel progetto.

Per altre informazioni sui ruoli predefiniti in Foundry, vedere questo articolo .

Pulizia delle risorse

Per evitare addebiti non necessari, pulire le risorse di Azure dopo aver completato il lavoro con l'applicazione.

Quando eseguire la pulizia:

• Al termine del test o della dimostrazione dell'applicazione.
• Quando l'applicazione non è più necessaria o si passa a un altro progetto o ambiente.
• Quando si completa lo sviluppo e si è pronti per dismettere l'applicazione.

Per eliminare tutte le risorse associate e arrestare l'applicazione, eseguire il comando seguente:

azd down

Il completamento di questo processo potrebbe richiedere fino a 20 minuti.

Creare un agente ospitato usando Foundry SDK

Quando si crea un agente ospitato, il sistema registra la definizione dell'agente in Microsoft Foundry e tenta di creare una distribuzione per tale versione dell'agente.

Elenco di controllo per la pre-distribuzione

Prima di creare un agente ospitato, completare questi passaggi nell'ordine seguente:

1. Verificare l'accesso: assicurarsi di avere accesso per assegnare i ruoli in Registro Azure Container. Sono necessarie almeno le autorizzazioni di Amministratore dei permessi utente o Proprietario nel registro dei contenitori.
2. Installare Azure AI Projects SDK: eseguire il comando seguente: pip install --pre "azure-ai-projects>=2.0.0b4"
3. Creare un Registro Azure Container: creare un registro contenitori privato
4. Compilare l'immagine Docker con la piattaforma corretta: compilare ed eseguire il push dell'immagine Docker.
5. Eseguire il push dell'immagine nel registro: compilare ed eseguire il push dell'immagine Docker. Sostituire gli URL di esempio (YOUR_ACR_NAME, YOUR_IMAGE_NAME, YOUR_TAG) con i valori effettivi per l'immagine Docker e Registro Azure Container.
6. Configurare le autorizzazioni di Registro Azure Container: Configurare le autorizzazioni di Registro Azure Container
7. Creare un host di funzionalità: creare un host di funzionalità a livello di account

Compilare ed effettuare il push dell'immagine Docker su Azure Container Registry

Per costruire l'agente come contenitore Docker e caricarlo su Azure Container Registry:

1. Crea l'immagine Docker localmente.

   Importante

   È NECESSARIO specificare --platform linux/amd64 quando si compila l'immagine Docker. Gli agenti ospitati vengono eseguiti nell'infrastruttura Linux AMD64. Le immagini create per altre architetture ( ad esempio ARM64 in Apple Silicon Mac) non riusciranno a iniziare con errori di runtime del contenitore.

   docker build --platform linux/amd64 -t <YOUR_IMAGE_NAME>:<YOUR_TAG> .
   

   Fare riferimento a Dockerfile di esempio per Python e C#.

2. Accedere a Registro Azure Container:

   az acr login --name <YOUR_ACR_NAME>
   

3. Tagga l'immagine per il registro:

   docker tag <YOUR_IMAGE_NAME>:<YOUR_TAG> <YOUR_ACR_NAME>.azurecr.io/<YOUR_IMAGE_NAME>:<YOUR_TAG>
   

4. Caricare l'immagine nel Registro Container di Azure.

   docker push <YOUR_ACR_NAME>.azurecr.io/<YOUR_IMAGE_NAME>:<YOUR_TAG>
   

Per indicazioni dettagliate sull'uso delle immagini Docker in Registro Azure Container, vedere Eseguire il push e il pull di immagini Docker.

Configurare le autorizzazioni di Registro Azure Container

Prima di creare l'agente, concedere all'identità gestita del progetto l'accesso per eseguire il pull dal registro contenitori che ospita l'immagine. Gli agenti ospitati non pubblicati vengono eseguiti con questa identità gestita del progetto, quindi le autorizzazioni assegnate qui si applicano in fase di esecuzione.

1. Nel portale di Azure passare alla risorsa del progetto Foundry.

2. Nel riquadro sinistro selezionare Identità.

3. Sotto System assigned (Sistema assegnato), copiare il valore ID oggetto (principale). Questo valore è l'identità gestita alla quale assegnerai il ruolo di Azure Container Instances.

4. Concedi autorizzazioni pull assegnando il ruolo di Lettore del repository del registro dei container all'identità gestita del tuo progetto nel container registry. Per i passaggi dettagliati, vedere Ruoli e autorizzazioni di Registro Azure Container.

Creare un host di funzionalità a livello di account

Gli agenti ospitati richiedono un host di funzionalità a livello di account con hosting pubblico attivato.

L'aggiornamento degli host di funzionalità non è supportato. Se si dispone già di un host di funzionalità per l'account Microsoft Foundry, eliminarlo e ricrearlo con enablePublicHostingEnvironment impostato su true.

Usare az rest in modo da non dover gestire manualmente i token.

CLI di Azure (bash)

az rest --method put \
    --url "https://management.azure.com/subscriptions/[SUBSCRIPTIONID]/resourceGroups/[RESOURCEGROUPNAME]/providers/Microsoft.CognitiveServices/accounts/[ACCOUNTNAME]/capabilityHosts/accountcaphost?api-version=2025-10-01-preview" \
    --headers "content-type=application/json" \
    --body '{
        "properties": {
            "capabilityHostKind": "Agents",
            "enablePublicHostingEnvironment": true
        }
    }'

CLI di Azure (PowerShell)

az rest --method put `
    --url "https://management.azure.com/subscriptions/[SUBSCRIPTIONID]/resourceGroups/[RESOURCEGROUPNAME]/providers/Microsoft.CognitiveServices/accounts/[ACCOUNTNAME]/capabilityHosts/accountcaphost?api-version=2025-10-01-preview" `
    --headers "content-type=application/json" `
    --body '{
        "properties": {
            "capabilityHostKind": "Agents",
            "enablePublicHostingEnvironment": true
        }
    }'

Creare la versione dell'agente ospitato

Installare version>=2.0.0b4 di Azure AI Projects SDK. È necessario Python 3.10 o versione successiva.

pip install --pre "azure-ai-projects>=2.0.0b4"

Usare Azure AI Projects SDK per creare e registrare l'agente:

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Initialize the client
client = AIProjectClient(
    endpoint="https://your-project.services.ai.azure.com/api/projects/project-name",
    credential=DefaultAzureCredential()
)

# Create the agent from a container image
agent = client.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": "https://your-project.services.ai.azure.com/api/projects/project-name",
            "MODEL_NAME": "gpt-4",
            "CUSTOM_SETTING": "value"
        }
    )
)

# Print confirmation
print(f"Agent created: {agent.name} (id: {agent.id}, version: {agent.version})")

Output previsto:

Agent created: my-agent (id: agent_abc123, version: 1)

Ecco i parametri chiave:

• PROJECT_ENDPOINT: URL dell'endpoint per il progetto Foundry.
• AGENT_NAME: Nome univoco per il tuo agente.
• CONTAINER_IMAGE: URL completo dell'immagine del Registro Azure Container con tag.
• CPU/Memory: allocazione delle risorse (ad esempio, 1 per CPU, 2Gi per la memoria).

L'agente viene visualizzato nel portale Foundry non appena lo crei.

Gestire gli agenti ospitati

Aggiornare un agente

È possibile aggiornare un agente in due modi: aggiornamenti con versioni e aggiornamenti senza versione.

Aggiornamento versionato

Usare un aggiornamento con versione per modificare la configurazione del runtime dell'agente. Questo processo crea una nuova versione dell'agente.

Le modifiche che attivano una nuova versione includono:

• Immagine del contenitore: aggiornamento a una nuova immagine o tag.
• Allocazione delle risorse: modifica delle impostazioni della CPU o della memoria.
• Variabili di ambiente: aggiunta, rimozione o modifica delle variabili di ambiente.
• Versioni del protocollo: aggiornamento delle versioni del protocollo supportate.

Per creare una nuova versione, usare lo stesso client.agents.create_version() metodo illustrato nell'esempio di creazione con la configurazione aggiornata.

Aggiornamento non con controllo delle versioni

Usare un aggiornamento senza versione per modificare la configurazione della scalabilità orizzontale (repliche minime e massime) o i metadati dell'agente, ad esempio la descrizione e i tag. Questo processo non crea una nuova versione.

az cognitiveservices agent update

Gli argomenti per questo comando includono:

Ecco un esempio:

az cognitiveservices agent update --account-name myAccount --project-name myProject --name myAgent --agent-version 1 --min-replicas 1 --max-replicas 2

Avviare una distribuzione dell'agente

Dopo aver creato la versione dell'agente ospitato, avviare la distribuzione usando l'estensione della riga di comando az per renderla disponibile per le richieste. È anche possibile avviare un agente ospitato arrestato in precedenza.

az cognitiveservices agent start

Gli argomenti per questo comando includono:

Se non si specificano repliche massime e minime durante l'operazione di avvio dell'agente, il valore predefinito è 1 per entrambi gli argomenti.

Ecco un esempio:

az cognitiveservices agent start --account-name myAccount --project-name myProject --name myAgent --agent-version 1

az cognitiveservices agent start --account-name myAccount --project-name myProject --name myAgent --agent-version 1 --min-replicas 0 --max-replicas 2

Quando si avvia un agente:

• Stato corrente: Arrestato
• Operazione consentita: Avvio
• Stato transitorio: avvio
• Stato finale: Avviato (se riuscito) o Non riuscito (se non riuscito)

Visualizzare il flusso di log del contenitore

L'API Logstream del contenitore per gli agenti ospitati consente di accedere ai log di sistema e console del contenitore distribuito per conto dell'utente nell'ambiente Azure di Microsoft per abilitare il debug self-service per gli errori di avvio e runtime dell'agente durante la distribuzione.

Dettagli DELL'API REST

Parametri del percorso

Parametri di query

Impostazioni di timeout

• Durata massima connessione: la durata massima per una connessione al flusso di log è 10 minutes. Dopo questo periodo, il server chiuderà automaticamente la connessione client.
• Timeout di inattività: questo timeout è impostato su 1 minute. Si applica quando non è presente alcuna risposta dal client o se non è presente alcuna attività dopo la risposta precedente durante il flusso di log. Se la connessione rimane inattiva per 1 minuto, verrà chiusa dal server.

Codici di stato della risposta

• 200 OK: flusso di testo normale delle righe di log, una per riga.
• 404 Not Found: la versione dell'agente, la replica o l'endpoint del log del contenitore non sono stati trovati.
• 401/403: il chiamante non dispone dell'autorizzazione.
• 5xx: propagato dalle chiamate al contenitore downstream quando non è possibile recuperare i dettagli o i token.

Esempio: Ottenere i log usando curl

curl -N "https://{endpoint}/api/projects/{projectName}/agents/{agentName}/versions/{agentVersion}/containers/default:logstream?kind=console&tail=500&api-version=2025-11-15-preview" \
  -H "Authorization: Bearer $(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)"

Bandiere:

• -N disabilita il buffer di output (importante per i log di streaming in tempo reale)

Esempi di risposta

200 OK (log della console)

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

2025-12-15T08:43:48.72656  Connecting to the container 'agent-container'...
2025-12-15T08:43:48.75451  Successfully Connected to container: 'agent-container' [Revision: 'je90fe655aa742ef9a188b9fd14d6764--7tca06b', Replica: 'je90fe655aa742ef9a188b9fd14d6764--7tca06b-6898b9c89f-mpkjc']
2025-12-15T08:33:59.0671054Z stdout F INFO:     127.0.0.1:42588 - "GET /readiness HTTP/1.1" 200 OK
2025-12-15T08:34:29.0649033Z stdout F INFO:     127.0.0.1:60246 - "GET /readiness HTTP/1.1" 200 OK
2025-12-15T08:34:59.0644467Z stdout F INFO:     127.0.0.1:43994 - "GET /readiness HTTP/1.1" 200 OK
2025-12-15T08:35:29.0651892Z stdout F INFO:     127.0.0.1:59368 - "GET /readiness HTTP/1.1" 200 OK
2025-12-15T08:35:59.0644637Z stdout F INFO:     127.0.0.1:57488 - "GET /readiness HTTP/1.1" 200 OK

200 OK (log di sistema)

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

{"TimeStamp":"2025-12-15T16:51:33Z","Type":"Normal","ContainerAppName":null,"RevisionName":null,"ReplicaName":null,"Msg":"Connecting to the events collector...","Reason":"StartingGettingEvents","EventSource":"ContainerAppController","Count":1}
{"TimeStamp":"2025-12-15T16:51:34Z","Type":"Normal","ContainerAppName":null,"RevisionName":null,"ReplicaName":null,"Msg":"Successfully connected to events server","Reason":"ConnectedToEventsServer","EventSource":"ContainerAppController","Count":1}

Fermare una distribuzione dell'agente

Per arrestare l'agente ospitato, impostare la replica massima per la distribuzione dell'agente su zero e usare il comando seguente:

az cognitiveservices agent stop

Gli argomenti per questo comando includono:

Ecco un esempio:

az cognitiveservices agent stop --account-name myAccount --project-name myProject --name myAgent --agent-version 1

Quando si arresta un agente:

• Stato corrente: in esecuzione
• Operazione consentita: Arresta
• Stato transitorio: arresto
• Stato finale: Interrotto (se ha avuto successo) o In esecuzione (se non ha avuto successo)

Eliminazione di un agente

È possibile eliminare gli agenti a vari livelli, a seconda di ciò che si vuole rimuovere.

Eliminare solo un deployment

Il comando seguente arresta l'agente in esecuzione ma mantiene la versione dell'agente per un uso futuro. Usarlo quando si vuole arrestare temporaneamente l'agente o passare a una versione diversa.

az cognitiveservices agent delete-deployment

Gli argomenti per questo comando includono:

Eliminare l'agente

Il comando seguente rimuove tutte le versioni e le distribuzioni per l'agente. Usarlo quando non è più necessario l'agente e si vuole pulire tutte le risorse associate.

Se si specifica agent_version e si elimina la distribuzione dell'agente, l'operazione elimina la definizione dell'agente associata a tale versione. Se la distribuzione dell'agente è in esecuzione, l'operazione non va a buon fine.

Se non si specifica agent_version, l'operazione elimina tutte le versioni dell'agente associate al nome dell'agente.

az cognitiveservices agent delete

Gli argomenti per questo comando includono:

Elencare gli agenti ospitati

Elencare tutte le versioni di un agente ospitato

az cognitiveservices agent list-versions

Gli argomenti per questo comando includono:

Visualizzare i dettagli di un agente ospitato

az cognitiveservices agent show

Gli argomenti per questo comando includono:

Richiamare gli agenti ospitati

È possibile visualizzare e testare gli agenti ospitati nell'interfaccia utente dell'area di prova degli agenti. Gli agenti ospitati espongono un'API compatibile con le risposte OpenAI. Usare Azure AI Projects SDK per richiamare questa API.

#!/usr/bin/env python3
"""
Call a deployed Microsoft Foundry agent
"""

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Configuration
PROJECT_ENDPOINT = "https://your-project.services.ai.azure.com/api/projects/your-project"
AGENT_NAME = "your-agent-name"

# Initialize the client and retrieve the agent
client = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
agent = client.agents.get(agent_name=AGENT_NAME)
print(f"Agent retrieved: {agent.name} (version: {agent.versions.latest.version})")

# Get the OpenAI client and send a message
openai_client = client.get_openai_client()
response = openai_client.responses.create(
    input=[{"role": "user", "content": "Hello! What can you help me with?"}],
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}}
)

print(f"Agent response: {response.output_text}")

Output previsto:

Agent retrieved: your-agent-name (version: 1)
Agent response: Hello! I'm your hosted agent. I can help you with...

Per altre informazioni, vedere Azure AI Projects SDK per Python.

Usare strumenti con agenti ospitati

Prima che l'agente ospitato possa funzionare con gli strumenti Foundry, stabilisci una connessione al server remoto del protocollo di contesto del modello (MCP) in Foundry.

La RemoteMCPTool connessione supporta questi meccanismi di autenticazione:

• Credenziali archiviate: usare le credenziali predefinite archiviate nel sistema.
• Identità gestita del progetto: usare l'identità gestita per il progetto Foundry.

Scegliere il metodo di autenticazione:

• Per l'identità condivisa: usare l'autenticazione dell'identità gestita basata su chiave o progetto Foundry quando ogni utente dell'agente deve usare la stessa identità. L'identità o il contesto dell'utente singolo non vengono mantenuti con questi metodi.

• Per il contesto utente singolo: usare il pass-through dell'identità OAuth quando ogni utente dell'agente deve usare il proprio account per l'autenticazione con il server MCP. Questo approccio mantiene il contesto utente personale.

Per altre informazioni, vedere Connettersi ai server del protocollo di contesto modello.

Fare riferimento all'ID connessione dello strumento Foundry per i server MCP remoti all'interno del codice dell'agente usando una variabile di ambiente. Effettua il wrapping utilizzando l'adattatore di hosting per i test locali. Costruire e pushare l'immagine Docker su Azure Container Registry (ACR). Configurare le autorizzazioni di recupero delle immagini nell'Azure Container Registry. Creare un host di funzionalità seguendo le istruzioni indicate in precedenza e procedere alla registrazione dell'agente in Foundry.

Creare una versione degli agenti ospitati con la definizione degli strumenti usando Foundry SDK.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Initialize the client
client = AIProjectClient(
    endpoint="https://your-project.services.ai.azure.com/api/projects/project-name",
    credential=DefaultAzureCredential()
)

# Create the agent from a container image
agent = client.agents.create_version(
    agent_name="my-agent",
    description="Coding agent expert in assisting with github issues",
    definition=HostedAgentDefinition(
        container_protocol_versions=[ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        tools=[
            {
                "type": "code_interpreter"
            },
            {
                "type": "mcp",
                "project_connection_id": "github_connection_id"
            }
        ],
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": "https://your-project.services.ai.azure.com/api/projects/project-name",
            "MODEL_NAME": "gpt-4",
            "CUSTOM_SETTING": "value"
        }
    )
)

Avvia l'agente usando l'Azure Cognitive Services CLI o da Agent Builder nella nuova interfaccia utente di Foundry.

Gli strumenti Foundry predefiniti attualmente supportati includono:

• Interprete di codice
• Generazione di immagini
• Web Search

Gestire l'osservabilità con gli agenti ospitati

Gli agenti ospitati supportano l'esposizione di tracce, metriche e log OpenTelemetry dai framework sottostanti a Microsoft Foundry con Application Insights o a qualsiasi endpoint dell'agente di raccolta OpenTelemetry specificato dall'utente.

Se si utilizza l'estensione azd ai agent dell'interfaccia della riga di comando, Application Insights viene automaticamente sottoposto a provisioning e connesso al progetto Foundry. All'identità gestita del progetto viene concesso il ruolo utente di Intelligenza artificiale di Azure nella risorsa Foundry in modo che le tracce vengano esportate in Application Insights.

Se si usa Foundry SDK, è necessario eseguire questi passaggi in modo indipendente. Per altre informazioni, vedere Abilitare la traccia nel progetto.

L'adattatore di hosting fornisce:

• Completare l'installazione di OpenTelemetry: TracerProvider, MeterProvider, LoggerProvider.
• Strumentazione automatica: richieste HTTP, chiamate di database, chiamate al modello di intelligenza artificiale.
• Integrazione di Azure Monitor: esportazione, formattazione, autenticazione.
• Ottimizzazione delle prestazioni: campionamento, invio in batch, rilevamento delle risorse.
• Metriche in tempo reale: dashboard in tempo reale in Application Insights.

Tracciamento locale

1. Installare e configurare AI Toolkit per Visual Studio Code (VS Code) seguendo la traccia in AI Toolkit.

2. Configurare ed esportare la variabile di ambiente OTEL_EXPORTER_ENDPOINT. È possibile trovare l'endpoint nel Toolkit AI per VS Code dopo aver selezionato il pulsante Avvia raccolta.

3. Richiamare l'agente e trovare tracce in AI Toolkit.

Traccia nel portale Foundry

È possibile esaminare anche le tracce per l'agente ospitato nella scheda Tracce nell'area di test.

Esportare tracce al server compatibile con OpenTelemetry

Per inviare tracce al proprio agente di raccolta OpenTelemetry o alla piattaforma di osservabilità compatibile, usare la variabile OTEL_EXPORTER_ENDPOINTdi ambiente .

Gestire le conversazioni usando agenti ospitati

Gli agenti ospitati si integrano perfettamente con il sistema di gestione delle conversazioni in Microsoft Foundry. Questa integrazione consente interazioni a stati multipli con mantenimento dello stato senza gestione dello stato manuale.

Funzionamento delle conversazioni con gli agenti ospitati

Oggetti di conversazione: Foundry crea automaticamente oggetti di conversazione durevoli con identificatori univoci che vengono mantenuti tra più interazioni tra agenti. Quando un utente avvia una conversazione con l'agente ospitato, la piattaforma gestisce automaticamente questo contesto di conversazione.

Gestione dello stato: a differenza delle API tradizionali in cui si passa manualmente la cronologia delle conversazioni, gli agenti ospitati ricevono automaticamente il contesto di conversazione. Il runtime Foundry gestisce:

• Messaggi e risposte precedenti.
• Le chiamate agli strumenti e i relativi output.
• Istruzioni e configurazione dell'agente.
• Metadati della conversazione e timestamp.

Elementi di conversazione: ogni conversazione contiene elementi strutturati che il sistema gestisce automaticamente:

• Messaggi: input utente e risposte dell'agente con timestamp.
• Chiamate agli strumenti: chiamate di funzione con parametri e risultati.
• Output degli strumenti: risposte strutturate da servizi esterni.
• Messaggi di sistema: informazioni sullo stato interno e sul contesto.

Persistenza e riutilizzo della conversazione

Continuità tra sessioni: le conversazioni vengono mantenute oltre le singole richieste. Gli utenti possono tornare alle discussioni precedenti con il contesto completo gestito.

Riutilizzo della conversazione: gli utenti possono accedere alla stessa conversazione da più canali e applicazioni. Le conversazioni mantengono uno stato e una cronologia coerenti.

Pulizia automatica: Foundry gestisce il ciclo di vita e la pulizia delle conversazioni in base alle politiche di conservazione del progetto.

Valutare e testare gli agenti ospitati

Microsoft Foundry offre funzionalità complete di valutazione e test progettate per gli agenti ospitati. Usare queste funzionalità per convalidare le prestazioni, confrontare le versioni e garantire la qualità prima della distribuzione.

Funzionalità di valutazione predefinite

Valutazione delle prestazioni dell'agente: Foundry include metriche di valutazione predefinite per valutare l'efficacia dell'agente ospitato:

• Qualità e pertinenza della risposta
• La precisione nel completamento delle attività
• Efficacia dell'utilizzo degli strumenti
• Coerenza della conversazione e conservazione del contesto
• Metriche relative al tempo di risposta e all'efficienza

Valutazione specifica dell'agente: valutare gli agenti ospitati usando Foundry SDK con analizzatori predefiniti progettati per i flussi di lavoro agenti. L'SDK fornisce analizzatori specializzati per misurare le prestazioni dell'agente tra dimensioni chiave, ad esempio risoluzione delle finalità, conformità alle attività e accuratezza dell'utilizzo degli strumenti.

Test dei flussi di lavoro per gli agenti ospitati

Test di sviluppo: testare l'agente ospitato in locale durante lo sviluppo usando il playground dell'agente e gli strumenti di test locali prima della distribuzione.

Convalida dell'ambiente di staging: Implementare la distribuzione in un ambiente di staging per convalidare il comportamento usando l'infrastruttura reale di Foundry pur mantenendo l'isolamento dall'ambiente di produzione.

Monitoraggio della produzione: monitorare continuamente gli agenti ospitati distribuiti usando esecuzioni di valutazione automatizzate per rilevare la riduzione delle prestazioni o i problemi.

Approcci di valutazione strutturati

Creazione del set di dati di test: creare set di dati di test completi che coprono:

• Modelli di interazione utente comuni.
• Casi limite e scenari di errore.
• Flussi di conversazione a più turni.
• Scenari di utilizzo degli strumenti.
• Test di stress delle prestazioni.

Metriche di valutazione supportate: Foundry SDK fornisce gli analizzatori seguenti per i flussi di lavoro dell'agente:

• Risoluzione delle finalità: misura il grado di identificazione e comprensione delle richieste utente da parte dell'agente.
• Conformità alle attività: valuta se le risposte dell'agente rispettano le attività assegnate e le istruzioni di sistema.
• Accuratezza della Chiamata degli Strumenti: determina se l'agente effettua chiamate corrette alle funzioni degli strumenti per le richieste degli utenti.
• Metriche di qualità aggiuntive: consente l'uso di pertinenza, coerenza e fluenza con i messaggi dell'agente.

Procedure consigliate per la valutazione

Eseguire test con dati rappresentativi: creare set di dati di valutazione che rappresentano le interazioni utente effettive e i casi d'uso.

Monitorare le prestazioni dell'agente: usare il portale Foundry per tenere traccia delle prestazioni dell'agente e esaminare le tracce di conversazione.

Usare la valutazione iterativa: valutare regolarmente le versioni degli agenti durante lo sviluppo per rilevare i problemi in anticipo e misurare i miglioramenti.

Per altre informazioni sulla valutazione degli agenti, vedere Valutare gli agenti di intelligenza artificiale e gli analizzatori di agenti.

Pubblicare agenti ospitati sui canali

La pubblicazione trasforma l'agente ospitato da un asset di sviluppo in una risorsa di Azure gestita con un endpoint dedicato, un'identità indipendente e funzionalità di governance. Prima della pubblicazione, gli agenti ospitati vengono eseguiti con l'identità gestita del progetto. Dopo aver pubblicato l'agente ospitato, è possibile condividerlo tra più canali e piattaforme.

Processo di pubblicazione per gli agenti ospitati

Quando si pubblica un agente ospitato, Microsoft Foundry esegue automaticamente le operazioni seguenti:

1. Crea una risorsa applicazione agente con un URL di chiamata dedicato.
2. Fornisce un'identità agente distinta e separata dall'identità gestita del progetto utilizzata dagli agenti non pubblicati.
3. Registra l'agente nel registro degli agenti di Microsoft Entra per l'individuazione e la governance.
4. Abilita l'accesso all'endpoint stabile che rimane coerente durante la distribuzione di nuove versioni dell'agente.

A differenza degli agenti basati su prompt che è possibile modificare nel portale, gli agenti ospitati mantengono l'implementazione basata sul codice ottenendo le stesse funzionalità di pubblicazione e condivisione.

Canali di pubblicazione disponibili

Anteprima dell'applicazione Web: usare un'interfaccia Web per illustrare e testare l'agente ospitato con gli stakeholder. È istantaneo e condivisibile.

Microsoft 365 Copilot e Teams: integrare l'agente ospitato direttamente in Microsoft 365 Copilot e Microsoft Teams tramite un flusso di pubblicazione senza codice semplificato. L'agente appare nello store degli agenti per la distribuzione a livello aziendale o condiviso.

Endpoint API stabile: accedere all'agente ospitato a livello di codice tramite un'API REST coerente che rimane invariata man mano che si aggiornano le versioni dell'agente.

Applicazioni personalizzate: incorporare l'agente ospitato in applicazioni esistenti usando l'endpoint stabile e l'integrazione dell'SDK.

Considerazioni sulla pubblicazione per gli agenti ospitati

Gestione delle identità: prima della pubblicazione, gli agenti ospitati utilizzano l'identità gestita del progetto. Dopo la pubblicazione in una risorsa dell'applicazione agente, Foundry assegna un'identità dedicata all'agente. È necessario riconfigurare le autorizzazioni per le risorse di Azure a cui accede l'agente, perché le autorizzazioni di identità gestite dal progetto non vengono trasferite automaticamente alla nuova identità agente.

Controllo della versione: la pubblicazione crea una distribuzione che fa riferimento alla versione dell'agente corrente. È possibile aggiornare l'agente pubblicato distribuendo nuove versioni senza modificare l'endpoint pubblico.

Autenticazione: gli agenti pubblicati supportano l'autenticazione basata su RBAC per impostazione predefinita. Questa autenticazione include la gestione automatica delle autorizzazioni per l'integrazione del servizio Azure Bot durante la pubblicazione nei canali di Microsoft 365.

Per istruzioni dettagliate sulla pubblicazione, vedere Pubblicare e condividere agenti.

Risolvere i problemi relativi agli endpoint dell'agente ospitato

Se la distribuzione dell'agente non riesce, è possibile visualizzare i log degli errori selezionando Visualizza log di distribuzione. Se vengono visualizzati errori 4xx, usare la tabella seguente per determinare i passaggi successivi. Se l'endpoint agente restituisce codici di stato 5xx, contattare il supporto tecnico Microsoft.

Risolvere i problemi di runtime

Se l'agente ospitato viene distribuito correttamente ma non risponde come previsto, verificare questi problemi comuni:

Per eseguire il debug dei problemi di runtime:

1. Usare l'API del flusso di log per visualizzare i log dei contenitori in tempo reale.
2. Per informazioni dettagliate sulle richieste e sulla risposta, vedere la scheda Tracce nel playground del portale Foundry.
3. Verificare che le variabili di ambiente siano impostate correttamente nella definizione dell'agente.

Comprendere i dettagli dell'anteprima

Limitazioni durante l'anteprima

Prezzi di hosting

La fatturazione per il runtime di hosting gestito è abilitata non prima del 1° aprile 2026 durante l'anteprima. Per gli aggiornamenti sui prezzi, vedere la pagina dei prezzi di Foundry.

Supporto della rete privata

Attualmente, non è possibile creare agenti ospitati usando la configurazione standard all'interno delle risorse Foundry isolate dalla rete. Per altre informazioni, vedere Configurare le reti virtuali.

Contenuti correlati

• Esempi di codice Python
• Esempi di codice C#
• Componenti di runtime dell'agente
• Ciclo di vita di sviluppo dell'agente
• Concetti relativi all'identità degli agenti in Microsoft Foundry
• Scoprire strumenti in Foundry Tools
• Pubblicare e condividere agenti in Microsoft Foundry
• Documentazione di Registro Azure Container