Adición de una aplicación de App Service como herramienta en Foundry Agent Service (Python)

En este tutorial, aprenderá a exponer la funcionalidad de una aplicación FastAPI a través de OpenAPI, agregarla como una herramienta al servicio Foundry Agent y interactuar con la aplicación mediante lenguaje natural en el área de juegos de agentes.

Si la aplicación web ya tiene características útiles, como compras, reservas de hoteles o administración de datos, es fácil hacer que esas funcionalidades estén disponibles para un agente de IA en foundry Agent Service. Con solo agregar un esquema OpenAPI a su aplicación, permite que el agente comprenda y utilice las capacidades de su aplicación cuando responde a las solicitudes de los usuarios. Esto significa que todo lo que puede hacer su aplicación, también lo puede hacer su agente de IA, con un esfuerzo mínimo más allá de crear un punto de conexión OpenAPI para su aplicación. En este tutorial, comienza con una sencilla aplicación de valoración de restaurantes. Al final, podrá ver las valoraciones de los restaurantes, así como crear nuevos restaurantes y nuevas reseñas con un agente a través de la IA conversacional.

Prerrequisitos

Este tutorial asume que está trabajando con el ejemplo utilizado en Implementar una aplicación web Python FastAPI con PostgreSQL en Azure.

Como mínimo, abra la aplicación de muestra en GitHub Codespaces e implemente la aplicación ejecutando azd up.

Agregue la funcionalidad OpenAPI a su aplicación web

FasAPI ya contiene la funcionalidad OpenAPI en la ruta predeterminada /openapi.json. Solo necesita realizar algunos cambios en el código existente para que un agente pueda llamarlo de forma remota.

1. Abra src/fastapi_app/app.py y busque la línea 24, donde se declara la aplicación FastAPI. Reemplaza app = FastAPI() con el siguiente código:

   if os.getenv("WEBSITE_HOSTNAME"):
       server_url = f"https://{os.getenv('WEBSITE_HOSTNAME')}"
   else:
       server_url = "http://localhost:8000"
   app = FastAPI(
       title="Restaurant Review API",
       version="1.0.0",
       description="Can show restaurant ratings HTML and add new restaurants and reviews.",
       servers=[{"url": server_url}],
   )
   

   Este código agrega metadatos al esquema OpenAPI, como title y description. Lo más importante es que agrega la URL del servidor del punto de conexión de la API.

2. Abra src/fastapi_app/app.py, agregue operation_id a las / y /details/{id} API GET. Estas dos API devuelven documentos HTML que un agente de IA puede analizar. Para todas las demás API, agregue el parámetro include_in_schema=False.

   @app.get("/", response_class=HTMLResponse, operation_id="getRestaurantsWithRatingsHtml")
       ...    
   
   @app.get("/create", response_class=HTMLResponse, include_in_schema=False)
       ...    
   
   @app.post("/add", response_class=RedirectResponse, include_in_schema=False)
       ...
   
   @app.get("/details/{id}", response_class=HTMLResponse, operation_id="getRestaurantDetails")
       ...    
   
   @app.post("/review/{id}", response_class=RedirectResponse, include_in_schema=False)
       ...
   

   Se utiliza include_in_schema=False para excluir GET /create, POST /add y POST /review/{id} porque forman parte de la funcionalidad basada en formularios, mientras que el agente de IA necesita enviar datos JSON.

3. Para agregar la funcionalidad de agregar restaurante y agregar reseña usando JSON, agregue el siguiente código:

   from typing import Optional
   from fastapi import Body, HTTPException
   
   @app.post("/api/restaurants", response_model=Restaurant, status_code=status.HTTP_201_CREATED, operation_id="createRestaurant")
   async def create_restaurant_json(
       name: str = Body(...),
       street_address: str = Body(...),
       description: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       restaurant = Restaurant(name=name, street_address=street_address, description=description)
       session.add(restaurant)
       session.commit()
       session.refresh(restaurant)
       return restaurant
   
   
   @app.post("/api/restaurants/{id}/reviews", response_model=Review, status_code=status.HTTP_201_CREATED,operation_id="createReview")
   async def create_review_for_restaurant_json(
       id: int,
       user_name: str = Body(...),
       rating: Optional[int] = Body(None),
       review_text: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       if not session.get(Restaurant, id):
           raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Restaurant not found")
   
       review = Review(
           restaurant=id, user_name=user_name, rating=rating, review_text=review_text, review_date=datetime.now()
       )
       session.add(review)
       session.commit()
       session.refresh(review)
       return review
   

   Este código solo muestra la API de creación por motivos de brevedad y para mantener la paridad con la aplicación de ejemplo existente. Si lo desea, también puede agregar otras API, como actualizar y eliminar.

4. Inicie el servidor de desarrollo para la aplicación de ejemplo con los siguientes comandos:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r src/requirements.txt
   pip install -e src
   python3 src/fastapi_app/seed_data.py
   python3 -m uvicorn fastapi_app:app --reload --port=8000
   

5. Seleccione Abrir en el explorador.

6. Para ver el esquema OpenAPI, agregue /openapi.json a la URL, que es la ruta predeterminada que utiliza FastAPI para servir el esquema.

7. De vuelta en la terminal del codespace, implemente los cambios confirmándolos (método de Acciones de GitHub) o ejecute azd up (método Azure Developer CLI).

8. Una vez implementados los cambios, vaya a https://<your-app's-url>/openapi.json y copie el esquema para más adelante.

Creación de un agente en Microsoft Foundry

1. En el portal de Foundry, en el menú superior derecho, seleccione Nuevo Foundry.

2. Si esta es la primera vez en el nuevo portal de Foundry, seleccione el nombre del proyecto y seleccione Crear nuevo proyecto.

3. Asigne un nombre al proyecto y seleccione Crear.

4. Seleccione Iniciar compilación y, a continuación, Crear agente.

5. Asigne un nombre al agente y seleccione Crear. Cuando el agente esté listo, debería ver el área de juegos del agente.

   Tenga en cuenta los modelos que puede utilizar y las regiones disponibles.

6. En el área de juegos del agente, expanda Herramientas y seleccione Agregar>la herramienta>OpenAPI personalizada>Crear.

7. Asigne un nombre a la herramienta y una descripción. En el cuadro esquema OpenAPI 3.0+ , pegue el esquema que copió anteriormente.

8. Seleccione Crear herramienta.

9. Haga clic en Guardar.

Prueba del agente

1. En Instrucciones, proporcione algunas instrucciones sencillas, como "Use la herramienta restaurantReview para ayudar a administrar las opiniones de restaurantes".

2. Chatee con el agente con las siguientes sugerencias de aviso:

   • "Muéstrame la lista de reseñas de restaurantes".
   • "Cree un restaurante. Use su imaginación para los detalles".
   • "No me gustó la comida en este restaurante. Cree una revisión de 2 estrellas".

   

Procedimientos recomendados de seguridad

Al exponer API a través de OpenAPI en Azure App Service, siga estas prácticas recomendadas de seguridad:

• Autenticación y autorización: proteja los puntos de conexión de OpenAPI con la autenticación de Microsoft Entra. Para obtener instrucciones paso a paso, consulte Secure OpenAPI endpoints for Foundry Agent Service (Protección de puntos de conexión de OpenAPI para el servicio de agente foundry). También puede proteger los puntos de conexión detrás de Azure API Management con el identificador de Microsoft Entra y asegurarse de que solo los usuarios o agentes autorizados puedan acceder a las herramientas.
• Validar los datos introducidos: valide siempre los datos entrantes para evitar entradas no válidas o maliciosas. Para aplicaciones Python, utilice bibliotecas como Pydantic para aplicar reglas de validación de datos con modelos de esquema de solicitud dedicados (como RestaurantCreate y ReviewCreate). Consulte su documentación para conocer las mejores prácticas y los detalles de implementación.
• Utilice HTTPS: la muestra se basa en Azure App Service, que aplica HTTPS de forma predeterminada y proporciona certificados TLS/SSL gratuitos para cifrar los datos en tránsito.
• Limitar CORS: restringir el intercambio de recursos entre orígenes (CORS) solo a dominios de confianza. Para obtener más información, consulte Habilitar CORS.
• Aplicar limitación de velocidad: utilice API Management o middleware personalizado para evitar abusos y ataques de denegación de servicio.
• Ocultar puntos de conexión confidenciales: evite exponer API internas o administrativas en su esquema OpenAPI.
• Revisar el esquema OpenAPI: asegúrese de que su esquema OpenAPI no revele información confidencial (como URL internas, secretos o detalles de implementación).
• Mantenga las dependencias actualizadas: actualice periódicamente los paquetes NuGet y supervise los avisos de seguridad.
• Supervisión y actividad de registro: Habilite el registro y supervise el acceso para detectar actividades sospechosas.
• Utilice identidades administradas: Cuando llame a otros servicios de Azure, utilice identidades administradas en lugar de credenciales codificadas.

Para obtener más información, consulte Proteger la aplicación de App Service y Procedimientos recomendados para la seguridad de la API REST.

Paso siguiente

Ahora ha habilitado la aplicación de App Service para que se use como herramienta en Foundry Agent Service e interactúe con las API de la aplicación a través de lenguaje natural en el área de juegos de agentes. Desde aquí, puede seguir agregando características al agente en el portal de Foundry, integrarla en sus propias aplicaciones mediante el SDK de Microsoft Foundry o la API REST, o implementarla como parte de una solución más grande. Los agentes creados en Microsoft Foundry se pueden ejecutar en la nube, integrados en bots de chat o insertados en aplicaciones web y móviles.

Para dar el siguiente paso y aprender a ejecutar su agente directamente en Azure App Service, consulte el siguiente tutorial:

Más recursos

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