Esercitazione: Creare un'app Web agentic nel servizio app di Azure con Microsoft Agent Framework o il servizio Foundry Agent (.NET)

Questa esercitazione illustra come aggiungere funzionalità agentiche a un'applicazione CRUD core basata sui dati esistente ASP.NET. A tale scopo, si usano due approcci diversi: Microsoft Agent Framework e il servizio Foundry Agent.

Se l'applicazione Web ha già funzionalità utili, ad esempio acquisti, prenotazioni di hotel o gestione dei dati, è relativamente semplice aggiungere funzionalità dell'agente all'applicazione Web eseguendo il wrapping di tali funzionalità come strumenti (per Microsoft Agent Framework) o come endpoint OpenAPI (per il servizio Foundry Agent). In questo tutorial, si inizia con una semplice app per lista di cose da fare. Alla fine, sarai in grado di creare, aggiornare e gestire attività con un agente in un'app del Servizio app.

Sia Microsoft Agent Framework che il servizio Foundry Agent consentono di creare applicazioni Web agentic con funzionalità basate su intelligenza artificiale. La tabella seguente illustra alcune considerazioni e compromessi:

In questa esercitazione si apprenderà come:

Prerequisites

• Un account Azure con una sottoscrizione attiva: creare gratuitamente un account.
• Account GitHub per usare GitHub Codespaces - Scopri di più su GitHub Codespaces.

Aprire l'esempio con Codespaces

Il modo più semplice per iniziare consiste nell'usare GitHub Codespaces, che offre un ambiente di sviluppo completo con tutti gli strumenti necessari preinstallati.

1. Passare al repository GitHub all'indirizzo https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. Selezionare il pulsante Codice , selezionare la scheda Codespaces e selezionare Crea spazio di codice nel main.

3. Attendere alcuni istanti per inizializzare Codespace. Quando si è pronti, nel browser verrà visualizzato un ambiente di sviluppo completamente configurato.

4. Eseguire l'applicazione in locale:

   dotnet run
   

5. Quando viene visualizzato L'applicazione in esecuzione sulla porta 5280 è disponibile, selezionare Apri nel browser e aggiungere alcune attività.

Esaminare il codice dell'agente

Entrambi gli approcci usano lo stesso modello di implementazione, in cui l'agente viene inizializzato come servizio (in Program.cs) in un provider e inserito nel rispettivo componente 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

Distribuire l'applicazione di esempio

Il repository di esempio contiene un template Azure Developer CLI (AZD), che crea un'app di App Service e distribuisce la tua applicazione di esempio. L'identità gestita assegnata al sistema App Service viene mantenuta per le chiamate AI Azure in uscita. Un'identità gestita separata assegnata dall'utente e una credenziale di identità federata permettevano all'autenticazione App Service di agire come l'applicazione Microsoft Entra generata senza un segreto client.

1. Nel terminale, accedi ad Azure usando Azure Developer CLI:

   azd auth login
   

   Seguire le istruzioni per completare il processo di autenticazione.

2. Distribuisci l'app Servizio app di Azure utilizzando il modello AZD:

   azd up
   

3. Quando richiesto, fornire le risposte seguenti:

   Question	Answer
   Immettere un nuovo nome di ambiente:	Digitare un nome univoco.
   Selezionare una sottoscrizione di Azure da usare:	Selezionare la sottoscrizione.
   Selezionare un gruppo di risorse da usare:	Selezionare Crea un nuovo gruppo di risorse.
   Selezionare un percorso in cui creare il gruppo di risorse:	Selezionare Svezia centrale.
   Immettere un nome per il nuovo gruppo di risorse:	Immettere Invio.

4. Nell'output AZD, individua l'URL della tua app e accedi a esso tramite il browser. Copia anche il valore dell'audience di identità gestita da Foundry OpenAPI per più avanti. L'output è simile al seguente:

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

5. Quando Microsoft ti chiede, accedi usando un account nel tenant di distribuzione e verifica che la lista delle attività si carichi.

6. Nello stesso browser già autenticato, aggiungi /openapi/v1.json all'endpoint di App Service. Copia o salva lo schema OpenAPI generato per dopo.

   Note

   L'autenticazione tramite App Service restituisce un reindirizzamento HTTP 302 per le richieste del browser non autenticate. Questo esempio contiene sia un'interfaccia utente del browser che API, quindi il redirect offre un'esperienza di accesso utilizzabile. Le app basate esclusivamente su API usano comunemente invece HTTP 401.

Creare e configurare la risorsa Microsoft Foundry

Assegnare le autorizzazioni necessarie

Configurare le variabili di connessione nell'applicazione di esempio

1. Aprire appsettings.json. Usando i valori copiati in precedenza dal portale foundry, configurare le variabili seguenti:

   • Microsoft Agent Framework
   • Servizio Agente Fonderia

   Variable	Description
   AzureOpenAIEndpoint	Azure OpenAI endpoint (copiato dalla homepage del portale Foundry).
   ModelDeployment	Nome del modello nella distribuzione (copiato dall'area di sperimentazione del modello nel nuovo portale Foundry).

   Note

   Per semplificare l'esercitazione, queste variabili verranno usate in appsettings.json anziché sovrascriverle con le impostazioni dell'app nel servizio app.

   Note

   Per semplificare l'esercitazione, queste variabili verranno usate in appsettings.json anziché sovrascriverle con le impostazioni dell'app nel servizio app.

2. Accedere ad Azure con l'interfaccia della riga di comando di Azure:

   az login
   

   Ciò consente alla libreria client di Identità di Azure nel codice di esempio di ricevere un token di autenticazione per l'utente connesso. Tenere presente che è stato aggiunto il ruolo necessario per questo utente in precedenza.

3. Eseguire l'applicazione in locale:

   dotnet run
   

4. Quando viene visualizzato L'applicazione in esecuzione sulla porta 5280 è disponibile, selezionare Apri nel browser.

5. Valida entrambi i pivot separatamente:

   • Microsoft Agent Framework: Seleziona Microsoft Agent Framework Agent e chiedi all'agente di creare un compito. Microsoft Agent Framework chiama lo strumento di task in processamento.
   • Servizio Agente Fonderia: Seleziona Foundry Agent Service e chiedi all'agente di creare un compito. L'agente remoto di Foundry invoca l'endpoint /api/tasks distribuito e protetto usando l'identità gestita.

   Il compito creato dall'agente Foundry appare nell'istanza del servizio App distribuito, non nel database locale in memoria. Lo strumento Foundry OpenAPI utilizza sempre l'URL del server incorporato nello schema OpenAPI.

6. Tornare nello spazio di codice GitHub, distribuire le modifiche dell'app.

   azd up
   

7. Passare di nuovo all'applicazione distribuita e testare gli agenti di chat.

Domande frequenti

• Come posso aggiungere la generazione aumentata di recupero (RAG) all'agente Foundry?

Come posso aggiungere la generazione aumentata di recupero (RAG) all'agente Foundry?

Questa guida si riferisce al percorso Foundry Agent Service in questo tutorial. Non cambia le implementazioni di LangGraph, Kernel semantico o Microsoft Agent Framework mostrate nell'altra scheda.

Crea o seleziona una knowledge base di Foundry IQ, e poi collega la knowledge base all'agente di Foundry Agent Service. La connessione viene esposta all'agente come uno strumento di conoscenza MCP gestito.

Il codice di App Service continua a richiamare lo stesso agente per nome tramite il client Foundry esistente e agent_reference. L'app web non ha bisogno di un'integrazione diretta con Azure AI Search né di un proprio client MCP. Se l'interfaccia mostra le fonti, elabora le annotazioni di citazione restituite dall'agente.

Pulire le risorse

Al termine dell'applicazione, è possibile eliminare le risorse del servizio app per evitare di sostenere ulteriori costi:

azd down --purge

Poi, elimina la risorsa Foundry se l'hai creata separatamente.

Altre risorse

• Integrare l'intelligenza artificiale nelle applicazioni del servizio app di Azure
• Che cos'è il Servizio Agente Fonderia?
• Documentazione di Microsoft Agent Framework