Tutorial: Compilación de una aplicación web agente en Azure App Service con Microsoft Agent Framework o Foundry Agent Service (.NET)

En este tutorial se muestra cómo agregar capacidad agente a una aplicación CRUD basada en datos existente de ASP.NET Core. Para ello, se usan dos enfoques diferentes: Microsoft Agent Framework y Foundry Agent Service.

Si la aplicación web ya tiene características útiles, como compras, reservas de hoteles o administración de datos, es relativamente sencillo agregar funcionalidad de agente a la aplicación web ajustando esas funcionalidades como herramientas (para Microsoft Agent Framework) o como punto de conexión de OpenAPI (para el servicio Foundry Agent). En este tutorial, empezará con una sencilla aplicación de lista de tareas pendientes. Al final, podrá crear, actualizar y administrar tareas con un agente en una aplicación de App Service.

Tanto Microsoft Agent Framework como foundry Agent Service le permiten crear aplicaciones web agente con funcionalidades controladas por IA. En la tabla siguiente se muestran algunas de las consideraciones y desventajas:

En este tutorial, aprenderá a:

Prerequisites

• Una cuenta de Azure con una suscripción activa: cree una cuenta de forma gratuita.
• Cuenta de GitHub para usar GitHub Codespaces: obtenga más información sobre GitHub Codespaces.

Abra el ejemplo con Codespaces.

La manera más fácil de empezar es usar GitHub Codespaces, que proporciona un entorno de desarrollo completo con todas las herramientas necesarias preinstaladas.

1. Vaya al repositorio de GitHub en https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. Seleccione el botón Code (Código ), seleccione la pestaña Codespaces (Espacios de código ) y seleccione Create codespace on main (Crear espacio de código en main).

3. Espere unos instantes para que codespace se inicialice. Cuando esté listo, verá un entorno de desarrollo totalmente configurado en el explorador.

4. Ejecute la aplicación localmente:

   dotnet run
   

5. Cuando vea La aplicación que se ejecuta en el puerto 5280 está disponible, seleccione Abrir en el explorador y agregue algunas tareas.

Revisión del código del agente

Ambos enfoques usan el mismo patrón de implementación, donde el agente se inicializa como servicio (en Program.cs) en un proveedor e inserta en el componente blazor correspondiente.

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

Implementación de la aplicación de ejemplo

El repositorio de ejemplo contiene una plantilla de CLI de Azure Developer (AZD), que crea una aplicación de Servicio de Aplicaciones y despliega tu aplicación de ejemplo. La identidad gestionada asignada por el sistema de App Service se conserva para las llamadas salientes a Azure AI. Una identidad administrada asignada por el usuario independiente y una credencial de identidad federada permiten a la autenticación de App Service actuar como la aplicación de Microsoft Entra generada sin un secreto de cliente.

1. En el terminal, inicia sesión en Azure usando la CLI de Azure Developer:

   azd auth login
   

   Siga las instrucciones para completar el proceso de autenticación.

2. Despliega la aplicación de Azure App Service usando la plantilla AZD:

   azd up
   

3. Cuando se le solicite, proporcione las siguientes respuestas:

   Question	Answer
   Escriba un nuevo nombre de entorno:	Escriba un nombre único.
   Seleccione una suscripción de Azure para usar:	Seleccione la suscripción.
   Elija un grupo de recursos para usar:	Seleccione Crear un grupo de recursos nuevo.
   Seleccione una ubicación para crear el grupo de recursos en:	Seleccione Centro de Suecia.
   Escriba un nombre para el nuevo grupo de recursos:	Escriba Entrar.

4. En la salida de AZD, busque la dirección URL de la aplicación y vaya a ella en el explorador. También copia el valor de audiencia de identidad gestionada de Foundry OpenAPI para usarlo más adelante. El resultado tiene este aspecto:

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

5. Cuando Microsoft te lo pida, inicia sesión usando una cuenta en el tenant de despliegue y verifica que la lista de tareas se carga.

6. En el mismo navegador autenticado, añade /openapi/v1.json al endpoint de App Service. Copia o guarda el esquema OpenAPI generado para más adelante.

   Note

   La autenticación por App Service devuelve una redirección HTTP 302 para solicitudes de navegador no autenticadas. Este ejemplo contiene tanto una interfaz de navegador como APIs, por lo que la redirección proporciona una experiencia de inicio de sesión utilizable. Las aplicaciones solo API suelen usar HTTP 401 en su lugar.

Creación y configuración del recurso de Microsoft Foundry

Asignación de permisos necesarios

Configuración de variables de conexión en la aplicación de ejemplo

1. Abra appsettings.json. Con los valores que copió anteriormente desde el portal de Foundry, configure las siguientes variables:

   • Marco de trabajo de agentes de Microsoft
   • Servicio de agente de Foundry

   Variable	Description
   AzureOpenAIEndpoint	Azure OpenAI endpoint (copiado de la página principal del portal Foundry).
   ModelDeployment	Nombre del modelo en la implementación (copiado del entorno de pruebas de modelos en el nuevo portal de Foundry).

   Note

   Para simplificar el tutorial, usará estas variables en appsettings.json en lugar de sobrescribirlas con la configuración de la aplicación en App Service.

   Note

   Para simplificar el tutorial, usará estas variables en appsettings.json en lugar de sobrescribirlas con la configuración de la aplicación en App Service.

2. Inicie sesión en Azure con la CLI de Azure:

   az login
   

   Esto permite que la biblioteca cliente de Identidad de Azure en el código de ejemplo reciba un token de autenticación para el usuario que ha iniciado sesión. Recuerde que ha agregado el rol necesario para este usuario anteriormente.

3. Ejecute la aplicación localmente:

   dotnet run
   

4. Cuando vea La aplicación que se ejecuta en el puerto 5280 está disponible, seleccione Abrir en el explorador.

5. Valida ambos pivotes por separado:

   • Microsoft Agent Framework: Selecciona Microsoft Agent Framework Agent Agent Agent y pide al agente que cree una tarea. Microsoft Agent Framework llama a la herramienta de tareas en proceso.
   • Foundry Agent Service: Selecciona Foundry Agent Service y pídele al agente que cree una tarea. El agente remoto de Foundry invoca el punto de conexión /api/tasks implementado y protegido con identidad gestionada.

   La tarea que crea el agente de Foundry aparece en la instancia de App Service desplegada, no en la base de datos local en memoria. La herramienta OpenAPI de Foundry siempre utiliza la URL del servidor incrustada en el esquema OpenAPI.

6. De nuevo en el espacio de código de GitHub, implemente los cambios de la aplicación.

   azd up
   

7. Vuelva a ir a la aplicación implementada y pruebe los agentes de chat.

Preguntas más frecuentes

• ¿Cómo puedo incorporar retrieval augmented generation (RAG) en el agente de Foundry?

¿Cómo puedo añadir generación aumentada por recuperación (RAG) al agente de Foundry?

Esta guía se aplica a la ruta Foundry Agent Service en este tutorial. No cambia las implementaciones de LangGraph, Kernel semántico o Microsoft Agent Framework que se muestran en la otra pestaña.

Crea o selecciona una base de conocimientos de Foundry IQ y luego conecta esa base con el agente de Foundry Agent Service. La conexión se expone al agente como una herramienta de conocimiento gestionado de MCP.

El código del Servicio de Aplicaciones sigue invocando al mismo agente por nombre a través de su cliente existente de Foundry y agent_reference. La aplicación web no necesita una integración directa con Búsqueda de Azure AI ni un cliente MCP propio. Si la interfaz muestra las fuentes, procesa las anotaciones de citas devueltas por el agente.

Limpieza de recursos

Cuando haya terminado con la aplicación, puede eliminar los recursos de App Service para evitar incurrir en costos adicionales:

azd down --purge

Luego, elimina el recurso de Foundry si lo creaste por separado.

Más recursos

• Integración de la inteligencia artificial en las aplicaciones de Azure App Service
• ¿Qué es Foundry Agent Service?
• Documentación de Microsoft Agent Framework