Een gehoste agent implementeren

In dit artikel wordt beschreven hoe u een containeragent implementeert in Foundry Agent Service met behulp van de Python SDK of REST API. Gebruik deze benaderingen wanneer u agentimplementaties rechtstreeks vanuit uw eigen toepassingen of services wilt beheren.

Als u voor het eerst implementeert of het snelste pad wilt, gebruikt u in plaats daarvan de quickstart: Een gehoste agent maken en implementeren . In de quickstart wordt de Azure Developer CLI (azd) of VS Code-extensie gebruikt, die automatisch omgaan met het bouwen, pushen, versiebeheer en RBAC-configuratie.

Levenscyclus van implementatie

Elke gehoste agentimplementatie volgt deze reeks:

1. Build en push — Verpak uw agentcode in een containerafbeelding en deel deze naar Azure Container Registry.
2. Maak een agentversie — registreer de afbeelding bij Foundry Agent Service. Het platform richt infrastructuur in en maakt een toegewezen Entra-agentidentiteit.
3. Status opvragen — Wacht tot de status van de versie is bereikt active.
4. Aanroepen : aanvragen verzenden naar het toegewezen eindpunt van de agent.

Voorwaarden

• Een Microsoft Foundry-project.
• Agentcode met behulp van een ondersteund framework.
• Docker Desktop geïnstalleerd voor lokale containerontwikkeling.
• Azure CLI versie 2.80 of hoger.

Vereiste machtigingen

U hebt Azure AI Project Manager nodig binnen de projectomvang om gehoste agenten te maken en te implementeren. Deze rol omvat zowel de machtigingen voor het gegevensvlak voor het maken van agents als de mogelijkheid om de rol Azure AI-gebruiker toe te wijzen aan de door het platform gemaakte agentidentiteit. De agentidentiteit heeft Azure AI-gebruiker in het project nodig om tijdens runtime toegang te krijgen tot modellen en artefacten.

Als u azd of de VS Code-extensie gebruikt, worden de meeste RBAC-toewijzingen automatisch verwerkt, waaronder:

• Container Registry Repository Reader voor de beheerde identiteit van het project (afbeelding ophalen)
• Azure AI-gebruiker voor de door het platform gemaakte agentidentiteit (runtimemodel en toegang tot hulpprogramma's)

Zie Verificatie en autorisatie voor meer informatie.

Containervereisten

Uw container-image moet aan de volgende vereisten voldoen om op het gehoste agentplatform te draaien.

Protocolbibliotheken

Gehoste agents communiceren met de Foundry-gateway via protocolbibliotheken. Kies het protocol dat overeenkomt met het interactiepatroon van uw agent:

Eén container kan beide protocollen tegelijkertijd beschikbaar maken door beide te declareren wanneer u de agent maakt, in het bestand, de agent.yaml SDK-aanroep of de REST API-aanvraag, en beide bibliotheken importeert. Gebruik de protocolbibliotheken binnen uw bestaande framework, of dat nu Microsoft Agent Framework, LangChain of aangepaste code is.

Protocolbibliotheek voor antwoorden

De Python- en .NET-bibliotheken voor het protocol Antwoorden implementeren de API voor Azure AI-antwoorden. Importeer het pakket en implementeer de IResponseHandler interface. De bibliotheek verwerkt routering, streaming met door de server verzonden gebeurtenissen (SSE), uitvoering op de achtergrond, annulering, caching en levenscyclusbeheer van reacties.

IResponseHandler

IResponseHandler is de kernabstractie die u implementeert. De bibliotheek roept voor elke binnenkomende aanvraag CreateAsync aan en levert de geretourneerde IAsyncEnumerable<ResponseStreamEvent> aan klanten via SSE:

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 beheert sequenceNumber, outputIndex, contentIndex, itemId en de volledige Response levenscyclus automatisch. Elke yield return komt één-op-één overeen met een SSE-gebeurtenis, dus u hoeft deze status niet zelf bij te houden.

Streaming- en achtergrondmodi

• Streamingmodus (standaard): SSE-gebeurtenissen worden in realtime geleverd aan de verbonden client.
• Achtergrondmodus: de handler wordt uitgevoerd tot voltooiing zonder een verbonden SSE-client. Gebeurtenissen worden gebufferd en zijn beschikbaar voor opnieuw afspelen via GET /responses/{id}.

Levenscyclus van reactie

De bibliotheek organiseert de volledige levenscyclus van reacties: created → in_progress → completed (offailed).cancelled De bibliotheek beheert ook automatisch annulerings-, foutafhandelings- en terminal gebeurtenisgaranties.

Schroefdraadveiligheid

Alle service-exemplaren, die via AddResponsesServer() zijn geregistreerd, zijn thread-safe. Handler-exemplaren hebben een bereik per aanvraag.

Zie de implementatiehandleiding voor handler voor gedetailleerde richtlijnen voor de implementatie van handler. Zie de voorbeelden van het Responses-protocol voor voorbeelden die kunnen worden uitgevoerd.

Gezondheidseindpunten

De protocolbibliotheken maken automatisch een /readiness eindpunt beschikbaar voor platformstatuscontroles. U hoeft dit zelf niet te implementeren.

Poort

Containers bedienen lokaal verkeer op poort 8088. ** In productie zorgt de Foundry gateway voor de routering—uw container hoeft geen openbare poort beschikbaar te maken.

Door platform geïnjecteerde omgevingsvariabelen

Het gehoste agentplatform injecteert automatisch omgevingsvariabelen in uw container tijdens runtime. Uw code kan deze lezen zonder ze in agent.yaml of environment_variableste declareren. Het FOUNDRY_* voorvoegsel is gereserveerd voor platformgebruik.

Declareer geen door het platform geïnjecteerde variabelen agent.yaml opnieuw. Ze worden automatisch ingesteld.

Variabelen die u zelf declareert, zoals MODEL_DEPLOYMENT_NAME MCP-eindpunten of werksets, gaan in de environment_variables sectie van agent.yaml of de SDK-aanroep create_version .

Uw agent lokaal verpakken en testen

Voordat u implementeert in Foundry, controleert u of uw agent lokaal werkt met behulp van de protocolbibliotheek. De container biedt lokaal dezelfde eindpunten als in de productieomgeving.

Het antwoordprotocol testen

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

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

Het protocol voor aanroepingen testen

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

{
    "message": "Hello!"
}

Implementeren met behulp van de Azure Developer CLI of VS Code

De Azure Developer CLI (azd) en de VS Code-extensie automatiseren de volledige levenscyclus van de implementatie. Zie de Quickstart: Een gehoste agent maken en uitrollen voor een stapsgewijze procedure.

Implementeren met behulp van de Python SDK

Gebruik de SDK wanneer u agentimplementaties rechtstreeks vanuit Python code wilt beheren.

Aanvullende vereisten

• Python 3.10 of hoger

• Een containerimage in Azure Container Registry

• De rol van Container Registry Repository Writer of AcrPush in het containerregister (om afbeeldingen te pushen)

• Azure AI Projects SDK versie 2.1.0 of hoger

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

Uw containerinstallatiekopieën bouwen en pushen

1. Bouw uw Docker-image:

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

   Zie voorbeeld-Dockerfiles voor Python en C#.

2. Pushen naar Azure Container Registry:

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

Containerregistermachtigingen configureren

Verleent de beheerde identiteit van uw project toegang tot het ophalen van afbeeldingen.

1. Ga in de Azure-portal naar je Foundry-projectresource.

2. Selecteer Identiteit en kopieer de object-id (principal) onder Toegewezen systeem.

3. Wijs de rol Lezer van containerregisteropslagplaats toe aan deze identiteit in uw containerregister. Zie Azure Container Registry rollen en machtigingen.

Een gehoste agentversie maken

Als u een versie maakt, wordt het platform geactiveerd om de agent automatisch in te richten. Er is geen afzonderlijke beginstap: het platform bouwt een momentopname van een container en maakt de agent gereed voor het verwerken van aanvragen.

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

Als u beide protocollen beschikbaar wilt maken, geeft u beide door:container_protocol_versions

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

Belangrijkste parameters:

Poll voor versiestatus

Nadat u een versie hebt gemaakt, wacht u totdat de status active is voordat u de agent activeert. Het inrichten duurt doorgaans minder dan één minuut, afhankelijk van de grootte van de afbeelding.

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)

Versiestatuswaarden:

De agent aanroepen

Nadat de versie de status active heeft bereikt, gebruikt u get_openai_client om een OpenAI-client te maken die is verbonden met het eindpunt van de agent.

Voor het protocol Antwoorden :

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

Voor het protocol Aanroepen roept u het eindpunt voor aanroepen rechtstreeks aan:

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

Voor vollediger voorbeelden, zie de voorbeelden van gehoste agents.

Implementeren met behulp van de REST API

Gebruik de REST API voor directe HTTP-implementaties of bij het integreren met aangepaste hulpprogramma's.

Voordat u begint, bouwt en uploadt u de containerafbeelding en configureert u de machtigingen van het containerregister.

Variabelen instellen

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)

Een agent maken

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

Het maken van een agent maakt ook versie 1 en activeert provisioning.

Poll voor versiestatus

Controleer het versie-eindpunt totdat statusactive:

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

De agent aanroepen

Gebruik het toegewezen eindpunt van de agent om aanvragen te verzenden. Stel "stream": true in om door de server verzonden gebeurtenissen te ontvangen.

Antwoordprotocol:

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

Protocol voor aanroepen:

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

Een nieuwe versie maken

Bijgewerkte code of configuratie implementeren door een nieuwe versie te maken:

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

Resources opschonen

Om kosten te voorkomen, ruim middelen op zodra u klaar bent. Na 15 minuten inactiviteit worden agent-compute resources opgeheven, zodat er geen kosten zijn wanneer een agent geen aanvragen verwerkt.

Azure Developer CLI opschonen

azd down

SDK opschoning

Eén versie verwijderen:

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

Of verwijder de volledige agent en alle bijbehorende versies:

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

REST API opschonen

Eén versie verwijderen:

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

Of verwijder de hele agent:

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

Probleemoplossing

Inrichtingsfouten worden weergegeven op de error.code- en error.message-velden van het versieobject. Controleer de versiestatus na het maken om problemen te identificeren.

Neem voor 5xx-fouten contact op met Microsoft ondersteuning.

Zie De referentie voor gehoste agentmachtigingen voor gedetailleerde RBAC-vereisten en het oplossen van problemen met machtigingen.

Volgende stappen

Verwante inhoud

• Wat zijn gehoste agenten?
• Concepten van agentidentiteit
• Agenttoepassingen
• Azure Container Registry documentatie