Distribuera en värdbaserad agent

Den här artikeln visar hur du distribuerar en containerbaserad agent till Foundry Agent Service med hjälp av Python SDK eller REST API. Använd dessa metoder när du vill hantera agentdistributioner direkt från dina egna program eller tjänster.

Om du distribuerar för första gången eller vill ha den snabbaste sökvägen använder du snabbstarten: Skapa och distribuera en värdbaserad agent i stället. I snabbstarten används Azure Developer CLI (azd) eller VS Code-tillägget, som hanterar konfiguration av skapande, push-överföring, versionshantering och RBAC automatiskt.

Distributionslivscykel

Varje värdbaserad agentdistribution följer den här sekvensen:

1. Build och push – Paketera agentkoden i en containeravbildning och skicka den till Azure Container Registry.
2. Skapa en agentversion – Registrera avbildningen med Foundry Agent Service. Plattformen etablerar infrastrukturen och skapar en dedikerad Entra-agentidentitet.
3. Sök efter status – Vänta tills versionsstatusen har nått active.
4. Invoke – Skicka begäranden till agentens dedikerade slutpunkt.

Förutsättningar

• Ett Microsoft Foundry-projekt.
• Agentkod med ett ramverk som stöds.
• Docker Desktop installerat för utveckling av lokala containrar.
• Azure CLI version 2.80 eller senare.

Nödvändiga behörigheter

Du behöver Azure AI Project Manager vid projektets omfattning för att skapa och distribuera värdtjänstagenter. Den här rollen omfattar både behörigheter för dataplanet för att skapa agenter och möjligheten att tilldela Azure AI-användare roll till den plattformsskapade agentidentiteten. Agentidentiteten behöver Azure AI-användare i projektet för att få åtkomst till modeller och artefakter under körning.

Om du använder azd eller VS Code-tillägget hanterar verktygen de flesta RBAC-tilldelningar automatiskt, inklusive:

• Container Registry Repository Reader för hanterad projektidentitet (bildhämtningar)
• Azure AI User för den av plattformen skapade agentidentiteten (körningsmiljömodell och åtkomst till verktyg)

Mer information finns i Autentisering och auktorisering.

Containerkrav

Containeravbildningen måste uppfylla följande krav för att köras på den värdbaserade agentplattformen.

Protokollbibliotek

Värdbaserade agenter kommunicerar med Foundry-gatewayen via protokollbibliotek. Välj det protokoll som matchar agentens interaktionsmönster:

En enda container kan exponera båda protokollen samtidigt genom att deklarera både när du skapar agenten – i filen, SDK-anropet agent.yaml eller REST API-begäran – och genom att importera båda biblioteken. Använd protokollbiblioteken inom ditt befintliga ramverk, oavsett om det är Microsoft Agent Framework, LangChain eller anpassad kod.

Hälsoslutpunkter

Protokollbiblioteken exponerar automatiskt en /readiness slutpunkt för plattformshälsokontroller. Du behöver inte implementera detta själv.

Port

Containrar hanterar trafik på port 8088 lokalt. I produktionsmiljöer hanterar Foundry-gatewayen routning – containern behöver inte exponera en offentlig port.

Plattformsinmatade miljövariabler

Den värdbaserade agentplattformen matar automatiskt in miljövariabler i containern vid körning. Koden kan läsa dessa utan att deklarera dem i agent.yaml eller environment_variables. Prefixet FOUNDRY_* är reserverat för plattformsanvändning.

Omdeklarera inte plattformsinmatade variabler i agent.yaml – de anges automatiskt.

Variabler som du själv deklarerar, till exempel MODEL_DEPLOYMENT_NAME eller MCP-slutpunkter i verktygslådan, placeras i environment_variables-delen av agent.yaml eller i SDK-anropet create_version.

Paketera och testa din agent lokalt

Innan du distribuerar till Foundry kontrollerar du att agenten fungerar lokalt med hjälp av protokollbiblioteket. Containern hanterar samma slutpunkter lokalt som i produktion.

Testa Responses-protokollet

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

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

Testa anropsprotokollet

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

{
    "message": "Hello!"
}

Distribuera med hjälp av Azure Developer CLI eller VS Code

AZURE Developer CLI (azd) och VS Code-tillägget automatiserar hela distributionslivscykeln. En stegvis genomgång finns i Snabbstart: Skapa och distribuera en värdbaserad agent.

Distribuera med hjälp av Python SDK

Använd SDK när du vill hantera agentdistributioner direkt från Python kod.

Ytterligare förutsättningar

• Python 3.10 eller senare

• En containeravbildning i Azure Container Registry

• Container Registry Repository Writer eller AcrPush-rollen i containerregistret (för att skicka avbildningar)

• Azure AI Projects SDK version 2.1.0 eller senare

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

Bygg och pusha din containerbild

1. Skapa docker-avbildningen:

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

   Se Dockerfiles-exempel för Python och C#.

2. Push-överför till Azure Container Registry:

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

Konfigurera behörigheter för containerregister

Ge projektets hanterade identitet åtkomst till att hämta bilder:

1. I Azure-portalen går du till din Foundry-projektresurs.

2. Välj Identitet och kopiera objekt-ID (huvudnamn) under Systemtilldelad.

3. Tilldela rollen Container Registry Repository Reader till den här identiteten i containerregistret. Se Azure Container Registry roller och behörigheter.

Skapa en värdbaserad agentversion

När du skapar en version initierar plattformen automatiskt förberedelserna för agenten. Det finns inget separat startsteg – plattformen skapar en ögonblicksbild av containern och gör agenten redo att hantera begäranden.

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

Om du vill exponera båda protokollen skickar du båda i container_protocol_versions:

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

Nyckelparametrar:

Sök efter versionsstatus

När du har skapat en version kontrollerar du kontinuerligt tills statusen är active innan du anropar agenten. Etableringen tar vanligtvis mindre än en minut beroende på bildstorleken.

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)

Versionsstatusvärden:

Anropa agenten

När versionen har nått active status använder du get_openai_client för att skapa en OpenAI-klient som är bunden till agentens slutpunkt.

För protokollet Svar :

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

För protokollet Anrop anropar du slutpunkten för anrop direkt:

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

Mer fullständiga exempel finns i exemplen på värdbaserade agenter.

Distribuera med REST-API

Använd REST-API:et för direkta HTTP-baserade distributioner eller när du integrerar med anpassade verktyg.

Innan du börjar bygger och pushar din containerbild och konfigurerar behörigheter för containerregistret.

Konfigurera variabler

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)

Skapa en agent

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

När du skapar en agent skapas även version 1 och provisioning initieras.

Sök efter versionsstatus

Fråga versionsändpunkten tills status är 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

Anropa agenten

Använd agentens dedikerade slutpunkt för att skicka begäranden. Ange "stream": true för att ta emot server-skickade händelser.

Svarsprotokoll:

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

Anropsprotokoll:

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

Skapa en ny version

Distribuera uppdaterad kod eller konfiguration genom att skapa en ny version:

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

Rensa resurser

Rensa resurser när du är klar för att förhindra avgifter. Agentens datorkapacitet avmonteras efter 15 minuters inaktivitet, så det kostar ingenting när en agent inte hanterar förfrågningar.

Azure CLI-rensning för utvecklare

azd down

SDK-rensning

Ta bort en enskild version:

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

Eller ta bort hela agenten och alla dess versioner:

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

REST API-rensning

Ta bort en enskild version:

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

Eller ta bort hela agenten:

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

Felsökning

Etableringsfel visas på versionsobjektets error.code och error.message fält. Kontrollera versionsstatusen när du har skapat den för att identifiera problem.

Kontakta supporten för Microsoft för 5xx-fel.

Detaljerade RBAC-krav och behörighetsfelsökning finns i Referens för värdbaserade agentbehörigheter.

Nästa steg

Relaterat innehåll

• Vad är värdbaserade agenter?
• Agentidentitetsbegrepp
• Agentapplikationer
• Azure Container Registry dokumentation