Distribuire un agente ospitato

Questo articolo illustra come distribuire un agente in contenitori nel servizio Foundry Agent usando Python SDK o l'API REST. Usare questi approcci 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 il percorso più rapido, usare invece la guida introduttiva: Creare e distribuire un agente ospitato . La guida introduttiva utilizza l'interfaccia della riga di comando Azure Developer CLI (azd) o l'estensione di VS Code, che gestiscono automaticamente la compilazione, il push, il versionamento e la configurazione di RBAC.

Ciclo di vita della distribuzione

Ogni distribuzione dell'agente ospitato segue questa sequenza:

1. Build e push — Crea un pacchetto del codice dell'agente in un'immagine del contenitore e inviala a Registro di Azure Container.
2. Creare una versione dell'agente : registrare l'immagine con il servizio agente Foundry. La piattaforma fornisce l'infrastruttura e crea un'identità dedicata dell'agente Entra.
3. Controllo periodico dello stato — attendere che lo stato della versione raggiunga active.
4. Invoke : inviare richieste all'endpoint dedicato dell'agente.

Prerequisiti

• Un progetto di 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

È necessario Azure AI Project Manager nell'ambito del progetto per creare e distribuire agenti ospitati. Questo ruolo include sia le autorizzazioni del piano dati per creare agenti che la possibilità di assegnare il ruolo utente di Intelligenza artificiale di Azure all'identità dell'agente creata dalla piattaforma. L'identità dell'agente richiede all'utente di Intelligenza artificiale di Azure nel progetto di accedere ai modelli e agli artefatti in fase di esecuzione.

Se si usa azd o l'estensione VS Code, gli strumenti gestiscono automaticamente la maggior parte delle assegnazioni di controllo degli accessi in base al ruolo, tra cui:

• Lettore del repository del registro dei container per l'identità gestita del progetto (estrazione delle immagini)
• Utente di Intelligenza artificiale di Azure per l'identità dell'agente creata dalla piattaforma (modello di runtime e accesso agli strumenti)

Per altre informazioni, vedere Autenticazione e autorizzazione.

Requisiti dei contenitori

L'immagine del contenitore deve soddisfare i requisiti seguenti per essere eseguita sulla piattaforma dell'agente ospitato.

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:

Un singolo contenitore può esporre entrambi i protocolli contemporaneamente dichiarando sia quando si crea l'agente, nel file, nella agent.yaml chiamata SDK o nella richiesta api REST, sia importando entrambe le librerie. Usare le librerie di protocolli all'interno del framework esistente, sia che si tratti di Microsoft Agent Framework, LangChain o codice personalizzato.

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.

Porto

I container servono il traffico sulla porta 8088 localmente. Nell'ambiente di produzione, il gateway Foundry gestisce il routing, quindi il container 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ò leggerli senza dichiararli in agent.yaml o environment_variables. Il FOUNDRY_* prefisso è riservato per l'uso della piattaforma.

Non ridefinire le variabili inserite dalla piattaforma in agent.yaml — vengono impostate automaticamente.

Le variabili dichiarate dall'utente, come MODEL_DEPLOYMENT_NAME o gli endpoint MCP della casella degli strumenti, vanno nella sezione environment_variables di agent.yaml o nella chiamata SDK create_version.

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 invocazioni

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

{
    "message": "Hello!"
}

Eseguire la distribuzione usando l'interfaccia della riga di comando per sviluppatori di Azure o VS Code

L'interfaccia della riga di comando per sviluppatori di Azure (azd) e l'estensione VS Code automatizzano il ciclo di vita completo della distribuzione. Per una procedura dettagliata, vedere Avvio rapido: Creare e distribuire un agente ospitato.

Eseguire la distribuzione con Python SDK

Usare l'SDK per gestire le distribuzioni degli agenti direttamente dal codice Python.

Prerequisiti aggiuntivi

• Python 3.10 o versione successiva

• Immagine del contenitore in Azure Container Registry

• Writer del repository del registro contenitori o ruolo AcrPush nel registro contenitori (per eseguire il push delle immagini)

• Azure AI Projects SDK versione 2.1.0 o successiva

  pip install "azure-ai-projects>=2.1.0"
  

Creare l'immagine del contenitore ed eseguirne il push

1. Costruisci la tua immagine Docker:

   docker build --platform linux/amd64 -t myagent:v1 .
   

   Vedere i Dockerfile di esempio per Python e C#.

2. Eseguire il push su Azure Container Registry

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

Configurare le autorizzazioni del registro dei container

Concedere all'identità gestita del progetto l'accesso per scaricare le immagini:

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

2. Selezionare Identità e copiare l'ID oggetto (entità) sotto Assegnato dal sistema.

3. Assegnare il ruolo Lettore repository Registro Container a questa identità nel Registro Container. Consulta Azure Container Registry ruoli e autorizzazioni.

Creare una versione dell'agente ospitato

La creazione di una versione fa sì che la piattaforma avvii automaticamente l'approvvigionamento dell'agente. Non esiste un passaggio di avvio separato: la piattaforma compila uno snapshot del contenitore e rende l'agente pronto per la gestione delle richieste.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
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(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        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}")

Per esporre entrambi i protocolli, passare entrambi in container_protocol_versions:

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS, version="1.0.0")
],

Parametri chiave:

Verificare lo stato della versione

Dopo aver creato una versione, eseguire il polling fino a quando lo stato non è active, quindi richiamare l'agente. "La fornitura solitamente richiede meno di un minuto a seconda delle dimensioni dell'immagine."

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)

Valori dello stato della versione:

Richiamare l'agente

Dopo che la versione raggiunge active lo stato, usare get_openai_client per creare un client OpenAI associato all'endpoint dell'agente.

Per il protocollo Risposte :

# 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)

Per il protocollo Invocazioni, chiamare direttamente l'endpoint invocazioni:

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())

Per esempi più completi, vedere gli esempi dell'agente ospitato.

Distribuire usando l'API REST

Usare l'API REST per distribuzioni dirette basate su HTTP o durante l'integrazione con strumenti personalizzati.

Prima di iniziare, compilare ed eseguire il push dell'immagine del contenitore e configurare le autorizzazioni del registro contenitori.

Imposta variabili

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)

Creare un agente

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",
      "image": "myacr.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

La creazione di un agente crea anche la versione 1 e attiva il provisioning.

Eseguire il polling dello stato della versione

Eseguire il polling dell'endpoint della versione finché status non diventa active:

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

Richiamare l'agente

Usare l'endpoint dedicato dell'agente per inviare richieste. Impostare "stream": true per ricevere eventi inviati dal server.

Protocollo di risposte:

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
  }'

Protocollo invocazioni:

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"
  }'

Creare una nuova versione

Distribuire il codice o la configurazione aggiornati creando una nuova versione:

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",
      "image": "myacr.azurecr.io/my-agent:v2",
      "cpu": "1",
      "memory": "2Gi",
      "container_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 calcolo dell'agente viene disattivato dopo 15 minuti di inattività, quindi non ci sono costi quando l'agente non gestisce le richieste.

pulizia del CLI per sviluppatori Azure

azd down

Pulizia dell'SDK

Eliminare una singola versione:

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

In alternativa, eliminare l'intero agente e tutte le relative versioni:

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

Pulizia dell'API REST

Eliminare una singola versione:

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

In alternativa, eliminare l'intero agente:

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 informazioni dettagliate sui requisiti di controllo degli accessi in base al ruolo (RBAC) e sulla diagnosi dei problemi di autorizzazione, vedere il riferimento alle autorizzazioni dell'agente ospitato.

Passaggi successivi

Contenuti correlati

• Che cosa sono gli agenti ospitati?
• Concetti relativi all'identità dell'agente
• Pubblicare e condividere agenti
• Documentazione di Azure Container Registry