Tutorial: Compilación de una aplicación web agente en Azure App Service con LangGraph o Foundry Agent Service (Python)

En este tutorial se muestra cómo agregar funcionalidad de agente a una aplicación CRUD de FastAPI controlada por datos existente. Para ello, se usan dos enfoques diferentes: LangGraph 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 en un complemento (para LangGraph) o como punto de conexión de OpenAPI (para el servicio de agente de Foundry). 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.

LangGraph y Foundry Agent Service le permiten crear aplicaciones web agente con funcionalidades controladas por IA. LangGraph es similar a Microsoft Agent Framework y es un SDK. En la tabla siguiente se muestran algunas de las consideraciones y desventajas:

En este tutorial, aprenderá a:

Prerrequisitos

• 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.

Apertura del ejemplo con Codespaces

La manera más fácil de empezar es mediante 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-langgraph-foundry-python.

2. Seleccione el botón Código, seleccione la pestaña Codespaces y seleccione Crear Codespaces en main.

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

4. Ejecución de la aplicación de forma local:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

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

   Los agentes no están completamente configurados, por lo que aún no funcionan. Los configurará más adelante.

Revisión del código del agente

Ambos enfoques usan el mismo patrón de implementación, donde el agente se inicializa al iniciar la aplicación y responde a los mensajes de usuario mediante solicitudes POST.

self.memory = InMemorySaver()
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation thread per worker process.
self.thread_id = "authenticated-conversation"

try:
    endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    deployment_name = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME")
    
    if not endpoint or not deployment_name:
        print("Azure OpenAI configuration missing for LangGraph agent")
        return
    
    # Initialize Azure OpenAI client
    credential = DefaultAzureCredential()
    azure_ad_token_provider = get_bearer_token_provider(
        credential, "https://cognitiveservices.azure.com/.default"
    )
    
    self.llm = AzureChatOpenAI(
        azure_endpoint=endpoint,
        azure_deployment=deployment_name,
        azure_ad_token_provider=azure_ad_token_provider,
        api_version="2024-10-21"
    )
    
    # Define tools
    tools = [
        self._create_task_tool(),
        self._get_tasks_tool(),
        self._get_task_tool(),
        self._update_task_tool(),
        self._delete_task_tool()
    ]
    
    # Create the agent
    self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)

config = {"configurable": {"thread_id": self.thread_id}}

# Process the message
result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Get the OpenAI client for conversation operations
self.openai_client = self.project_client.get_openai_client()

# Find the existing agent by name
self.agent = self.project_client.agents.get(agent_name)

if not self.agent:
    print(f"Agent with name '{agent_name}' not found in project.")
    return
            
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation per worker process.
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

# Add user message to the conversation
await asyncio.to_thread(
    self.openai_client.conversations.items.create,
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

# Create response using the agent
response = await asyncio.to_thread(
    self.openai_client.responses.create,
    conversation=self.conversation_id,
    extra_body={"agent": {"name": self.agent.name, "type": "agent_reference"}},
    input="",
)

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:

   Pregunta	Respuesta
   Escribir 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.json al endpoint de App Service. Copia o guarda el esquema OpenAPI generado para más adelante.

   Nota:

   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

Asignar los permisos necesarios

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

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

   • LangGraph
   • Servicio de agente de Foundry

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

   Nota:

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

   Nota:

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

   Los valores en .env configuran la conexión saliente de la app a Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID configura la conexión separada de entrada Foundry-to-App-Service OpenAPI y se almacena en el entorno AZD.

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. Ejecución de la aplicación de forma local:

   source venv/bin/activate
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

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

5. Valida ambos pivotes por separado:

   • LangGraph:Selecciona LangGraph Agent y pídele al agente que cree una tarea. LangGraph invoca la herramienta de tareas en proceso.
   • Servicio Foundry Agent: Selecciona Foundry Agent 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 de SQLite. La herramienta OpenAPI de Foundry siempre utiliza la URL del servidor incrustada en el esquema OpenAPI.

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

   azd up
   

7. Vuelve a ir a la aplicación desplegada y prueba ambos agentes de chat. El navegador solo envía mensajes de texto; no envía un ID de sesión ni de conversación para ninguno de los dos agentes.

Preguntas más frecuentes

• ¿Cómo puedo añadir la generación aumentada mediante recuperación (RAG) al 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 de 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

El gancho AZD postdown también elimina la aplicación Microsoft Entra a nivel de inquilino creada para la autenticación de servicios de aplicaciones.

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?
• LangGraph: inicio rápido
• Biblioteca cliente de proyectos de Azure AI para Python