Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Python)

Dans ce tutoriel, vous allez apprendre à exposer les fonctionnalités d’une application FastAPI via OpenAPI, à l’ajouter en tant qu’outil au service De l’agent Foundry et à interagir avec votre application à l’aide du langage naturel dans le terrain de jeu des agents.

Si votre application web dispose déjà de fonctionnalités utiles, telles que le shopping, la réservation d’hôtels ou la gestion des données, il est facile de rendre ces fonctionnalités disponibles pour un agent IA dans le service De l’agent Foundry. En ajoutant simplement un schéma OpenAPI à votre application, vous permettez à l’agent de comprendre et d’utiliser les fonctionnalités de votre application lorsqu’il répond aux invites des utilisateurs. Cela signifie que tout ce que votre application peut faire, votre agent d’IA peut le faire aussi, avec un minimum d’effort au-delà de la création d’un endpoint OpenAPI pour votre application. Dans ce tutoriel, vous partez d’une application simple d’évaluation de restaurants. À la fin, vous pourrez consulter les évaluations de restaurants, mais aussi créer de nouveaux restaurants et de nouveaux avis avec un agent via l’IA conversationnelle.

Prerequisites

Ce tutoriel suppose que vous travaillez avec l’exemple utilisé dans la section Déployer une application web Python FastAPI avec PostgreSQL sur Azure.

Au minimum, ouvrez l’application d’exemple dans GitHub Codespaces et déployez l’application en exécutant azd up.

Ajouter la fonctionnalité OpenAPI à votre application web

FastAPI inclut déjà la fonctionnalité OpenAPI au chemin par défaut /openapi.json. Vous devez simplement apporter quelques modifications au code existant pour qu’il puisse être appelé à distance par un agent.

1. Ouvrez src/fastapi_app/app.py et recherchez la ligne 24, où l’application FastAPI est déclarée. Remplacez app = FastAPI() par le code suivant :

   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}],
   )
   

   Ce code ajoute des métadonnées au schéma OpenAPI, telles que title et description. Plus important encore, il ajoute l’URL du serveur de l’endpoint d’API.

2. Ouvrez src/fastapi_app/app.py et ajoutez operation_id aux API GET / et /details/{id}. Ces deux API renvoient des documents HTML qu’un agent d’IA peut analyser. Pour toutes les autres API, ajoutez le paramètre 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)
       ...
   

   Vous utilisez include_in_schema=False pour exclure GET /create, POST /add et POST /review/{id}, car ils font partie des fonctionnalités basées sur des formulaires, alors que l’agent d’IA doit soumettre des données JSON.

3. Pour ajouter les fonctionnalités d’ajout de restaurant et d’ajout d’avis via JSON, ajoutez le code suivant :

   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
   

   Ce code ne montre l’API de création que pour des raisons de concision et pour rester cohérent avec l’application d’exemple existante. Si vous le souhaitez, vous pouvez également ajouter d’autres API, comme la mise à jour et la suppression.

4. Démarrez le serveur de développement pour l’application d’exemple avec les commandes suivantes :

   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. Sélectionnez Ouvrir dans le navigateur.

6. Affichez le schéma OpenAPI en ajoutant /openapi.json à l’URL, qui est le chemin par défaut utilisé par FastAPI pour servir le schéma.

7. De retour dans le terminal du codespace, déployez vos modifications en validant (commit) vos changements (méthode GitHub Actions) ou exécutez azd up (méthode Azure Developer CLI).

8. Une fois vos modifications déployées, accédez à https://<your-app's-url>/openapi.json et copiez le schéma pour plus tard.

Créer un agent dans Microsoft Foundry

1. Dans le portail Foundry, dans le menu supérieur droit, sélectionnez New Foundry.

2. S’il s’agit de votre première fois dans le nouveau portail Foundry, sélectionnez le nom du projet et sélectionnez Créer un projet.

3. Donnez un nom à votre projet, puis sélectionnez Créer.

4. Sélectionnez Démarrer la génération, puis Créer un agent.

5. Donnez un nom à votre agent et sélectionnez Créer. Lorsque l’agent est prêt, vous devriez voir l’agent playground.

   Notez les modèles que vous pouvez utiliser et les régions disponibles.

6. Dans l’agent playground, développez Tools (Outils) et sélectionnez Add (Ajouter)>Custom (Personnalisé)>OpenAPI tool (Outil OpenAPI)>Create (Créer).

7. Donnez un nom à l’outil et une description. Dans la zone de schéma OpenAPI 3.0+ , collez le schéma que vous avez copié précédemment.

8. Sélectionnez Créer un outil.

9. Cliquez sur Enregistrer.

Tester l’agent

1. Dans Instructions, donnez quelques instructions simples, telles que « Utilisez l’outil restaurantReview pour aider à gérer les avis des restaurants ».

2. Discutez avec l’agent à l’aide des suggestions d’invite suivantes :

   • « Montre-moi la liste des avis de restaurants. »
   • « Crée un restaurant. Utilise ton imagination pour les détails. »
   • « Je n’ai pas aimé la nourriture dans ce restaurant. Crée un avis 2 étoiles. »

   

Bonnes pratiques de sécurité

Lorsque vous exposez des API via OpenAPI dans Azure App Service, suivez ces bonnes pratiques de sécurité :

• Authentification et autorisation : Protégez vos points de terminaison OpenAPI avec l’authentification Microsoft Entra. Pour obtenir des instructions pas à pas, consultez Points de terminaison OpenAPI sécurisés pour le service de l'agent Foundry. Vous pouvez également protéger vos points de terminaison derrière Gestion des API Azure avec l’ID Microsoft Entra et garantir que seuls les utilisateurs ou agents autorisés peuvent accéder aux outils.
• Valider les données d’entrée : validez toujours les données entrantes afin d’éviter les entrées invalides ou malveillantes. Pour les applications Python, utilisez des bibliothèques comme Pydantic pour appliquer des règles de validation des données via des modèles de schéma de requête dédiés (tels que RestaurantCreate et ReviewCreate). Consultez leur documentation pour connaître les bonnes pratiques et les détails d’implémentation.
• Utiliser HTTPS : l’exemple repose sur Azure App Service, qui impose HTTPS par défaut et fournit des certificats TLS/SSL gratuits pour chiffrer les données en transit.
• Limiter CORS : limitez le Cross-Origin Resource Sharing (CORS) aux seuls domaines de confiance. Pour plus d’informations, consultez Activer CORS.
• Appliquer une limitation de débit : utilisez API Management ou un middleware personnalisé pour prévenir les abus et les attaques par déni de service.
• Masquer les endpoints sensibles : évitez d’exposer des API internes ou d’administration dans votre schéma OpenAPI.
• Passer en revue le schéma OpenAPI : assurez-vous que votre schéma OpenAPI ne divulgue pas d’informations sensibles (telles que des URL internes, des secrets ou des détails d’implémentation).
• Maintenir les dépendances à jour : mettez régulièrement à jour les packages NuGet et surveillez les avis de sécurité.
• Surveiller et journaliser l’activité : activez la journalisation et surveillez les accès afin de détecter toute activité suspecte.
• Utiliser des identités managées : lorsque vous appelez d’autres services Azure, utilisez des identités managées plutôt que des informations d’identification codées en dur.

Pour plus d’informations, consultez les sections Sécuriser votre application App Service et Bonnes pratiques de sécurité pour les API REST.

Étape suivante

Vous avez maintenant activé l’utilisation de votre application App Service en tant qu’outil par Foundry Agent Service et interagir avec les API de votre application via le langage naturel dans le terrain de jeu des agents. À partir de là, vous pouvez continuer à ajouter des fonctionnalités à votre agent dans le portail Foundry, l’intégrer à vos propres applications à l’aide du Kit de développement logiciel (SDK) Microsoft Foundry ou de l’API REST, ou la déployer dans le cadre d’une solution plus grande. Les agents créés dans Microsoft Foundry peuvent être exécutés dans le cloud, intégrés à des chatbots ou incorporés dans des applications web et mobiles.

Pour passer à l’étape suivante et apprendre à exécuter votre agent directement au sein d’Azure App Service, consultez le tutoriel suivant :

Plus de ressources

• Intégrer l’IA à vos applications Azure App Service
• Qu’est-ce que le Service de l’agent Foundry ?