Zelfstudie: Een agentische web-app bouwen in Azure App Service met Microsoft Agent Framework of Foundry Agent Service (.NET)

Deze zelfstudie laat zien hoe u agentische mogelijkheden toevoegt aan een bestaande gegevensgestuurde ASP.NET Core CRUD-toepassing. Dit doet u met behulp van twee verschillende benaderingen: Microsoft Agent Framework en Foundry Agent Service.

Als uw webtoepassing al nuttige functies heeft, zoals winkelen, hotelreservering of gegevensbeheer, is het relatief eenvoudig om agentfunctionaliteit toe te voegen aan uw webtoepassing door deze functies als hulpprogramma's (voor Microsoft Agent Framework) of als een OpenAPI-eindpunt (voor Foundry Agent Service) te verpakken. In deze handleiding begint u met een eenvoudige to-do lijstapp. Aan het einde kunt u taken maken, bijwerken en beheren met een agent in een App Service-app.

Met zowel Microsoft Agent Framework als Foundry Agent Service kunt u agentische webtoepassingen bouwen met AI-gestuurde mogelijkheden. In de volgende tabel ziet u enkele overwegingen en afwegingen:

Consideration Microsoft Agent Framework Foundry Agentendienst
Performance Snel (lokaal uitgevoerd) Trager (beheerde, externe service)
Development Volledige code, maximaal beheer Low-code, snelle integratie
Testing Handmatige/eenheidstests in code Ingebouwde speeltuin voor snel testen
Scalability App-managed Door Azure beheerd, automatisch geschaald
Veiligheidsrails Aangepaste implementatie vereist Ingebouwde inhoudsveiligheid en toezicht
Identiteit Aangepaste implementatie vereist Ingebouwde agent-id en verificatie
Enterprise Aangepaste integratie vereist Ingebouwde microsoft 365/Teams-implementatie en geïntegreerde hulpprogramma-aanroepen van Microsoft 365.

In deze handleiding leer je hoe je:

  • Bestaande app-functionaliteit converteren naar hulpprogramma's voor Microsoft Agent Framework.
  • Voeg de hulpprogramma's toe aan een Microsoft Agent Framework-agent en gebruik deze in een web-app.
  • Bestaande app-functionaliteit converteren naar een OpenAPI-eindpunt voor Foundry Agent Service.
  • Roep een Foundry-agent aan in een web-app.
  • Wijs de vereiste machtigingen toe voor connectiviteit met beheerde identiteiten.

Prerequisites

Het voorbeeld openen met Codespaces

De eenvoudigste manier om aan de slag te gaan is door GitHub Codespaces te gebruiken. Dit biedt een volledige ontwikkelomgeving met alle vereiste hulpprogramma's die vooraf zijn geïnstalleerd.

  1. Navigeer naar de GitHub-opslagplaats op https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

  2. Klik op de knop Code, selecteer het tabblad Codespaces en selecteer Codespace op main maken.

  3. Wacht even totdat uw Codespace is geïnitialiseerd. Wanneer u klaar bent, ziet u een volledig geconfigureerde ontwikkelomgeving in uw browser.

  4. Voer de toepassing lokaal uit:

    dotnet run

  5. Wanneer u ziet dat uw toepassing beschikbaar is op poort 5280, selecteer dan Openen in browser en voeg enkele taken toe.

De agentcode controleren

Beide benaderingen gebruiken hetzelfde implementatiepatroon, waarbij de agent wordt geïnitialiseerd als een service (in Program.cs) in een provider en wordt geïnjecteerd in het respectieve Blazor-onderdeel.

De AgentFrameworkProvider is geïnitialiseerd in Services/AgentFrameworkProvider.cs. De initialisatiecode doet het volgende:

  • Hiermee maakt u een IChatClient van Azure OpenAI met behulp van de AzureOpenAIClient.
  • Hiermee haalt u het TaskCrudTool exemplaar op dat de functionaliteit van de CRUD-toepassing inkapselt (in Tools/TaskCrudTool.cs). Met de Description kenmerken van de hulpprogrammamethoden kan de agent bepalen hoe deze moeten worden aangeroepen.
  • Hiermee maakt u een AI-agent met instructies CreateAIAgent() en hulpprogramma's die zijn geregistreerd via AIFunctionFactory.Create().
  • Hiermee maakt u een thread voor de agent om het gesprek tijdens de navigatie te behouden.
// 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);

Telkens wanneer de gebruiker een bericht verzendt, roept het Agent.RunAsync()) aan met de gebruikersinvoer en de agentthread. De agentthread houdt de chatgeschiedenis bij.

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

De voorbeeldtoepassing implementeren

De voorbeeldrepository bevat een Azure Developer CLI (AZD) sjabloon, die een App Service-app maakt en je voorbeeldapplicatie uitrolt. De door het App Service toegewezen beheerde identiteit wordt behouden voor uitgaande Azure AI-aanroepen. Een aparte, door de gebruiker toegewezen beheerde identiteit en gefedereerd identiteitsbewijs laten App Service-authenticatie fungeren als de gegenereerde Microsoft Entra-applicatie zonder een clientgeheim.

  1. Log in de terminal in bij Azure met behulp van Azure Developer CLI:

    azd auth login

    Volg de instructies om het verificatieproces te voltooien.

  2. Deploy de Azure App Service app met behulp van de AZD-template:

    azd up

  3. Geef de volgende antwoorden wanneer u hierom wordt gevraagd:

    Question Answer
    Voer een nieuwe omgevingsnaam in: Voer een unieke naam in.
    Selecteer een Azure-abonnement dat u wilt gebruiken: Selecteer het abonnement.
    Kies een resourcegroep die u wilt gebruiken: Selecteer Een nieuwe resourcegroep maken.
    Selecteer een locatie waarin u de resourcegroep wilt maken in: Selecteer Zweden - centraal.
    Voer een naam in voor de nieuwe resourcegroep: Typ Enter.

  4. Zoek in de AZD-uitvoer de URL van uw app en navigeer ernaar in de browser. Kopieer ook de Foundry OpenAPI managed identity audience waarde voor later. De uitvoer ziet er als volgt uit:

     Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>

 Foundry OpenAPI managed identity audience:
     api://<generated-client-id>

  5. Wanneer Microsoft je ernaar vraagt, log dan in met een account in de deployment tenant en controleer of de takenlijst geladen is.

  6. Voeg in dezelfde geauthenticeerde browser /openapi/v1.json toe aan het App Service-eindpunt. Kopieer of sla het gegenereerde OpenAPI-schema op voor later.

    Note

    App Service-authenticatie geeft een HTTP 302-redirect terug voor niet-geauthenticeerde browserverzoeken. Dit voorbeeld bevat zowel een browserinterface als API's, waardoor de redirect een bruikbare aanmeldervaring biedt. API-only apps gebruiken vaak HTTP 401.

De Microsoft Foundry-resource maken en configureren

  1. Maak in het Foundry-portaal een project.

  2. Een model van uw keuze implementeren (zie Snelstartgids voor Microsoft Foundry: Resources maken).

  3. Kopieer de naam van het model vanaf de bovenkant van de modelspeelplaats.

  4. Kopieer op de startpagina het Azure OpenAI-eindpunt voor later.

Vereiste machtigingen toewijzen

  1. Selecteer in het Foundry-portaal Beheren in het bovenste menu.

  2. Selecteer in Project details de Ouderresource van je project en selecteer vervolgens Open in Azure portal.

    Vanuit het Azure-portaal kun je rolgebaseerde toegang voor de resource toewijzen.

  3. Voeg de volgende rol toe voor zowel de beheerde identiteit van de App Service-app als de gebruiker waarmee je werkt az login:

    Doelresource Vereiste rol Vereist voor
    Gieterij Cognitive Services OpenAI-gebruiker De voltooiingsservice voor chats in Microsoft Agent Framework.

    Zie Azure-rollen toewijzen via Azure Portal voor instructies.

Verbindingsvariabelen configureren in uw voorbeeldtoepassing

  1. Open appsettings.json. Configureer de volgende variabelen met behulp van de waarden die u eerder hebt gekopieerd uit de Foundry-portal:

    Variable Description
    AzureOpenAIEndpoint Azure OpenAI endpoint (gekopieerd van de Foundry portal homepage).
    ModelDeployment Modelnaam in de implementatie (gekopieerd uit de modelspeeltuin in de nieuwe Foundry-portal).

    Note

    Als u de zelfstudie eenvoudig wilt houden, gebruikt u deze variabelen in appsettings.json in plaats van ze te overschrijven met app-instellingen in App Service.

    Note

    Als u de zelfstudie eenvoudig wilt houden, gebruikt u deze variabelen in appsettings.json in plaats van ze te overschrijven met app-instellingen in App Service.

  2. Meld u aan bij Azure met de Azure CLI:

    az login

    Hierdoor kan de Azure Identity-clientbibliotheek in de voorbeeldcode een verificatietoken ontvangen voor de aangemelde gebruiker. Houd er rekening mee dat u de vereiste rol voor deze gebruiker eerder hebt toegevoegd.

  3. Voer de toepassing lokaal uit:

    dotnet run

  4. Wanneer u ziet dat uw toepassing op poort 5280 draait en beschikbaar is, selecteer Openen in browser.

  5. Controleer beide draaipunten afzonderlijk:

    • Microsoft Agent Framework: Selecteer Microsoft Agent Framework Agent en vraag de agent een taak aan te maken. Microsoft Agent Framework roept het in-process-taakhulpprogramma aan.
    • Foundry Agent Service: Selecteer Foundry Agent Service en vraag de agent om een taak te maken. De externe Foundry-agent roept het uitgerolde, beschermde /api/tasks endpoint met beheerde identiteit aan.

    De taak die de Foundry-agent aanmaakt, verschijnt in de gedeployeerde App Service-instantie, niet in de lokale geheugendatabase. De Foundry OpenAPI-tool gebruikt altijd de server-URL die is ingebed in het OpenAPI-schema.

  6. Implementeer uw app-wijzigingen in de GitHub-codespace.

    azd up

  7. Ga opnieuw naar de geïmplementeerde toepassing en test de chatagents.

Veelgestelde vragen

Hoe voeg ik retrieval augmented generation (RAG) toe aan de Foundry-agent?

Deze richtlijn geldt voor het Foundry Agent Service-pad in deze tutorial. Het verandert niet de implementaties van LangGraph, Semantic Kernel of Microsoft Agent Framework die in het andere tabblad worden getoond.

Maak of selecteer een kennisbank van Foundry IQ, en verbind deze vervolgens met de Foundry Agent Service-agent. De verbinding wordt voor de agent beschikbaar gesteld als een beheerde MCP-kennistool.

De App Service-code blijft dezelfde agent bij naam aanroepen via zijn bestaande Foundry-client en agent_reference. De webapp heeft geen directe integratie met Azure AI Zoeken of een eigen MCP-client nodig. Als de gebruikersinterface bronnen toont, verwerk dan de citatie-annotaties die door de agent zijn teruggegeven.

De hulpbronnen opschonen

Wanneer u klaar bent met de toepassing, kunt u de App Service-resources verwijderen om verdere kosten te voorkomen:

azd down --purge

Verwijder vervolgens de Foundry-bron als je die apart hebt aangemaakt.

Meer middelen

  • Last updated on