Distribuire un agente ospitato

Questo articolo illustra come distribuire un agente in contenitori nel servizio Foundry Agent usando l'interfaccia della riga di comando di Azure Developer (azd), Python SDK o l'API REST. Scegliere un metodo di distribuzione usando il selettore nella parte superiore dell'articolo. Usare gli approcci SDK o REST quando si vogliono gestire le distribuzioni degli agenti direttamente dalle applicazioni o dai servizi personali.

Se si esegue la distribuzione per la prima volta o si vuole una procedura dettagliata guidata, vedere Avvio rapido: Creare e distribuire un agente ospitato. Azure Developer CLI (azd) e l'estensione di VS Code gestiscono automaticamente la compilazione, la pubblicazione, la gestione delle versioni e la configurazione RBAC.

Ciclo di vita dell'implementazione

Ogni distribuzione dell'agente ospitato segue questa sequenza:

1. Compila e invia - Crea un'immagine del contenitore che includa il codice dell'agente e inviala ad Registro Azure Container.
2. Crea una versione dell'agente - Registra l'immagine con Foundry Agent Service. La piattaforma fornisce l'infrastruttura e crea un'identità dedicata dell'agente Entra.
3. Verificare lo stato - Attendere che la versione raggiunga lo stato active.
4. Invoke : inviare richieste all'endpoint dedicato dell'agente.

Prerequisiti

• Progetto Microsoft Foundry.
• Codice dell'agente che usa un framework supportato.
• Docker Desktop installato per lo sviluppo di contenitori locali.
• interfaccia della riga di comando di Azure versione 2.80 o successiva.

Autorizzazioni necessarie

Per distribuire un agente ospitato, devi disporre del ruolo Foundry Project Manager a livello di progetto. Questo ruolo concede le autorizzazioni del piano dati per creare e aggiornare gli agenti, oltre alla possibilità di creare assegnazioni di ruolo per l'identità dell'agente creata dalla piattaforma, se necessario. Per una suddivisione dettagliata delle autorizzazioni coinvolte, vedi Riferimento alle autorizzazioni dell'agente ospitato.

La piattaforma crea un'identità dell'agente Microsoft Entra dedicata per ogni agente ospitato in fase di distribuzione. Questa identità è un'entità servizio usata dal contenitore in esecuzione per chiamare modelli e strumenti. Non è necessario configurare manualmente le identità gestite. 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 si usa azd o l'estensione VS Code, gli strumenti gestiscono automaticamente la maggior parte delle assegnazioni RBAC, compresa l'assegnazione del ruolo Lettore del repository di Registro Container per l'identità gestita del progetto (pull di immagini).

Per altre informazioni, vedere Autenticazione e autorizzazione.

Requisiti dei contenitori

L'immagine del container deve soddisfare i requisiti seguenti per essere eseguita sulla piattaforma Hosted agent.

Librerie di protocolli

Gli agenti ospitati comunicano con il gateway Foundry tramite librerie di protocolli. Scegliere il protocollo che corrisponde al modello di interazione dell'agente:

Il protocollo WebSocket usa l'identificatore invocations_ws e viene fornito nello stesso azure-ai-agentserver-invocations pacchetto della route HTTP /invocations , in modo che un contenitore possa servire entrambi. Usalo quando hai bisogno di uno streaming full-duplex continuo, ad esempio per inviare il PCM del microfono all'agente e ricevere in risposta audio sintetico. Per gli scenari vocali, vedere Creare un agente vocale con agenti ospitati.

Un singolo contenitore può esporre più protocolli contemporaneamente dichiarandoli quando si crea l'agente, nel protocols campo del azure.ai.agent servizio in azure.yaml, una chiamata SDK o una richiesta API REST e importando le librerie necessarie. Usare le librerie di protocolli all'interno del framework esistente, sia che si tratti di Microsoft Agent Framework, LangChain o codice personalizzato.

Libreria di protocolli di risposta

Le librerie Python e .NET per il protocollo Risposte implementano l'API risposte di intelligenza artificiale Azure. Importare il pacchetto e implementare l'interfaccia IResponseHandler . La libreria gestisce il routing, lo streaming con eventi inviati dal server ( SSE), l'esecuzione in background, l'annullamento, la memorizzazione nella cache e la gestione del ciclo di vita delle risposte.

IResponseHandler

IResponseHandler è l'astrazione di base implementata. La libreria chiama CreateAsync per ogni richiesta in ingresso e consegna il IAsyncEnumerable<ResponseStreamEvent> restituito ai client attraverso la crittografia del servizio di archiviazione.

public class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: async ct =>
            {
                var input = await context.GetInputTextAsync(cancellationToken: ct);
                return $"Echo: {input}";
            });
    }
}

ResponseEventStream

ResponseEventStream gestisce automaticamente sequenceNumber, outputIndex, contentIndex, itemId e il ciclo di vita completo Response. Ogni yield return esegue il mapping uno-a-uno a un evento di crittografia del servizio di archiviazione, quindi non è necessario tenere traccia di questo stato manualmente.

Modalità di streaming e in background

• Modalità di streaming (impostazione predefinita): gli eventi SSE vengono recapitati in tempo reale al client connesso.
• Modalità in background: il gestore viene eseguito completamente anche senza un client di crittografia del servizio di archiviazione connesso. Gli eventi vengono memorizzati nel buffer e disponibili per la riproduzione tramite GET /responses/{id}.

Ciclo di vita della risposta

La libreria gestisce l'intero ciclo di vita della risposta: created ->in_progress ->completed (o failed o cancelled). La libreria gestisce automaticamente l'annullamento, la gestione degli errori e garantisce gli eventi terminali.

Sicurezza dei thread

Tutte le istanze del servizio registrate tramite AddResponsesServer() sono thread-safe. Le istanze del gestore hanno ambito per richiesta.

Per indicazioni dettagliate sull'implementazione del gestore, vedere la guida all'implementazione handler. Per esempi eseguibili, vedere gli esempi di protocollo Responses.

Endpoint di integrità

Le librerie di protocolli espongono automaticamente un /readiness endpoint per i controlli di integrità della piattaforma. Non è necessario implementare questa operazione manualmente.

Porta

I container servono traffico sulla porta 8088 localmente. Nell'ambiente di produzione, il gateway Foundry gestisce il routing e il contenitore non deve esporre una porta pubblica.

Variabili di ambiente inserite dalla piattaforma

La piattaforma dell'agente ospitato inserisce automaticamente le variabili di ambiente nel contenitore in fase di esecuzione. Il codice può leggere queste variabili senza dichiararle nella env mappa del azure.ai.agent servizio in o nelle azure.yaml impostazioni delle variabili di ambiente REST e SDK. Il FOUNDRY_* prefisso è riservato per l'uso della piattaforma.

Non ripetere le variabili inserite dalla piattaforma in azure.yaml : vengono impostate automaticamente.

Le variabili che dichiari tu stesso, come MODEL_DEPLOYMENT_NAME o gli endpoint MCP del toolbox, vanno nella mappa env del servizio azure.ai.agent in azure.yaml o nella chiamata SDK create_version.

Riferimenti alle connessioni di progetto nelle variabili di ambiente

Anziché codificare direttamente i segreti (chiavi API, token, endpoint) in azure.yaml o nella tua immagine, recuperali da una connessione di progetto Foundry all'avvio della sandbox. Qualsiasi valore dichiarato come variabile di ambiente può essere un'espressione segnaposto risolta dalla piattaforma prima dell'avvio del contenitore.

Sintassi del segnaposto

Un segnaposto ha la forma ${{connections.<name>.<path>}}, dove <name> è il nome della risorsa della connessione (visibile nel portale in Dettagli progetto>Risorse connesse) e <path> è uno dei seguenti:

Il nome del campo da usare dipende dalla categoria di connessione:

Example

Per prima cosa, crea una connessione CustomKeys nel progetto che contiene il segreto. Vedere Aggiungi una nuova connessione in Microsoft Foundry. Quindi fare riferimento a esso dalla env mappa nel azure.ai.agent servizio in azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    env:
      MODEL_DEPLOYMENT_NAME: gpt-5-mini
      GITHUB_TOKEN: ${{connections.agent-secrets.credentials.github_token}}

All'avvio della sandbox Foundry risolve il segnaposto e inserisce il valore risolto come variabile di ambiente normale. Il codice lo legge come qualsiasi altro var di env:

import os
token = os.environ["GITHUB_TOKEN"]

Una funzione GET sulla versione dell'agente restituisce il testo letterale ${{...}} , ovvero il segreto risolto non viene mai restituito tramite l'API di gestione.

Considerazioni

• Creare la connessione prima di distribuire la versione. Se la connessione o il campo a cui si fa riferimento non è presente all'avvio della sandbox, il segnaposto non viene risolto e la variabile è vuota.
• I segreti sono di sola scrittura. GET su una connessione restituisce credentials: null. Verificare la risoluzione leggendo la variabile d'ambiente dall'interno del container in esecuzione, non ispezionando la connessione.
• Annota tu stesso i nomi dei campi CustomKeys. L'API di gestione non le restituisce mai dopo la creazione. Tienili accanto alla sorgente dell'agente (ad esempio, nei modelli IaC o accanto a azure.yaml) in modo da poter creare dei segnaposto successivamente senza dover tirare a indovinare.
• Foundry gestisce il nome del segreto di backup. Quando si crea la connessione, Foundry archivia il valore in Key Vault sotto un nome scelto. Non è possibile fare riferimento a un Key Vault segreto preesistente in base al nome. Per collegare il proprio Key Vault come archivio di supporto, vedi Configurare una connessione a Key Vault.

Creare un pacchetto e testare l'agente in locale

Prima di eseguire la distribuzione in Foundry, verificare che l'agente funzioni in locale usando la libreria di protocolli. Il contenitore gestisce gli stessi endpoint in locale come avviene nell'ambiente di produzione.

Testare il protocollo Risposte

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

Testare il protocollo Invocations

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

azd up

azd deploy

azd ai agent show

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(
            image="your-registry.azurecr.io/your-image:tag"
        ),
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

protocol_versions=[
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS_WS, version="1.0.0"),
],

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Foundry-Features": "HostedAgents=V1Preview"
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v1"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{
    "message": "Process this task"
  }'

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v2"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Pulire le risorse

Per evitare addebiti, pulire le risorse al termine. Il provisioning della risorsa di calcolo dell'agente viene annullato dopo 15 minuti di inattività, pertanto non ci sono costi quando l'agente non gestisce le richieste.

azd down

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

project.agents.delete(agent_name="my-agent")

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Risoluzione dei problemi

Gli errori di provisioning si manifestano nei campi error.code e error.message dell'oggetto versione. Controllare lo stato della versione dopo la creazione per identificare i problemi.

Per gli errori 5xx, contattare Microsoft supporto tecnico.

Per requisiti dettagliati di controllo degli accessi basati su ruolo e risoluzione dei problemi di autorizzazione, vedere il riferimento sulle autorizzazioni dell'agente ospitato.

Passaggi successivi

Contenuto correlato

• Cosa sono gli agenti ospitati?
• Aggiungere una protezione per la sicurezza del contenuto a un agente ospitato
• Concetti relativi all'identità dell'agente
• Applicazioni dell'agente

• Documentazione di Registro Azure Container