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.

Tips

Föredrar du en Docker-mindre inre loop? Du kan också distribuera en värdbaserad agent direkt från källkoden (förhandsversion) – ladda upp en .zip av din Python eller .NET kod och plattformen bygger och är värd för den åt dig.

Distributionslivscykel

Varje distribution av värdbaserad agent 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

Nödvändiga behörigheter

Du behöver Foundry Project Manager på projektnivå för att skapa och distribuera hostade agenter. Den här rollen omfattar både behörigheterna för dataplanet för att skapa agenter och möjligheten att tilldela rollen Foundry-användare till den plattformsskapade agentidentiteten. Agentidentiteten behöver Foundry-användare i projektet för att få åtkomst till modeller och artefakter vid körning.

Viktigt

Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

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)
  • Foundry-användare för den plattformsskapade agentidentiteten (körningsmodell och verktygsåtkomst)

Observera

  • Plattformen skapar en dedikerad Entra-agentidentitet för varje värdbaserad agent vid distributionstillfället. Den här identiteten är ett tjänstehuvudnamn som din körande container använder för att anropa modeller och verktyg. Du behöver inte konfigurera hanterade identiteter manuellt. Dock måste användaren som skapar agenten ha behörighet att ge den identiteten rollen Foundry User – vilket är anledningen till att Foundry Project Manager rekommenderas framför enbart Foundry User.
  • Medan azd och VS Code-tillägg hanterar grundläggande RBAC-tilldelningar automatiskt, kan komplexa scenarier kräva ytterligare manuell konfiguration. Omfattande information om alla behörigheter och rolltilldelningar finns i Referens för värdbaserade agentbehörigheter.

Mer information finns i Autentisering och auktorisering.

Viktigt

Azure Container Registry-instansen som innehåller containeravbildningen för din värdbaserade agent måste för närvarande kunna nås via sin offentliga slutpunkt. Att placera registret bakom ett privat nätverk (privat slutpunkt med åtkomst till offentligt nätverk inaktiverat) stöds inte för närvarande för värdbaserade agenter – plattformen kan inte hämta avbildningen. En fullständig lista över nätverksbegränsningar finns i Begränsningar.

Containerkrav

Din containeravbild måste uppfylla följande krav för att kunna köras på Hosted agent-plattformen.

Viktigt

Värdplattformen kräver x86_64 (linux/amd64) containeravbildningar. Om du bygger på Apple Silicon eller andra ARM-baserade datorer kan du använda docker build --platform linux/amd64 . för att undvika att skapa en inkompatibel ARM-avbildning.

Protokollbibliotek

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

Protokollet Python bibliotek .NET bibliotek Slutpunkt Bäst för
Svaren azure-ai-agentserver-responses Azure.AI.AgentServer.Responses /responses Konversationschattrobotar, strömning, multi-turn med plattformshanterad historik
Anrop azure-ai-agentserver-invocations Azure.AI.AgentServer.Invocations /invocations Webhook-mottagare, icke-konversationsbearbetning, anpassade asynkrona arbetsflöden
Anrop (WebSocket) azure-ai-agentserver-invocations Azure.AI.AgentServer.Invocations /invocations_ws Dubbelriktad direktuppspelning: röstagenter i realtid, interaktiva medier

WebSocket-protokollet använder identifieraren invocations_ws och levereras i samma azure-ai-agentserver-invocations paket som HTTP-vägen /invocations , så att en container kan hantera båda. Använd den när du behöver beständig direktuppspelning med full duplex– till exempel genom att skicka mikrofon-PCM till agenten och ta emot syntetiserat ljud tillbaka. För röstscenarier, se Skapa en röstagent med värdbaserade agenter.

Viktigt

invocations_ws WebSocket-protokollet är i förhandsversion och är för närvarande endast tillgängligt i USA, norra centrala.

En enda container kan exponera flera protokoll samtidigt genom att deklarera dem när du skapar agenten – i filen, SDK-anropet agent.yaml eller REST API-begäran – och importera de bibliotek som krävs. 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

Plattformen för värdbaserade agenter injicerar automatiskt miljövariabler i din container under 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.

Variabel Syfte
FOUNDRY_PROJECT_ENDPOINT Endpoint-URL för Foundry-projekt
FOUNDRY_PROJECT_ARM_ID Gjuteriprojektet – ARM-resurs-ID
FOUNDRY_AGENT_NAME Namn på den körande agenten
FOUNDRY_AGENT_VERSION Version av agenten som körs
FOUNDRY_AGENT_SESSION_ID Sessions-ID för den aktuella begäran (endast värdbaserade containrar)
APPLICATIONINSIGHTS_CONNECTION_STRING Telemetri-anslutningssträng för Application Insights

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.

Viktigt

När du distribuerar din värdbaserade agent till Foundry Agent Service matar plattformen automatiskt in en Application Insights-reťazec pripojenia i din agentcontainer som en miljövariabel, vilket aktiverar OpenTelemetry-spårning som standard. Om du vill visa distribuerade spårningar, begäranden och beroenden öppnar du Application Insights-resursen som etablerades under installationen i Azure-portalen och går till Undersök > transaktionssökning eller prestanda. Använd azd ai agent monitor för livekonsol-loggar. När AppInsights är aktiverat loggar det här projektet spårningar för att övervaka och utvärdera interaktioner på användarnivå med agenter. Projektmedlemmar som tilldelats rollen Log Analytics Reader i AppInsights kan visa spårningsdata, som kan innehålla personuppgifter och/eller Kundinnehåll. Granska vilka spårningsdata som samlas in och vem som kan visa och använda dessa data. Ytterligare Azure Montior App Insights-priser kan gälla. Läs mer.

Referera till projektanslutningar i miljövariabler

I stället för att hårdkoda hemligheter (API-nycklar, token, slutpunkter) till agent.yaml eller din bild kan du hämta dem från en Foundry-projektanslutning vid sandbox-start. Alla värden i environment_variables kan vara ett platshållaruttryck som plattformen löser innan containern startar.

Syntax för platshållare

En platshållare har formen ${{connections.<name>.<path>}}, där <name> är anslutningens resursnamn (visas i portalen under Projektinformation>Anslutna resurser) och <path> är ett av följande:

Sökväg Löser till
credentials.<field> Ett hemligt fält på anslutningen
target Anslutningens egenskap (till exempel en slutpunkts-URL target )
metadata.<field> Ett fält under anslutningen metadata

Vilket fältnamn som ska användas beror på anslutningskategorin:

Anslutningskategori Fältnamn i platshållaren
ApiKey, AppInsights Always key– till exempel credentials.key
CustomKeys Det nyckelnamn som du angav när du skapade anslutningen, till exempel credentials.github_token

Example

Skapa först en CustomKeys anslutning för projektet som innehåller hemligheten. Se Lägg till en ny anslutning i Microsoft Foundry. Referera sedan till den från agent.yaml:

environment_variables:
  - name: MODEL_DEPLOYMENT_NAME
    value: gpt-5-mini
  - name: GITHUB_TOKEN
    value: ${{connections.agent-secrets.credentials.github_token}}

Vid sandbox-start löser Foundry platshållaren och matar in det lösta värdet som en vanlig miljövariabel. Din kod läser den precis som vilken annan miljövariabel som helst:

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

En GET på agentversionen returnerar literaltexten ${{...}} – den lösta hemligheten upprepas aldrig via hanterings-API:et.

Considerations

  • Skapa anslutningen innan du distribuerar versionen. Om anslutningen eller det refererade fältet saknas vid sandbox-start löses inte platshållaren och variabeln är tom.
  • Hemligheter är skrivskyddade. GET för en anslutning returnerar credentials: null. Kontrollera lösningen genom att läsa env var inifrån containern som körs, inte genom att inspektera anslutningen.
  • Anteckna CustomKeys fältnamn själv. Hanterings-API:t returnerar dem aldrig efter att de har skapats. Behåll dem intill agentens källfiler (till exempel i IaC-mallar eller tillsammans med agent.yaml) så att du senare kan konstruera platshållare utan att behöva gissa.
  • Foundry hanterar namnet på den underliggande hemligheten. När du skapar anslutningen lagrar Foundry värdet i Key Vault under ett namn som det väljer – du kan inte referera till en befintlig Key Vault hemlighet efter namn. Om du vill ansluta ditt eget Key Vault som bakomliggande lagringsplats, se Konfigurera en anslutning till Key Vault.

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.

För att granska uppmaningar och svar mot en policy för innehållssäkerhet lägger du till ett skyddsräcke för innehållssäkerhet i din 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

Tips

Använd unika avbildningstaggar istället för :latest i reproducerbara distribueringar.

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, 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=AgentProtocol.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}")

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

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

Nyckelparametrar:

Parameter Beskrivning
agent_name Unikt namn (alfanumeriskt med bindestreck, högst 63 tecken)
container_configuration.image Fullständig URL för Azure Container Registry-avbild med tagg
cpu CPU-allokering (till exempel "1")
memory Minnesallokering (till exempel "2Gi")
protocol_versions Protokoll som containern exponerar (responses, invocationseller båda)

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:

Status Beskrivning
creating Infrastrukturetablering pågår
active Agenten är redo att hantera begäranden
failed Provisioneringen misslyckades – kontrollera fältet error för detaljer
deleting Versionen håller på att rensas upp
deleted Versionen har tagits bort helt

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ärdbaserad agent.

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

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

Om du vill skärma uppmaningar och svar mot en innehållssäkerhetsprincip inkluderar du ett rai_config objekt i definition. Se Lägga till ett skyddsräcke för innehåll till en värdbaserad agent.

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

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"

Varning

Om du tar bort en agent tas alla dess versioner bort och aktiva sessioner avslutas. Det går inte att ångra den här åtgärden.

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.

Felkod HTTP-kod Lösning
image_pull_failed 400 Verifiera avbildningens URI. Bekräfta att den projekthanterade identiteten har Container Registry Repository Reader på ACR och att registrets azureADAuthenticationAsArmPolicy principstatus är enabled
SubscriptionIsNotRegistered 400 Registrera prenumerationsprovidern
InvalidAcrPullCredentials 401 Åtgärda hanterad identitet eller registeret-RBAC
UnauthorizedAcrPull 403 Ange rätt autentiseringsuppgifter eller identitet
AcrImageNotFound 404 Korrigera bildnamn/tagg eller publicera bild
RegistryNotFound 400/404 Åtgärda register-DNS eller nätverkstillgänglighet

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

Hantera värdbaserad agentlivscykel

Relaterat innehåll

  • Last updated on