Samouczek: Budowa aplikacji agenta internetowego w usłudze Azure App Service z wykorzystaniem Microsoft Agent Framework lub Foundry Agent Service (.NET)

W tym samouczku pokazano, jak dodać zdolność agentów do istniejącej aplikacji ASP.NET Core CRUD opartej na danych. Robi to przy użyciu dwóch różnych podejść: Microsoft Agent Framework i Foundry Agent Service.

Jeśli aplikacja internetowa ma już przydatne funkcje, takie jak zakupy, rezerwacja hotelowa lub zarządzanie danymi, stosunkowo proste jest dodanie funkcji agenta do aplikacji internetowej przez opakowywanie tych funkcji jako narzędzi (dla programu Microsoft Agent Framework) lub jako punktu końcowego openAPI (dla usługi Agenta Foundry). W tym samouczku zaczniesz od prostej aplikacji typu lista to-do. Na koniec będziesz mieć możliwość tworzenia, aktualizowania i zarządzania zadaniami za pomocą agenta w aplikacji usługi App Service.

Zarówno Microsoft Agent Framework, jak i Foundry Agent Service umożliwiają tworzenie agentowych aplikacji internetowych wykorzystujących sztuczną inteligencję. W poniższej tabeli przedstawiono niektóre zagadnienia i kompromisy:

W tym poradniku nauczysz się, jak:

Prerequisites

• Konto platformy Azure z aktywną subskrypcją — utwórz bezpłatne konto.
• Konto usługi GitHub do korzystania z usługi GitHub Codespaces — dowiedz się więcej o usłudze GitHub Codespaces.

Otwieranie przykładu za pomocą usługi Codespaces

Najprostszym sposobem rozpoczęcia pracy jest użycie usługi GitHub Codespaces, która udostępnia kompletne środowisko programistyczne ze wszystkimi wymaganymi wstępnie zainstalowanymi narzędziami.

1. Przejdź do repozytorium GitHub pod adresem https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. Wybierz przycisk Kod , wybierz kartę Codespaces i wybierz pozycję Utwórz przestrzeń kodu w obszarze głównym.

3. Zaczekaj chwilę na zainicjowanie usługi Codespace. Gdy wszystko będzie gotowe, zobaczysz w przeglądarce w pełni skonfigurowane środowisko programistyczne.

4. Uruchom aplikację lokalnie:

   dotnet run
   

5. Gdy zobaczysz, że aplikacja uruchomiona na porcie 5280 jest dostępna, wybierz pozycję Otwórz w przeglądarce i dodaj kilka zadań.

Przeanalizować kod agenta

Oba podejścia używają tego samego wzorca implementacji, w którym agent jest inicjowany jako usługa (w Program.cs) dostawcy i wstrzykiwany do odpowiedniego składnika Platformy Blazor.

// 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

Wdrażanie aplikacji przykładowej

Przykładowe repozytorium zawiera szablon Azure Developer CLI (AZD), który tworzy aplikację App Service i wdraża Twoją przykładową aplikację. Tożsamość zarządzana przypisana przez system usługi App Service jest zachowana na potrzeby wychodzących wywołań do usługi Azure AI. Oddzielna zarządzana tożsamość przypisana przez użytkownika oraz federacja tożsamości pozwalały uwierzytelniać App Service jako wygenerowana aplikacja Microsoft Entra bez tajemnicy klienta.

1. W terminalu zaloguj się do Azure, używając Azure Developer CLI:

   azd auth login
   

   Postępuj zgodnie z instrukcjami, aby ukończyć proces uwierzytelniania.

2. Wdrożenie aplikacji Azure App Service za pomocą szablonu AZD:

   azd up
   

3. Po wyświetleniu monitu podaj następujące odpowiedzi:

   Question	Answer
   Wprowadź nową nazwę środowiska:	Wpisz unikatową nazwę.
   Wybierz subskrypcję platformy Azure do użycia:	Wybierz subskrypcję.
   Wybierz grupę zasobów do użycia:	Wybierz pozycję Utwórz nową grupę zasobów.
   Wybierz lokalizację, w ramach których chcesz utworzyć grupę zasobów:	Wybierz pozycję Szwecja Środkowa.
   Wprowadź nazwę nowej grupy zasobów:	Wpisz Enter.

4. W wynikach AZD znajdź URL swojej aplikacji i otwórz go w przeglądarce. Skopiuj też wartość „audience” tożsamości zarządzanej Foundry OpenAPI do późniejszego użycia. Dane wyjściowe wyglądają następująco:

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

5. Gdy Microsoft cię o to poprosi, zaloguj się, używając konta w tenantzie wdrożenia i sprawdź, czy lista zadań się ładuje.

6. W tej samej uwierzytelnionej przeglądarce dodaj /openapi/v1.json na końcu punktu końcowego usługi App Service. Skopiuj lub zapisz wygenerowany schemat OpenAPI na później.

   Note

   Uwierzytelnianie usługi App Service zwraca przekierowanie HTTP 302 dla nieuwierzytelnionych żądań z przeglądarki. Ten przykład zawiera zarówno interfejs przeglądarki, jak i API, dzięki czemu przekierowanie zapewnia użyteczne doświadczenie logowania. Aplikacje oparte wyłącznie na API często korzystają z HTTP 401.

Tworzenie i konfigurowanie zasobu rozwiązania Microsoft Foundry

Przypisywanie wymaganych uprawnień

Konfigurowanie zmiennych połączenia w przykładowej aplikacji

1. Otwórz appsettings.json. Korzystając z wartości skopiowanych wcześniej z portalu Foundry, skonfiguruj następujące zmienne:

   • Microsoft — Struktura agentów
   • Usługa agenta programu Foundry

   Variable	Description
   AzureOpenAIEndpoint	Azure OpenAI endpoint (skopiowany ze strony głównej portalu Foundry).
   ModelDeployment	Nazwa modelu we wdrożeniu (skopiowana ze środowiska testowego modelu w nowym portalu Foundry).

   Note

   Aby zachować prostotę samouczka, użyjesz tych zmiennych w appsettings.json zamiast zastępować je ustawieniami aplikacji w usłudze App Service.

   Note

   Aby zachować prostotę samouczka, użyjesz tych zmiennych w appsettings.json zamiast zastępować je ustawieniami aplikacji w usłudze App Service.

2. Zaloguj się do platformy Azure przy użyciu interfejsu wiersza polecenia platformy Azure:

   az login
   

   Dzięki temu biblioteka klienta tożsamości platformy Azure w przykładowym kodzie może odbierać token uwierzytelniania dla zalogowanego użytkownika. Pamiętaj, że wcześniej dodano wymaganą rolę dla tego użytkownika.

3. Uruchom aplikację lokalnie:

   dotnet run
   

4. Gdy zobaczysz, że aplikacja uruchomiona na porcie 5280 jest dostępna, wybierz pozycję Otwórz w przeglądarce.

5. Walidacja obu pivotów osobno:

   • Microsoft Agent Framework: Wybierz Microsoft Agent Framework Agent i poproś agenta o utworzenie zadania. Microsoft Agent Framework wywołuje narzędzie zadaniowe w procesie.
   • Foundry Agent Service: Wybierz Foundry Agent Service i poproś agenta o utworzenie zadania. Zdalny agent Foundry wywołuje wdrożony, chroniony /api/tasks punkt końcowy przy użyciu tożsamości zarządzanej.

   Zadanie tworzone przez agenta Foundry pojawia się w wdrożonej instancji App Service, a nie w lokalnej bazie danych w pamięci. Narzędzie Foundry OpenAPI zawsze korzysta z adresu URL serwera osadzonego w schemacie OpenAPI.

6. W usłudze GitHub codespace wdróż zmiany aplikacji.

   azd up
   

7. Przejdź ponownie do wdrożonej aplikacji i przetestuj agentów czatu.

Często zadawane pytania

• Jak dodać funkcję retrieval augmented generation (RAG) w agencie Foundry?

Jak dodać generowanie wspomagane wyszukiwaniem (RAG) do agenta Foundry?

Te wskazówki dotyczą ścieżki Foundry Agent Service w tym samouczku. Nie zmienia to implementacji LangGraph, Semantic Kernel ani Microsoft Agent Framework pokazanych w drugiej karcie.

Stwórz lub wybierz bazę wiedzy Foundry IQ, a następnie połącz tę bazę z agentem Foundry Agent Service. Połączenie jest udostępniane agentowi jako zarządzane narzędzie wiedzy MCP.

Kod usługi App Service nadal wywołuje tego samego agenta po nazwie za pośrednictwem istniejącego klienta Foundry oraz agent_reference. Aplikacja webowa nie potrzebuje bezpośredniej integracji z Wyszukiwanie AI platformy Azure ani własnego klienta MCP. Jeśli interfejs wyświetla źródła, przetworz adnotacje cytowań zwrócone przez agenta.

Uprzątnij zasoby

Po zakończeniu pracy z aplikacją możesz usunąć zasoby usługi App Service, aby uniknąć ponoszenia dodatkowych kosztów:

azd down --purge

Następnie usuń zasób Foundry, jeśli utworzyłeś go osobno.

Więcej zasobów

• Integrowanie sztucznej inteligencji z aplikacjami usługi Azure App Service
• Co to jest usługa agenta programu Foundry?
• Dokumentacja programu Microsoft Agent Framework