Distribuire un agente ospitato

Questo articolo illustra come distribuire un agente in contenitori nel servizio Agente Foundry usando l'SDK di Python 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 . Il quickstart utilizza l'interfaccia della riga di comando di Azure Developer CLI (azd) o l'estensione VS Code, che gestisce automaticamente la compilazione, l'invio, il controllo delle versioni e la configurazione RBAC.

Ciclo di vita della distribuzione

Ogni distribuzione dell'agente ospitato segue questa sequenza:

1. Compila e pubblica: crea il pacchetto del codice dell'agente in un'immagine container e pubblicala in Registro 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 per l'agente Entra.
3. Eseguire il polling dello stato — attendere che lo stato della versione giunga a 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

Hai bisogno di 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 Azure utente di intelligenza artificiale all'identità dell'agente creata dalla piattaforma. L'identità dell'agente deve essere Azure AI User nel progetto per accedere ai modelli e agli artefatti in fase di esecuzione.

Se si usa azd o l'estensione VS Code, lo strumento gestisce automaticamente la maggior parte delle assegnazioni RBAC, tra cui:

• Lettore del repository del Registro dei Container per l'identità gestita di progetto (estrazione immagini)
• Utente di Azure AI per l'identità dell'agente creata dalla piattaforma (modello di esecuzione e accesso agli strumenti)

Per altre informazioni, vedere Autenticazione e autorizzazione.

Requisiti dei contenitori

L'immagine del contenitore deve rispettare i seguenti requisiti per funzionare sulla piattaforma dell'agente in hosting.

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 Framework agente, 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.

Porta

I container servono traffico sulla porta 8088 localmente. Nell'ambiente di produzione, il gateway Foundry gestisce il routing: il tuo 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 poiché vengono impostate automaticamente.

Le variabili dichiarate da voi stessi, ad esempio MODEL_DEPLOYMENT_NAME o gli endpoint MCP della casella degli strumenti, si inseriscono nella sezione environment_variables di agent.yaml o nella chiamata dell'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 Azure o VS Code

L'estensione Azure Developer CLI (azd) e 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 Registro Azure Container

• Scrittore del repository del registro dei contenitori o ruolo AcrPush sul registro dei contenitori (per pushare le immagini)

• Azure AI Projects SDK versione 2.1.0 o successiva

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

Creare e inviare l'immagine del contenitore

1. Crea l'immagine Docker:

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

   Vedere i Dockerfile di esempio per Python e C#.

2. Effettuare il push su Registro Azure Container:

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

Configurare autorizzazioni del registro dei contenitori

Concedi l'accesso all'identità gestita del progetto per pullare le immagini.

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

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

3. Assegna all'identità il ruolo di Lettore del repository del Registro Container nel tuo registro contenitori. Consulta Ruoli e autorizzazioni di Registro Azure Container.

Creare una versione dell'agente ospitato

La creazione di una versione fa sì che la piattaforma esegua automaticamente il provisioning 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:

Eseguire polling dello stato della versione

Dopo aver creato una versione, eseguire il polling fino a quando lo stato non è active, prima di richiamare l'agente. L'operazione di provisioning richiede in genere meno di un minuto in base alla dimensione 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.

Configurare le 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 polling dello stato della versione

Eseguire il polling dell'endpoint della versione finché status è 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 deprovisioning dell'agente viene eseguito dopo 15 minuti di inattività, pertanto, non vi è alcun costo quando un agente non soddisfa le richieste.

pulizia della CLI per sviluppatori di 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 emergono sui 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 e sulla risoluzione dei problemi di autorizzazione, vedere il riferimento ai permessi dell'agente ospitato.

Passaggi successivi

Contenuto correlato

• Che cosa sono gli agenti ospitati?
• Concetti relativi all'identità dell'agente
• Applicazioni dell'agente
• Documentazione di Registro Azure Container