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 push hem naar Azure Container Registry.
2. Maak een agentversie — registreer de image bij Foundry Agent Service. Het platform richt infrastructuur in en maakt een toegewezen Entra-agentidentiteit.
3. Status opvragen — wacht tot de versiestatus 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 bij het projectbereik om gehoste agents 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 voor het project (image pulls)
• 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 containerimage moet voldoen aan de volgende vereisten om te draaien op het gehoste agent-platform.

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.

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 handelt de Foundry-gateway de routeringstaken af, waardoor uw container geen openbare poort beschikbaar hoeft 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 of toolbox MCP-eindpunten, gaan in de environment_variables sectie van agent.yaml of in 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 dient dezelfde eindpunten lokaal als in productie.

Het antwoordprotocol testen

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

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

Het aanroepingsprotocol 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 implementeren voor een stapsgewijze handleiding.

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 Container Registry Repository Writer of AcrPush in het containerregister (om images te pushen)

• Azure AI Projects SDK versie 2.1.0 of hoger

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

Uw containerimage bouwen en pushen

1. Bouw uw Docker-image:

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

   Zie voorbeeld-Dockerfiles voor Python en C#.

2. Naar "Azure Container Registry" uploaden:

   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 om afbeeldingen op te halen.

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, pollt u totdat de status is active ingesteld voordat u de agent aanroept. 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 aan het eindpunt van de agent is gebonden.

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 meer volledige 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 pusht u de containerafbeeldingen en configureert u de machtigingen voor 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 aan en start de inrichting.

Poll voor versiestatus

Onderzoek 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 voor het ontvangen van door de server verzonden gebeurtenissen.

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 hulpmiddelen op wanneer u klaar bent. De rekenkracht van een agent wordt na 15 minuten inactiviteit vrijgegeven, dus er zijn geen kosten wanneer een agent geen verzoeken afhandelt.

Azure Developer CLI opschonen

azd down

SDK opruimen

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 velden van het versieobject error.code en error.message. Controleer de versiestatus na het maken om problemen te identificeren.

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

Voor gedetailleerde RBAC-vereisten en het oplossen van problemen met machtigingen, zie de referentie voor gehoste agentmachtigingen.

Volgende stappen

Verwante inhoud

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