Bereitstellen eines gehosteten Agents

In diesem Artikel erfahren Sie, wie Sie einen containerisierten Agenten im Foundry Agent Service mithilfe der Azure Developer CLI (azd), des Python SDK oder der REST-API bereitstellen. Wählen Sie eine Bereitstellungsmethode mithilfe der Auswahl oben im Artikel aus. Verwenden Sie die SDK- oder REST-Ansätze, wenn Sie Agent-Bereitstellungen direkt aus Ihren eigenen Anwendungen oder Diensten verwalten möchten.

Wenn Sie erstmals bereitstellen oder eine Schritt-für-Schritt-Anleitung wünschen, lesen Sie den Schnellstart: Erstellen und Bereitstellen eines gehosteten Agent. Die Azure Developer CLI (azd) und VS Code-Erweiterung übernehmen automatisch das Erstellen, Pushen, Versionieren und die RBAC-Konfiguration.

Bereitstellungslebenszyklus

Jede Bereitstellung des gehosteten Agents folgt dieser Sequenz:

1. Erstellen und pushen – Packen Sie Ihren Agentcode in ein Containerimage, und übertragen Sie ihn an Azure Container Registry.
2. Erstellen Sie eine Agentversion – Registrieren Sie das Image beim Foundry Agent Service. Die Plattform stellt Infrastruktur bereit und erstellt eine dedizierte Entra-Agent-Identität.
3. Status abfragen – Warten Sie, bis der Versionsstatus active erreicht.
4. Invoke – Senden von Anforderungen an den dedizierten Endpunkt des Agents.

Voraussetzungen

• Ein Microsoft Foundry-Projekt.
• Agentcode mit einem unterstützten Framework.
• Docker Desktop für die entwicklung lokaler Container installiert.
• Azure CLI Version 2.80 oder höher.

Erforderliche Berechtigungen

Sie benötigen auf Projektebene die Rolle Foundry Project Manager, um einen gehosteten Agenten bereitzustellen. Diese Rolle gewährt Berechtigungen auf der Datenebene zum Erstellen und Aktualisieren von Agenten sowie bei Bedarf die Möglichkeit, Rollenzuweisungen für die von der Plattform erstellte Agent-Identität zu erstellen. Eine detaillierte Aufschlüsselung der beteiligten Berechtigungen finden Sie in der Referenz für Berechtigungen gehosteter Agents.

Die Plattform erstellt bei der Bereitstellung für jeden gehosteten Agent eine dedizierte Microsoft Entra Agent-Identität. Diese Identität ist ein Dienstprinzipal, den Ihr ausgeführter Container zum Aufrufen von Modellen und Tools verwendet. Sie müssen verwaltete Identitäten nicht manuell konfigurieren. Die Agent-Identität kann standardmäßig über den Projektendpunkt und den Sitzungsspeicher auf Modellinferenz zugreifen. Weisen Sie für externe Ressourcen (z. B. Ihre eigene Azure Storage) RBAC-Rollen manuell dem Microsoft Entra ID des Agents zu. Weitere Informationen finden Sie unter Agentzugriff über die Standardeinstellungen hinaus.

Wenn Sie azd oder die VS Code-Erweiterung verwenden, übernimmt das Tooling die meisten RBAC-Zuweisungen automatisch, einschließlich Container Registry Repository Reader für die verwaltete Identität des Projekts (Abrufen von Images).

Weitere Informationen finden Sie unter Authentifizierung und Autorisierung.

Containeranforderungen

Ihr Container-Image muss die folgenden Anforderungen erfüllen, um auf der Hosted-Agent-Plattform ausgeführt werden zu können.

Protokollbibliotheken

Gehostete Agents kommunizieren mit dem Foundry-Gateway über Protokollbibliotheken. Wählen Sie das Protokoll aus, das dem Interaktionsmuster Ihres Agents entspricht:

Das WebSocket-Protokoll verwendet den Bezeichner invocations_ws und wird im selben azure-ai-agentserver-invocations Paket wie die HTTP-Route /invocations ausgeliefert, sodass ein Container beides bedienen kann. Verwenden Sie es, wenn Sie persistentes Vollduplex-Streaming benötigen, z. B. um Mikrofon-PCM an den Agenten zu senden und synthetisierte Audiodaten zurückzuerhalten. Informationen zu VoIP-Szenarien finden Sie unter Erstellen eines VoIP-Agents mit gehosteten Agents.

Ein einzelner Container kann mehrere Protokolle gleichzeitig verfügbar machen, indem sie deklariert werden, wenn Sie den Agent – im protocols Feld des azure.ai.agent Diensts in , einem azure.yamlSDK-Aufruf oder einer REST-API-Anforderung – erstellen und die erforderlichen Bibliotheken importieren. Verwenden Sie die Protokollbibliotheken in Ihrem vorhandenen Framework, unabhängig davon, ob es sich um Microsoft Agent Framework, LangChain oder benutzerdefinierten Code handelt.

Antwortprotokollbibliothek

Die Python- und .NET bibliotheken für das Antwortprotokoll implementieren die AZURE AI-Antwort-API. Importieren Sie das Paket, und implementieren Sie die IResponseHandler Schnittstelle. Die Bibliothek verarbeitet Routing, Streaming mit servergesendeten Ereignissen (SSE), Hintergrundausführung, Abbruch, Zwischenspeichern und Reaktionslebenszyklusverwaltung.

IResponseHandler

IResponseHandler ist die Kernstraktion, die Sie implementieren. Die Bibliothek ruft für jede eingehende Anforderung CreateAsync auf und übermittelt die zurückgegebenen IAsyncEnumerable<ResponseStreamEvent> über SSE an die Clients.

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 verwaltet sequenceNumber, outputIndex, contentIndex, itemId und den vollständigen Lebenszyklus von Response automatisch. Jedes yield return stimmt eins zu eins mit einem SSE-Ereignis überein, sodass Sie diesen Zustand nicht selbst nachverfolgen müssen.

Streaming- und Hintergrundmodi

• Streamingmodus (Standard): SSE-Ereignisse werden in Echtzeit an den verbundenen Client übermittelt.
• Hintergrundmodus: Der Handler läuft bis zum Abschluss, auch ohne einen verbundenen SSE-Client. Ereignisse werden gepuffert und stehen für die Wiedergabe über GET /responses/{id}.

Antwortlebenszyklus

Die Bibliothek koordiniert den vollständigen Antwortlebenszyklus: created - ->in_progress>completed (oder ).failedcancelled Die Bibliothek verwaltet auch die Abbruch-, Fehlerbehandlungs- und Terminalereignisgarantien automatisch.

Threadsicherheit

Alle Dienstinstanzen, die über AddResponsesServer() registriert wurden, sind threadsicher. Handler-Instanzen sind im Kontext einer Anforderung definiert.

Ausführliche Anleitungen zur Implementierung von Handlern finden Sie im Handlerimplementierungshandbuch. Für ausführbare Beispiele siehe die Responses-Protokollbeispiele.

Gesundheitsendpunkte

Die Protokollbibliotheken machen automatisch einen /readiness Endpunkt für Plattformintegritätsprüfungen verfügbar. Sie müssen dies nicht selbst implementieren.

Hafen

Container bedienen lokal den Datenverkehr auf Port 8088. Im Produktivbetrieb übernimmt das Foundry-Gateway das Routing – Ihr Container muss keinen öffentlichen Port freigeben.

Plattforminjizierte Umgebungsvariablen

Die Plattform des gehosteten Agents fügt Umgebungsvariablen automatisch zur Laufzeit in Ihren Container ein. Ihr Code kann diese Variablen lesen, ohne sie in der env Zuordnung des azure.ai.agent Diensts in azure.yaml oder in den Einstellungen der SDK- und REST-Umgebungsvariablen zu deklarieren. Das FOUNDRY_* Präfix ist für die Plattformverwendung reserviert.

Deklarieren Sie in azure.yaml keine von der Plattform eingefügten Variablen erneut – sie werden automatisch gesetzt.

Variablen, die Sie selbst deklarieren, wie MODEL_DEPLOYMENT_NAME oder Toolbox-MCP-Endpunkte, gehören in die env-Map des azure.ai.agent-Dienstes in azure.yaml oder in den SDK-Aufruf create_version.

Verweisen auf Projektverbindungen in Umgebungsvariablen

Anstatt Geheimnisse (API-Schlüssel, Token, Endpunkte) fest in azure.yaml oder Ihr Image einzucodieren, beziehen Sie sie beim Start der Sandbox aus einer Foundry-Projektverbindung. Jeder Wert, den Sie als Umgebungsvariable deklarieren, kann ein Platzhalterausdruck sein, der von der Plattform aufgelöst wird, bevor der Container gestartet wird.

Platzhaltersyntax

Ein Platzhalter weist das Formular ${{connections.<name>.<path>}} auf, wobei <name> der Ressourcenname der Verbindung ist (im Portal unter Project Details sichtbar>Verbindete Ressourcen) und <path> ist eine der folgenden:

Der zu verwendende Feldname hängt von der Verbindungskategorie ab:

Beispiel

Erstellen Sie zunächst eine CustomKeys Verbindung für das Projekt, die den geheimen Schlüssel enthält. Siehe Eine neue Verbindung in Microsoft Foundry hinzufügen. Anschließend kann man in der env-Karte im azure.ai.agent-Dienst in azure.yaml darauf zugreifen:

services:
  my-agent:
    host: azure.ai.agent
    env:
      MODEL_DEPLOYMENT_NAME: gpt-5-mini
      GITHUB_TOKEN: ${{connections.agent-secrets.credentials.github_token}}

Im Sandkastenstart löst Foundry den Platzhalter auf und fügt den aufgelösten Wert als einfache Umgebungsvariable ein. Ihr Code liest ihn wie jeder andere env var:

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

Ein GET für die Agentversion gibt den Literaltext ${{...}} zurück– der aufgelöste geheime Schlüssel wird niemals über die Verwaltungs-API zurückgegeben.

Considerations

• Erstellen Sie die Verbindung, bevor Sie die Version bereitstellen. Wenn die Verbindung oder das referenzierte Feld beim Sandkastenstart fehlt, wird der Platzhalter nicht aufgelöst, und die Variable ist leer.
• Geheimnisse können nur geschrieben werden. GET für eine Verbindung gibt zurück credentials: null. Überprüfen Sie die korrekte Auflösung, indem Sie die Umgebungsvariable innerhalb Ihres laufenden Containers auslesen, nicht durch Überprüfen der Verbindung.
• Notieren Sie Feldnamen CustomKeys selbst. Die Verwaltungs-API gibt sie nach der Erstellung nie wieder zurück. Bewahren Sie sie direkt bei Ihrer Agent-Quelle auf (z. B. in IaC-Vorlagen oder neben azure.yaml), damit Sie später Platzhalter anlegen können, ohne raten zu müssen.
• Foundry verwaltet den zugrunde stehenden geheimen Namen. Wenn Sie die Verbindung erstellen, speichert Foundry den Wert in Key Vault unter einem von ihr ausgewählten Namen – Sie können nicht auf ein bereits vorhandenes Key Vault Geheimnis anhand des Namens verweisen. Informationen dazu, wie Sie Ihren eigenen Key Vault als zugrunde liegenden Speicher einbinden, finden Sie unter Set up a Key Vault connection.

Paketieren und testen Sie Ihren Agenten lokal

Überprüfen Sie vor der Bereitstellung in Foundry, ob Ihr Agent lokal mithilfe der Protokollbibliothek funktioniert. Der Container dient denselben Endpunkten lokal wie in der Produktion.

Testen des Antwortprotokolls

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

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

Das Aufrufprotokoll testen

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

{
    "message": "Hello!"
}

azd up

azd deploy

azd ai agent show

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentEndpointProtocol, 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=AgentEndpointProtocol.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}")

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

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)

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

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

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)

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

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

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

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

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

Bereinigen von Ressourcen

Um Gebühren zu vermeiden, bereinigen Sie Ressourcen, nachdem Sie fertig sind. Agenten-Berechnung wird nach 15 Minuten Inaktivität abgebaut, wodurch keine Kosten anfallen, wenn ein Agent keine Anforderungen bedient.

azd down

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

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

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

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

Problembehandlung

Bereitstellungsfehler werden auf den error.code und error.message Feldern des Versionsobjekts angezeigt. Überprüfen Sie den Versionsstatus nach der Erstellung, um Probleme zu identifizieren.

Wenden Sie sich für 5xx-Fehler an Microsoft Support.

Detaillierte RBAC-Anforderungen und Berechtigungsprobleme finden Sie unter der Referenz zu Berechtigungen für gehostete Agenten.

Nächste Schritte

Verwandte Inhalte

• Was sind gehostete Agents?
• Fügen Sie einem gehosteten Agenten eine Schutzmaßnahme für die Inhaltssicherheit hinzu
• Agentidentitätskonzepte
• Agentanwendungen

• Azure Container Registry-Dokumentation