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 oder .NET (C#)-Agentcode im Foundry Agent Service bereit. Ihr Code kann ein beliebiges Agentframework verwenden, z. B. Microsoft Agent Framework, LangGraph, das GitHub Copilot SDK oder das OpenAI Agents SDK oder nur Code, der ein Modell direkt aufruft.

Jeder Codeschritt enthält Registerkarten für Ihre Sprache und Ihr Protokoll. Wählen Sie in jedem Schritt dieselbe Kombination wie C# (Antworten) aus.

Wenn Sie einen Codierungs-Agent wie GitHub Copilot verwenden, kann die Microsoft Foundry Skill die Schnellstartanleitung an Ihre eigene Codebasis anpassen und die richtigen azd Bereitstellungsschritte ausführen.

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 die Rolle Owner im Bereich Ressourcengruppe. Die vollständige Rollenmatrix finden Sie unter Referenz zu den Berechtigungen für gehostete Agents.

• Azure Developer CLI (azd) 1.27.1 oder höher.

• Die azd microsoft.foundry Erweiterung:

  azd ext install microsoft.foundry
  

• Eine authentifizierte azd Sitzung:

  azd auth login
  

• Ihr vorhandener Agentcode in einem lokalen Verzeichnis.

• Für den Python Pfad Python 3.13 oder höher.

• Für den C#-Pfad ist das .NET 10 SDK oder höher erforderlich.

• (Optional) Um mit einem Beispiel in Visual Studio Code zu beginnen, installieren Sie Visual Studio Code und das Microsoft Foundry Toolkit für Visual Studio Code.

Ihr Projektverzeichnis sollte mindestens für Python folgendes enthalten:

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

Oder für C# ein .NET Webprojekt:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

Wählen Sie Ihr Framework

Die in Schritt 1 hinzugefügte Hostingbibliothek behandelt das Protokoll – den HTTP-Server, Integritätsprüfungen und Anforderungs- und Antwortschemas. Es hängt nicht von einem bestimmten Agentframework ab, sodass Ihre Agentlogik alle von Ihnen gewünschten Pakete in Python oder C# verwenden kann.

Um ein Framework zu verwenden, fügen Sie die Pakete neben der Hostingbibliothek hinzu, und rufen Sie dann das Framework aus dem Handler auf. In der folgenden Tabelle sind allgemeine Auswahlmöglichkeiten und jeweils ein Python Beispiel aufgeführt.

Rahmen	Pakete, die zu requirements.txt hinzugefügt werden sollen	Beispiel
Einfache Python (direktes Aufrufen eines Modells)	azure-ai-projects	Hello-World
LangGraph	langgraph, langchain-azure-ai	langgraph-chat
GitHub Copilot SDK	github-copilot-sdk	github-copilot
OpenAI Agents SDK	openai-agents	openai-agents-sdk

Das requirements.txt jedes Beispiels führt die genauen Paketversionen auf. Eine vollständige Sammlung der Bring-your-own-Beispiele finden Sie im Ordner mit den Python-Beispielen.

Fügen Sie für C# Ihrer Projektdatei neben dem Hosting-Paket Framework-Pakete hinzu, und rufen Sie dann das Framework im Handler in Program.cs auf. Die vollständigen C#-Beispiele finden Sie im C#-Ordner mit eigenen Beispielen.

Note

Microsoft Agent Framework verfügt über eine integrierte Hostingintegration, die ein eigenes Paket verwendet. Informationen zum Bereitstellen eines Microsoft Agent Framework-Agents finden Sie unter Bereitstellen Ihres ersten gehosteten Agents.

Beginnen Sie mit einem Beispiel in Visual Studio Code

Verwenden Sie den Beispielkatalog im Microsoft Foundry Toolkit für Visual Studio Code, um mit einer Arbeitsframeworkvorlage anstelle ihres eigenen Codes zu beginnen:

1. Wählen Sie in der Visual Studio Code Aktivitätsleiste das Symbol "Foundry Toolkit" aus.
2. Wählen Sie unter Entwicklertools>Agent-Entwicklungstools die Option Agent erstellen aus.
3. Wählen Sie unter "Im Code erstellen" mit Vollzugriff die Option "Beispiel verwenden" aus.
4. Unter Gehosteten Agent anhand eines Beispiels erstellen verwenden Sie die Filter, um die Galerie einzugrenzen:
   • Wählen Sie für FrameworkAgent Framework, Bring Your Own, LangGraph oder Copilot SDK aus.
   • Wählen Sie für den Protokolltypdie Antwort-API oder die Aufruf-API aus.
5. Wählen Sie ein Beispiel und dann "Weiter" aus.
6. Geben Sie einen Agentnamen ein, wählen Sie Ihr Foundry-Projekt aus, und wählen Sie dann "Erstellen" aus.

Das Toolkit erstellt ein Gerüst für das Beispiel in einem neuen Arbeitsbereich und richtet eine F5-Debugumgebung mit nur einem Klick ein. Um Abhängigkeiten zu installieren, lokal zu testen und aus Visual Studio Code bereitzustellen, führen Sie die Visual Studio Code Schritte in Der Bereitstellung Ihres ersten gehosteten Agents aus.

Wählen Sie Ihr Protokoll aus.

Jeder Codeschritt verfügt über eine Registerkarte für jede Kombination aus Sprache und Protokoll. Responses verwaltet den Konversationsverlauf und ist OpenAI-kompatibel. Aufrufe geben Ihnen die vollständige Kontrolle über Anforderungs- und Antwortschemas. Wählen Sie in jedem Schritt dieselbe Sprach- und Protokollkombination aus.

Tipp

Sie wissen nicht genau, welches Protokoll verwendet werden soll? Beginnen Sie mit Antworten.

Schritt 1: Hinzufügen der Hostingbibliothek

Fügen Sie dem Projekt die Protokollbibliothek hinzu. Die Bibliothek behandelt den HTTP-Server, Integritätsprüfungen und Protokollkonformität, unabhängig vom verwendeten Agentframework. Wenn Sie ein Framework verwenden, fügen Sie die zugehörigen Pakete zusammen mit der Hostingbibliothek hinzu. Weitere Informationen finden Sie unter Auswählen des Frameworks.

Python (Antworten)

Fügen Sie die Protokollbibliothek zu Ihrem requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Python (Aufrufe)

Fügen Sie die Protokollbibliothek zu Ihrem requirements.txt:

azure-ai-agentserver-invocations>=1.0.0b5

C# (Antworten)

Erstellen Sie ein .NET Webprojekt, und fügen Sie das Protokollpaket hinzu:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

C# (Aufrufe)

Erstellen Sie ein .NET Webprojekt, und fügen Sie das Protokollpaket hinzu:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

Schritt 2: Hinzufügen des Hostingwrappers

Erstellen oder aktualisieren Sie Ihren Agent-Einstiegspunkt mit dem Hostingwrapper. Die folgenden Beispiele zeigen das minimale Muster. Ersetzen Sie den markierten Block durch Ihre vorhandene Agentlogik.

Python (Antworten)

Erstellen oder aktualisieren main.py:

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

Python (Aufrufe)

Erstellen oder aktualisieren main.py:

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

C# (Antworten)

Ersetzen Sie Program.cs:

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

C# (Aufrufe)

Ersetzen Sie Program.cs:

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

Note

Diese Beispiele geben Benutzereingaben wieder, um den Hosting-Wrapper zu demonstrieren. Ersetzen Sie den markierten Block durch Ihre eigene Agentlogik – Modellaufrufe, RAG oder ein Framework wie LangGraph oder das GitHub Copilot SDK. Vollständige Beispiele finden Sie in den Python Beispielen und C#-Beispielen.

Schritt 3: Initialisieren des Projekts

Führen Sie azd ai agent init im Quellverzeichnis Ihres Agenten aus. Die Azure Developer CLI erkennt Ihre Sprache aus den Projektdateien:

Python (Antworten)

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

Python (Aufrufe)

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

C# (Antworten)

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

C# (Aufrufe)

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

Mit diesem Befehl wird eine virtuelle Umgebung (Python) erstellt oder das Projekt (C#) wiederhergestellt und erstellt, Abhängigkeiten installiert und der Agent gestartet. 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

Warning

Wenn die aktuelle azd Umgebung das Foundry-Projekt erstellt hat, löscht azd down die Ressourcengruppe des Projekts und alles darin dauerhaft. Wenn Sie während der Initialisierung ein vorhandenes Projekt ausgewählt haben, azd down bleibt das Projekt, seine Ressourcengruppe, der gehostete Agent und andere Schnellstartressourcen vorhanden. Löschen Sie alle Ressourcen, die Sie nicht mehr aus dem vorhandenen Projekt separat benötigen.

azd down

Troubleshooting

Angelegenheit	Lösung
ModuleNotFoundError: azure.ai.agentserver	Stellen Sie sicher, dass sich die Protokollbibliothek in requirements.txt befindet, und installieren Sie sie erneut: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found	Stellen Sie sicher, dass auf das Protokollpaket verwiesen wird (dotnet add package Azure.AI.AgentServer.Responses --prerelease oder Azure.AI.AgentServer.Invocations), und dass das Projekt das Web SDK (dotnet new web) verwendet.
C#: Cannot resolve scoped service ... Handler from root provider auf dotnet run	Das standardmäßige dotnet new web Startprofil legt ASPNETCORE_ENVIRONMENT=Development fest, wodurch eine strenge Bereichsvalidierung aktiviert wird. Verwenden Sie azd ai agent run, um zu testen (es wird im gehosteten Modus ausgeführt), oder setzen Sie dotnet run vor ASPNETCORE_ENVIRONMENT=Production.
FOUNDRY_PROJECT_ENDPOINT not set	Verwenden Sie azd ai agent run (dadurch wird es automatisch festgelegt), anstatt die App direkt auszuführen. Oder fügen Sie sie Zu Ihrer .env Datei hinzu.
Connection refused bei lokaler Ausführung	Stellen Sie sicher, dass kein anderer Prozess Port 8088 verwendet.
AuthorizationFailed während der Bereitstellung	Sie benötigen Foundry Project Manager auf Projektebene.
Agent bleibt hängen in provisioning	Führen Sie die Ausführung azd ai agent show aus, um den Status zu überprüfen. Die ersten Bereitstellungen können 2 bis 3 Minuten dauern, während Abhängigkeiten installiert werden.
azd ai agent init funktioniert nicht	Führen Sie azd version aus, um zu überprüfen, ob Version 1.27.1 oder höher installiert ist. Führen Sie die Ausführung azd ext show azure.ai.agents aus, um 1.0.0-beta.4 oder höher zu überprüfen. Mit azd ext upgrade azure.ai.agents aktualisieren.

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

Verwalten des Lebenszyklus des gehosteten Agents

• 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 mit eigenem Framework (LangGraph, GitHub Copilot SDK und mehr)
• Beispiele für gehostete C#-Agent