Schnellstart: Bereitstellen Ihres eigenen Codes als gehosteter Agent

Unter Bereitstellen Ihres ersten gehosteten Agents haben Sie eine Beispielanwendung bereitgestellt. In dieser Schnellstartanleitung stellen Sie Ihren eigenen Python Agent-Code im Foundry Agent Service bereit.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

• Ein Azure abonnement-Create one for free.

• Wenn Sie über ein vorhandenes Foundry-Projekt verfügen, benötigen Sie Foundry Project Manager auf Projektebene. Wenn Sie ein neues Foundry-Projekt erstellen müssen, benötigen Sie Owner eine Rolle auf Ebene der Ressourcengruppe. Die vollständige Rollenmatrix finden Sie unter Referenz zu den Berechtigungen für gehostete Agents.

• Azure Developer CLI (AZD) 1.25.3 oder höher.

• Die azd microsoft.foundry Erweiterung:

  azd ext install microsoft.foundry
  

• Ihr vorhandener Agentcode in einem lokalen Verzeichnis.

• Python 3.13 oder höher.

Ihr Projektverzeichnis sollte mindestens Folgendes enthalten:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

Wählen Sie Ihr Protokoll aus.

Wählen Sie die Registerkarte aus, die dem Interaktionsmuster Ihres Agents entspricht. Responses verwaltet den Konversationsverlauf und ist OpenAI-kompatibel. Aufrufe geben Ihnen die vollständige Kontrolle über Anforderungs- und Antwortschemas.

Schritt 1: Hinzufügen der Hostingbibliothek

Fügen Sie die Protokollbibliothek zu Ihrer requirements.txt. Die Bibliothek behandelt den HTTP-Server, Integritätsprüfungen und Protokollkonformität.

azure-ai-agentserver-responses>=1.0.0b7

azure-ai-agentserver-invocations>=1.0.0b5

Schritt 2: Hinzufügen des Hostingwrappers

Erstellen oder aktualisieren Sie main.py mit dem Hosting-Wrapper. Die Beispiele zeigen das minimale Muster – ersetzen Sie den markierten Block durch Ihre vorhandene Agentlogik.

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

Schritt 3: Initialisieren des Projekts

Führen Sie azd ai agent init aus Ihrem Agent-Quellverzeichnis aus:

azd ai agent init --protocol responses --deploy-mode code

azd ai agent init --protocol invocations --deploy-mode code

Der interaktive Ablauf fragt Folgendes ab:

• Agentname: Passen Sie den Namen an, oder akzeptieren Sie den Standardwert.
• Foundry Project: Wählen Sie Vorhandenes Foundry-Projekt verwenden oder Neues Foundry-Projekt erstellen.
• Abonnement: Wählen Sie Ihr Azure-Abonnement.
• Ort: Wählen Sie eine Azure Region aus.

Wenn Sie fertig sind, sehen Sie: KI-Agent-Definition, die Ihrem azd-Projekt erfolgreich hinzugefügt wurde!

Schritt 4: Bereitstellen Azure Ressourcen

azd provision

Dadurch werden die erforderlichen Azure Ressourcen erstellt, z. B. Application Insights.

Schritt 5: Lokal testen des Agents

azd ai agent run

Dieser Befehl erstellt eine virtuelle Umgebung, installiert Abhängigkeiten und startet Ihren Agent. Außerdem öffnet sich der Agent-Inspektor in Ihrem Browser, damit Sie mit dem Agenten chatten können.

Sie können den Befehl auch über die CLI in einem separaten Terminal ausführen:

azd ai agent invoke --local "Hello from my hosted agent"

Schritt 6: Bereitstellen im Foundry-Agentendienst

azd deploy

Wenn der Befehl abgeschlossen ist, zeigt die Ausgabe Links zum Agent-Playground und zum Agent-Endpunkt an:

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

Schritt 7: Aufrufen des bereitgestellten Agents

azd ai agent invoke "Hello from my hosted agent"

Sie sollten innerhalb weniger Sekunden eine Antwort sehen.

Bereinigen von Ressourcen

azd down

Troubleshooting

Die vollständige Berechtigungs- und Rollenzuweisungsmatrix finden Sie unter Referenz für Berechtigungen von gehosteten Agents.

Was Sie gelernt haben

In dieser Schnellstartanleitung führen Sie die folgenden Schritte aus:

• Ihrem vorhandenen Agentcode wurde eine Hostingbibliothek hinzugefügt.
• Initialisiert ein azd Projekt aus Ihrem Quellverzeichnis.
• Lokal getestet mit azd ai agent run und azd ai agent invoke --local.
• Bereitgestellt für den Foundry Agent Service mit azd deploy.

Nächste Schritte

• Erstellen Sie eine Toolbox, und verwenden Sie sie mit einem gehosteten Agent , um Tools hinter einem verwalteten Endpunkt zu kombinieren.

Verwandte Inhalte

• Was sind gehostete Agenten?
• Bereitstellen eines gehosteten Agents aus dem Quellcode
• Bereitstellen eines gehosteten Agents aus einem Container
• Lebenszyklus der Agententwicklung
• Python gehostete Agentbeispiele
• Beispiele für gehostete C#-Agent