Lernprogramm: Erstellen einer agentischen Web-App in Azure App Service mit Microsoft Agent Framework oder Foundry Agent Service (.NET)

In diesem Lernprogramm wird veranschaulicht, wie Sie einer vorhandenen datengesteuerten ASP.NET Core CRUD-Anwendung agentische Funktionen hinzufügen. Dazu werden zwei verschiedene Ansätze verwendet: Microsoft Agent Framework und Foundry Agent Service.

Wenn Ihre Webanwendung bereits nützliche Features wie Shopping, Hotelbuchung oder Datenverwaltung aufweist, ist es relativ einfach, Ihrer Webanwendung Agent-Funktionen hinzuzufügen, indem sie diese Funktionen als Tools (für Microsoft Agent Framework) oder als OpenAPI-Endpunkt (für Foundry Agent Service) umschließen. In dieser Anleitung beginnen Sie mit einer einfachen To-Do-Listen-App. Am Ende können Sie Aufgaben mit einem Agent in einer App Service-App erstellen, aktualisieren und verwalten.

Sowohl microsoft Agent Framework als auch der Foundry Agent Service ermöglichen Es Ihnen, agentische Webanwendungen mit KI-gesteuerten Funktionen zu erstellen. In der folgenden Tabelle sind einige der Überlegungen und Kompromisse aufgeführt:

In diesem Tutorial lernen Sie Folgendes:

Prerequisites

• Ein Azure-Konto mit einem aktiven Abonnement – Kostenlos ein Konto erstellen.
• GitHub-Konto zur Verwendung von GitHub Codespaces – Erfahren Sie mehr über GitHub Codespaces.

Öffnen des Beispiels mit Codespaces

Die einfachste Möglichkeit für die ersten Schritte ist die Verwendung von GitHub Codespaces, die eine vollständige Entwicklungsumgebung mit allen erforderlichen Tools vorinstalliert bietet.

1. Navigieren Sie zum GitHub-Repository unter https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. Wählen Sie die Schaltfläche "Code ", dann die Registerkarte " Codespaces " und dann " Codespace erstellen" im Hauptfeld aus.

3. Warten Sie einige Augenblicke, bis Der Codespace initialisiert wird. Wenn Sie bereit sind, wird eine vollständig konfigurierte Entwicklungsumgebung in Ihrem Browser angezeigt.

4. Führen Sie die Anwendung lokal aus:

   dotnet run
   

5. Wenn Sie sehen, dass Ihre Anwendung auf Port 5280 ausgeführt wird, wählen Sie "Im Browser öffnen" aus, und fügen Sie einige Aufgaben hinzu.

Überprüfen des Agentcodes

Beide Ansätze verwenden dasselbe Implementierungsmuster, bei dem der Agent als Dienst (in Program.cs) in einem Anbieter initialisiert und in die jeweilige Blazor-Komponente eingefügt wird.

// Create IChatClient
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deployment)
    .AsIChatClient();

// Get TaskCrudTool instance from service provider
var taskCrudTool = sp.GetRequiredService<TaskCrudTool>();

// Create agent with tools
var agent = chatClient.CreateAIAgent(
    instructions: @"You are an agent that manages tasks using CRUD operations. 
        Use the provided functions to create, read, update, and delete tasks. 
        Always call the appropriate function for any task management request.
        Don't try to handle any requests that are not related to task management.
        When handling requests, if you're missing any information, don't make it up but prompt the user for it instead.",
    tools:
    [
        AIFunctionFactory.Create(taskCrudTool.CreateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.ReadTasksAsync),
        AIFunctionFactory.Create(taskCrudTool.UpdateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.DeleteTaskAsync)
    ]);

// Create thread for this scoped instance (persists across navigation)
var thread = agent.GetNewThread();

return (agent, thread);

var response = await this.Agent.RunAsync(sentInput, this.agentThread);

// Create project client
var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

// Get an existing agent from Microsoft Foundry
var agent = projectClient.Agents.GetAgent(agentName);

// Get conversations client for retrieving history
var conversationsClient = projectClient.OpenAI.Conversations;

// Create conversation for this browser session
var conversation = conversationsClient.CreateProjectConversation().Value;

// Get response client for this agent and conversation
var responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentName, conversation.Id);

return (responseClient, conversation, conversationsClient);

app.MapOpenApi();

app.MapGet("/api/tasks", async (TaskService taskService) =>
{
    return Results.Ok(await taskService.GetAllTasksAsync());
})
.WithDescription("Gets all tasks.")
.WithName("GetAllTasks");

#pragma warning disable OPENAI001
var response = await FoundryProvider.ResponseClient.CreateResponseAsync(sentInput);
#pragma warning restore OPENAI001

Bereitstellen der Beispielanwendung

Das Beispiel-Repository enthält eine Azure Developer CLI (AZD)-Vorlage, die eine App Service-App erstellt und deine Beispielanwendung bereitstellt. Die vom App Service systemzugeordneten verwalteten Identität wird für ausgehende Azure-KI-Aufrufe beibehalten. Eine separate, vom Benutzer zugewiesene verwaltete Identität und eine föderierte Identitätszugangsdaten ermöglichen es der App Service-Authentifizierung, als generierte Microsoft Entra-Anwendung ohne Client-Geheimnis zu fungieren.

1. Im Terminal melden Sie sich mit Azure Developer CLI bei Azure an:

   azd auth login
   

   Folgen Sie den Anweisungen, um den Authentifizierungsprozess abzuschließen.

2. Deploye die Azure App Service App mit der AZD-Vorlage:

   azd up
   

3. Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Antworten:

   Question	Answer
   Geben Sie einen neuen Umgebungsnamen ein:	Geben Sie einen eindeutigen Namen ein.
   Wählen Sie ein Azure-Abonnement aus, das Sie verwenden möchten:	Wählen Sie das Abonnement aus.
   Wählen Sie eine zu verwendende Ressourcengruppe aus:	Wählen Sie Eine neue Ressourcengruppe erstellen aus.
   Wählen Sie einen Speicherort aus, in dem die Ressourcengruppe erstellt werden soll:	Wählen Sie "Schweden Zentral" aus.
   Geben Sie einen Namen für die neue Ressourcengruppe ein:	Geben Sie Eingeben ein.

4. Suchen Sie in der AZD-Ausgabe die URL für Ihre App, und navigieren Sie im Browser dorthin. Kopiere außerdem den Wert für die Foundry OpenAPI-Zielgruppe der verwalteten Identität zur späteren Verwendung. Die Ausgabe sieht wie folgt aus:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
   
    Foundry OpenAPI managed identity audience:
        api://<generated-client-id>
    

5. Wenn Microsoft Sie auffordert, melden Sie sich mit einem Konto im Deployment-Tenant an und überprüfen Sie, ob die Aufgabenliste geladen ist.

6. Im selben authentifizierten Browser hängen Sie /openapi/v1.json dem App-Service-Endpunkt an. Kopiere oder speichere das generierte OpenAPI-Schema für später.

   Note

   Die App Service-Authentifizierung gibt eine HTTP-302-Weiterleitung für nicht authentifizierte Browseranfragen zurück. Dieses Beispiel enthält sowohl eine Browser-Benutzeroberfläche als auch APIs, sodass die Weiterleitung ein brauchbares Anmeldeerlebnis bietet. API-only-Apps verwenden stattdessen häufig HTTP 401.

Erstellen und Konfigurieren der Microsoft Foundry-Ressource

Zuweisen erforderlicher Berechtigungen

Konfigurieren von Verbindungsvariablen in Ihrer Beispielanwendung

1. Öffnen Sie appsettings.json. Konfigurieren Sie mithilfe der Werte, die Sie zuvor aus dem Foundry-Portal kopiert haben, die folgenden Variablen:

   • Microsoft Agent Framework
   • Foundry-Agent-Dienst

   Variable	Description
   AzureOpenAIEndpoint	Azure OpenAI-Endpunkt (kopiert von der Startseite des Foundry-Portals).
   ModelDeployment	Modellname in der Bereitstellung (kopiert aus dem Modell-Playground im New Foundry Portal).

   Note

   Um das Lernprogramm einfach zu halten, verwenden Sie diese Variablen in appsettings.json, anstatt sie mit App-Einstellungen in App Service zu überschreiben.

   Note

   Um das Lernprogramm einfach zu halten, verwenden Sie diese Variablen in appsettings.json, anstatt sie mit App-Einstellungen in App Service zu überschreiben.

2. Melden Sie sich mit der Azure CLI bei Azure an:

   az login
   

   Dadurch kann die Azure Identity-Clientbibliothek im Beispielcode ein Authentifizierungstoken für den angemeldeten Benutzer empfangen. Denken Sie daran, dass Sie die erforderliche Rolle für diesen Benutzer zuvor hinzugefügt haben.

3. Führen Sie die Anwendung lokal aus:

   dotnet run
   

4. Wenn Sie sehen, dass Ihre Anwendung auf Port 5280 ausgeführt wird, wählen Sie "Im Browser öffnen" aus.

5. Validiere beide Pivots separat:

   • Microsoft Agent Framework: Wählen Sie Microsoft Agent Framework Agent und bitten Sie den Agenten, eine Aufgabe zu erstellen. Das Microsoft Agent Framework ruft das In-Process-Task-Tool auf.
   • Foundry Agent Service: Wählen Sie Foundry Agent Service und bitten Sie den Agenten, eine Aufgabe zu erstellen. Der entfernte Foundry-Agent ruft den bereitgestellten, geschützten /api/tasks Endpunkt mit verwalteter Identität auf.

   Die Aufgabe, die der Foundry-Agent erstellt, erscheint in der bereitgestellten App Service-Instanz, nicht in der lokalen In-Memory-Datenbank. Das Foundry OpenAPI-Tool verwendet immer die Server-URL, die im OpenAPI-Schema eingebettet ist.

6. Stellen Sie ihre App-Änderungen wieder im GitHub-Codespace bereit.

   azd up
   

7. Navigieren Sie erneut zur bereitgestellten Anwendung, und testen Sie die Chat-Agents.

Häufig gestellte Fragen

• Wie füge ich Retrieval-Augmented Generation (RAG) zum Foundry-Agenten hinzu?

Wie füge ich dem Foundry-Agenten Retrieval-Augmented Generation (RAG) hinzu?

Diese Anleitung gilt für den Foundry Agent Service-Weg in diesem Tutorial. Es ändert nicht die im anderen Tab gezeigten Implementierungen von LangGraph, Semantischer Kernel oder Microsoft Agent Framework.

Erstellen oder wählen Sie eine Foundry IQ Wissensdatenbank und verbinden Sie diese dann mit dem Foundry Agent Service Agenten. Die Verbindung wird dem Agenten als verwaltetes MCP-Wissenswerkzeug zur Verfügung gestellt.

Der App Service-Code ruft denselben Agenten weiterhin namentlich über seinen bestehenden Foundry-Client und agent_referenceauf. Die Webanwendung benötigt keine direkte Azure KI-Suche-Integration oder einen eigenen MCP-Client. Wenn die Benutzeroberfläche Quellen anzeigt, verarbeiten Sie die vom Agenten zurückgegebenen Zitationsanmerkungen.

Bereinigen von Ressourcen

Wenn Sie mit der Anwendung fertig sind, können Sie die App Service-Ressourcen löschen, um weitere Kosten zu vermeiden:

azd down --purge

Dann lösche die Foundry-Ressource, falls du sie separat erstellt hast.

Weitere Ressourcen

• Integrieren von KI in Ihre Azure App Service-Anwendungen
• Was ist Foundry Agent Service?
• Dokumentation zu Microsoft Agent Framework