Självstudie: Skapa en agentisk webbapp i Azure App Service med Microsoft Agent Framework eller Foundry Agent Service (.NET)

Den här handledningen visar hur du lägger till agentfunktionalitet i en befintlig datadriven ASP.NET Core CRUD-applikation. Det gör detta med hjälp av två olika metoder: Microsoft Agent Framework och Foundry Agent Service.

Om ditt webbprogram redan har användbara funktioner, till exempel shopping, hotellbokning eller datahantering, är det relativt enkelt att lägga till agentfunktioner i webbappen genom att omsluta dessa funktioner som verktyg (för Microsoft Agent Framework) eller som en OpenAPI-slutpunkt (för Foundry Agent Service). I den här handledningen börjar du med en enkel to-do-listapp. I slutet kan du skapa, uppdatera och hantera uppgifter med en agent i en App Service-app.

Microsoft Agent Framework

Gjuteriagenttjänst

Med både Microsoft Agent Framework och Foundry Agent Service kan du skapa agentiska webbprogram med AI-drivna funktioner. Följande tabell visar några av övervägandena och kompromisserna:

Consideration	Microsoft Agent Framework	Gjuteritjänstagent
Performance	Snabb (körs lokalt)	Långsammare (hanterad fjärrtjänst)
Development	Fullständig kod, maximal kontroll	Låg kod, snabb integrering
Testing	Manuella tester och enhetstester i kod	Inbyggd lekplats för snabb testning
Scalability	App-managed	Azure-hanterad, autoskalning
Säkerhetsramverk	Anpassad implementering krävs	Inbyggd innehållssäkerhet och moderering
Identitet	Anpassad implementering krävs	Inbyggt agent-ID och autentisering
Enterprise	Anpassad integrering krävs	Inbyggd Microsoft 365/Teams-distribution och integrerade Verktygsanrop för Microsoft 365.

I den här tutorialen lär du dig följande:

• Konvertera befintliga appfunktioner till verktyg för Microsoft Agent Framework.
• Lägg till verktygen i en Microsoft Agent Framework-agent och använd dem i en webbapp.
• Konvertera befintliga appfunktioner till en OpenAPI-slutpunkt för Foundry Agent Service.
• Anropa en Foundry-agent i en webbapp.
• Tilldela nödvändiga behörigheter för hanterad identitetsanslutning.

Prerequisites

• Ett Azure-konto med en aktiv prenumeration – Skapa ett konto kostnadsfritt.
• GitHub-konto för att använda GitHub Codespaces – Läs mer om GitHub Codespaces.

Öppna exemplet med Codespaces

Det enklaste sättet att komma igång är att använda GitHub Codespaces, som ger en fullständig utvecklingsmiljö med alla nödvändiga verktyg förinstallerade.

1. Navigera till GitHub-lagringsplatsen på https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. Välj knappen Kod , välj fliken Codespaces och välj Skapa kodområde på main.

3. Vänta en stund tills kodområdet initieras. När du är klar visas en fullständigt konfigurerad utvecklingsmiljö i webbläsaren.

4. Kör programmet lokalt:

   dotnet run
   

5. När du ser Att din applikation körs på port 5280 och är tillgänglig, väljer du Öppna i webbläsaren och lägger till några uppgifter.

Granska agentkoden

Båda metoderna använder samma implementeringsmönster, där agenten initieras som en tjänst (i Program.cs) i en provider och matas in i respektive Blazor-komponent.

Microsoft Agent Framework

AgentFrameworkProvider Initieras i Tjänster/AgentFrameworkProvider.cs. Initieringskoden gör följande:

• Skapar en IChatClient från Azure OpenAI med hjälp av AzureOpenAIClient.
• Hämtar den TaskCrudTool instans som omsluter funktionaliteten för CRUD-programmet (i Verktyg/TaskCrudTool.cs). Attributen Description på verktygsmetoderna hjälper agenten att avgöra hur de ska kallas.
• Skapar en AI-agent genom att använda CreateAIAgent() med instruktioner och verktyg som är registrerade via AIFunctionFactory.Create().
• Skapar en tråd för agenten för att bevara konversationen i navigeringen.

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

Varje gång användaren skickar ett meddelande anropar Blazor-komponenten (i Agent.RunAsync()) med användarens indata och agenttråden. Agenttråden håller reda på chatthistoriken.

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

Gjuteriagenttjänst

Providern FoundryAgentProvider initieras i Tjänster/FoundryAgentProvider.cs. Initieringskoden gör följande:

• Skapar en AIProjectClient genom att använda Foundry-projektslutpunkten.
• Hämtar en befintlig agent från Microsoft Foundry med hjälp av namn.
• Skapar en konversation för webbläsarsessionen.
• Hämtar en ProjectResponsesClient för agenten och konversationen.

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

Den här initieringskoden definierar inte några funktioner för agenten eftersom du vanligtvis skapar agenten i Foundry-portalen. Som en del av exempelscenariot följer det även OpenAPI-mönstret som visas i Lägg till en App Service-app som ett verktyg i Foundry Agent Service (.NET) och gör dess CRUD-funktioner tillgängliga som en OpenAPI-slutpunkt. På så sätt kan du lägga till den i agenten senare som ett anropsbart verktyg.

OpenAPI-koden definieras i Program.cs. API:et "get tasks" definierar till exempel åtgärds-ID:t med WithName(), vilket krävs av OpenAPI-specifikationsverktyget i Microsoft Foundry, och WithDescription() hjälper agenten att avgöra hur API:et ska anropas:

app.MapOpenApi();

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

Varje gång användaren skickar ett meddelande anropar Blazor-komponenten (i ResponseClient.CreateResponseAsync()) med användarens indata. Svarsklienten använder konversations-ID:t för att hålla reda på chatthistoriken.

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

Distribuera exempelprogrammet

Exempellagringsplatsen innehåller en AZD-mall (Azure Developer CLI) som skapar en App Service-app med hanterad identitet och distribuerar exempelprogrammet.

1. Logga in på Azure med Azure Developer CLI i terminalen:

   azd auth login
   

   Följ anvisningarna för att slutföra autentiseringsprocessen.

2. Distribuera Azure App Service-appen med AZD-mallen:

   azd up
   

3. När du uppmanas, ge följande svar:

   Question	Answer
   Ange ett nytt miljönamn:	Skriv ett unikt namn.
   Välj en Azure-prenumeration som ska användas:	Välj prenumerationen.
   Välj en resursgrupp som ska användas:	Välj Skapa en ny resursgrupp.
   Välj en plats för att skapa resursgruppen i:	Välj Sweden Central.
   Ange ett namn för den nya resursgruppen:	Skriv Retur.

4. I AZD-utdata letar du reda på url:en för din app och navigerar till den i webbläsaren. URL:en ser ut så här i AZD-utdata:

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

5. Välj OpenAPI-schemaobjektet för att öppna det automatiskt genererade OpenAPI-schemat på standardsökvägen /openapi/v1.json . Du behöver det här schemat senare.

6. Efter distributionen visas en URL för ditt distribuerade program.

   Nu har du en App Service-app med en systemtilldelad hanterad identitet.

Skapa och konfigurera Microsoft Foundry-resursen

Microsoft Agent Framework

1. I Foundry-portalen kontrollerar du att den översta Ny Foundry-radioknappen är inställd på aktiv och skapa ett projekt.

2. Distribuera en modell (se Microsoft Foundry Snabbstart: Skapa resurser).

3. Kopiera modellnamnet överst på modelllekplatsen.

4. Det enklaste sättet att hämta Azure OpenAI-slutpunkten är fortfarande från den klassiska portalen. Välj alternativknappen Ny foundry, därefter Azure OpenAI, och kopiera sedan URL:en vid Azure OpenAI slutpunkt för senare användning.

   

Gjuteriagenttjänst

1. I Foundry-portalen kontrollerar du att den översta Ny Foundry-radioknappen är inställd på aktiv och skapa ett projekt.

2. På startsidan kopierar du Projektslutpunkten för senare.

3. Välj Börja skapa>en agent och följ anvisningarna.

4. I den nya agentens lekplats skapar du ett OpenAPI-verktyg för att anropa webbappen genom att välja Verktyg>Lägg till>anpassat>OpenAPI-verktyg>Skapa. I installationsfönstret lägger du till en åtgärd med verktyget OpenAPI-specifikation. Använd OpenAPI-schemat som du får från den distribuerade webbappen och anonym autentisering. Detaljerade steg finns i Använda OpenAPI-specifikationsverktyget.

   Programkoden är redan konfigurerad för att inkludera serverns url och operationId, som krävs av agenten. Mer information finns i Ansluta till OpenAPI-specifikation.

5. Var noga med att välja Spara.

6. Välj Prova på lekplatsen och testa Foundry-agenten med frågor som "Visa mig alla uppgifter" och "Lägg till en uppgift".

   Om du får ett giltigt svar gör agenten anrop till OpenAPI-slutpunkten på din distribuerade webbapplikation.

Tilldela nödvändiga behörigheter

Microsoft Agent Framework

1. På den översta menyn i den nya Foundry-portalen väljer du Använd och sedan Admin. På raden för ditt Foundry-projekt bör du se två länkar. Den i kolumnen Namn är projektresursen Foundry och den i kolumnen Överordnad resurs är Foundry-resursen.

   

2. Välj Foundry-resursen i den överordnade resursen och välj sedan Hantera den här resursen i Azure-portalen. Från Azure-portalen kan du tilldela rollbaserad åtkomst för resursen till den distribuerade webbappen.

3. Lägg till följande roll för App Service-appens hanterade identitet:

   Målresurs	Obligatorisk roll	Behövs för
   Gjuteri	Cognitive Services OpenAI-användare	Tjänsten för chattens slutförande i Microsoft Agent Framework.

   Instruktioner finns i Tilldela Azure-roller med hjälp av Azure-portalen.

Gjuteriagenttjänst

1. På den översta menyn i den nya Foundry-portalen väljer du Använd och sedan Admin. På raden för ditt Foundry-projekt bör du se två länkar. Den i kolumnen Namn är projektresursen Foundry och den i kolumnen Överordnad resurs är Foundry-resursen.

   

2. Välj projektresursen Foundry i kolumnen Namn och välj sedan Hantera den här resursen i Azure-portalen. Från Azure-portalen kan du tilldela rollbaserad åtkomst för resursen till den distribuerade webbappen.

3. Lägg till följande roll för App Service-appens hanterade identitet:

   Målresurs	Obligatorisk roll	Behövs för
   Foundry-projekt	Azure AI-användare	Läser och anropar Foundry-agenten.

   Instruktioner finns i Tilldela Azure-roller med hjälp av Azure-portalen.

Konfigurera anslutningsvariabler i exempelprogrammet

1. Öppna appsettings.json. Med de värden som du kopierade tidigare från Foundry-portalen konfigurerar du följande variabler:

   Microsoft Agent Framework

   Variable	Description
   AzureOpenAIEndpoint	Azure OpenAI-slutpunkt (kopierad från den klassiska Foundry-portalen).
   ModelDeployment	Modellnamn i distributionen (kopieras från modelllekplatsen i den nya Foundry-portalen).

   Note

   För att hålla självstudien enkel använder du dessa variabler i appsettings.json i stället för att skriva över dem med appinställningar i App Service.

   Gjuteriagenttjänst

   Variable	Description
   FoundryProjectEndpoint	Microsoft Foundry-projektslutpunkten från den nya Foundry-portalen.
   FoundryAgentName	Agentnamn (från agentlekplatsen i Foundry-portalen).

   Note

   För att hålla självstudien enkel använder du dessa variabler i appsettings.json i stället för att skriva över dem med appinställningar i App Service.

2. Logga in på Azure med Azure CLI:

   az login
   

   På så sätt kan Azure Identity-klientbiblioteket i exempelkoden ta emot en autentiseringstoken för den inloggade användaren. Kom ihåg att du lade till den roll som krävs för den här användaren tidigare.

3. Kör programmet lokalt:

   dotnet run
   

4. När du ser Din applikation som körs på port 5280 är tillgänglig väljer du Öppna i webbläsare.

5. Välj länken Microsoft Agent Framework Agent och länken Foundry Agent Service för att testa chattgränssnittet. Om du får ett svar ansluter programmet till Microsoft Foundry-resursen.

6. Tillbaka i GitHub-kodområdet distribuerar du dina appändringar.

   azd up
   

7. Navigera till det distribuerade programmet igen och testa chattagenterna.

Microsoft Agent Framework

Gjuteriagenttjänst

Rensa resurser

När du är klar med programmet kan du ta bort App Service-resurserna för att undvika ytterligare kostnader:

azd down --purge

Eftersom AZD-mallen inte innehåller Microsoft Foundry-resurserna måste du ta bort dem manuellt om du vill.

Fler resurser

• Integrera AI i dina Azure App Service-program
• Vad är Foundry Agent Service?
• Dokumentation om Microsoft Agent Framework