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 projektomfattning för att skapa och distribuera värdbaserade agenter. 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 plattformsskapade agentidentiteten (runtime-modell och verktygsåtkomst)

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.

Protokollbibliotek för svar

Biblioteken Python och .NET för protokollet Svar implementerar API:et Azure AI-svar. Importera paketet och implementera IResponseHandler gränssnittet. Biblioteket hanterar routning, strömning med serverutskickade händelser (SSE), bakgrundskörning, annullering, cachelagring och livscykelhantering för svar.

IResponseHandler

IResponseHandler är den kärnabstraktion som du implementerar. Biblioteket anropar CreateAsync för varje inkommande begäran och levererar via SSE de returnerade IAsyncEnumerable<ResponseStreamEvent> till klienterna.

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 sequenceNumber hanterar outputIndex, contentIndex, itemId och hela Response livscykeln automatiskt. Varje yield return mappar en-till-en till en SSE-händelse, så du behöver inte själv spåra detta tillstånd.

Strömnings- och bakgrundslägen

• Strömningsläge (standard): SSE-händelser levereras i realtid till den anslutna klienten.
• Bakgrundsläge: Hanteraren körs till slutförande utan en ansluten SSE-klient. Händelser är buffrade samt tillgängliga för uppspelning via GET /responses/{id}.

Svarslivscykel

Biblioteket samordnar hela svarslivscykeln: created → in_progress → completed (eller failed eller cancelled). Biblioteket hanterar även annullering, felhantering och terminalhändelsegarantier automatiskt.

Trådsäkerhet

Alla tjänstinstanser som registreras via AddResponsesServer() är trådsäkra. Handlerinstanser är avgränsade per begäran.

Detaljerade riktlinjer för hanteringsimplementering finns i implementeringsguiden för handler. Körbara exempel finns i protokollexemplen Responses.

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 produktion 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 deklarerar själv, till exempel MODEL_DEPLOYMENT_NAME eller slutpunkter för MCP i verktygslådan, kommer in i environment_variables-sektionen av agent.yaml eller SDK-create_version-anropet.

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 svarprotokollet

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"
  

Skapa och push-överföra containeravbildningen

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 för 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 att tillhandahålla agenten automatiskt. 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, kontrollera regelbundet tills statusen är active innan du anropar agenten. Konfigureringen 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())

För mer fullständiga exempel, se exemplen på värdbaserade agenter.

Distribuera med REST API:et

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

Innan du börjar skapar och skickar 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 provisionering initieras.

Sök efter versionsstatus

Kontrollera versionsslutpunkten 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 resurser frigörs 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ältet. 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