Tutoriel : Créer une application web agentique dans Azure App Service avec LangGraph ou Foundry Agent Service (Python)

Ce didacticiel montre comment ajouter une fonctionnalité agentique à une application CRUD FastAPI pilotée par les données existante. Cela utilise deux approches différentes : LangGraph et Foundry Agent Service.

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 relativement simple d’ajouter des fonctionnalités d’agent à votre application web en encapsulant ces fonctionnalités dans un plug-in (pour LangGraph) ou en tant que point de terminaison OpenAPI (pour le service De l’agent Foundry). Dans ce tutoriel, vous commencez par une application de liste de tâches simple. À la fin, vous pourrez créer, mettre à jour et gérer des tâches avec un agent dans une application App Service.

LangGraph et Foundry Agent Service vous permettent de créer des applications web agentiques avec des fonctionnalités basées sur l’IA. LangGraph est similaire à Microsoft Agent Framework et est un SDK. Le tableau suivant présente quelques-uns des points à prendre en compte et des adaptations :

Dans ce tutoriel, vous allez apprendre à :

Prerequisites

• Un compte Azure avec un abonnement actif : créez gratuitement un compte.
• Compte GitHub pour utiliser GitHub Codespaces - En savoir plus sur GitHub Codespaces.

Ouvrir l’exemple avec Codespaces

Le moyen le plus simple de commencer consiste à utiliser GitHub Codespaces, qui fournit un environnement de développement complet avec tous les outils requis préinstallés.

1. Accédez au référentiel GitHub à l’adresse https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.

2. Sélectionnez le bouton Code, sélectionnez l’onglet Codespaces, puis sélectionnez Créer un codespace sur l’espace principal.

3. Attendez quelques instants que votre Codespace s’initialise. Lorsqu’il est prêt, un environnement de développement entièrement configuré s’affiche dans votre navigateur.

4. Exécutez l’application localement :

   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. Lorsque vous voyez Votre application s’exécutant sur le port 3000 est disponible, sélectionnez Ouvrir dans le navigateur et ajoutez quelques tâches.

   Les agents ne sont pas entièrement configurés, donc ils ne fonctionnent pas encore. Vous les configurerez ultérieurement.

Examinez le code de l’agent

Les deux approches utilisent le même modèle d’implémentation, où l’agent est initialisé au démarrage de l’application et répond aux messages utilisateur par des demandes 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="",
)

Déployer l’exemple d’application

Le dépôt d’exemples contient un modèle Azure Developer CLI (AZD), qui crée une application App Service et déploie votre application d’exemple. L’identité managée attribuée au système App Service est conservée pour les appels Azure AI sortants. Une identité managée distincte attribuée par l’utilisateur et une identifiante d’identité fédérée permettaient à l’authentification App Service d’agir comme l’application Microsoft Entra générée sans secret client.

1. Dans le terminal, connectez-vous à Azure en utilisant la CLI de développeur Azure :

   azd auth login
   

   Suivez les instructions pour terminer le processus d’authentification.

2. Déploie l’application Azure App Service en utilisant le modèle AZD :

   azd up
   

3. Lorsque vous y êtes invité, fournissez les réponses suivantes :

   Question	Réponse
   Entrez un nom pour le nouvel environnement :	Tapez un nom unique.
   Sélectionnez un abonnement Azure à utiliser :	Sélectionnez l’abonnement.
   Choisissez un groupe de ressources à utiliser :	Sélectionnez Créer un groupe de ressources.
   Sélectionnez un emplacement dans lequel créer le groupe de ressources :	Sélectionnez Suède Centre.
   Entrez un nom pour le nouveau groupe de ressources :	Tapez Entrée.

4. Dans la sortie AZD, retrouvez l’URL de votre application et accédez-y dans le navigateur. Copiez également la valeur de l’audience de l’identité managée Foundry OpenAPI pour une utilisation ultérieure. Le résultat se présente ainsi :

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

5. Lorsque Microsoft vous le demande, connectez-vous en utilisant un compte dans le locataire de déploiement et vérifiez que la liste des tâches se charge.

6. Dans le même navigateur authentifié, ajoutez /openapi.json à l’URL du point de terminaison App Service. Copiez ou sauvegardez le schéma OpenAPI généré pour plus tard.

   Note

   L’authentification par service d’applications renvoie une redirection HTTP 302 pour les requêtes navigateur non authentifiées. Cet exemple contient à la fois une interface utilisateur de navigateur et des API, ce qui permet à la redirection d’offrir une expérience de connexion utilisable. Les applications uniquement API utilisent généralement HTTP 401 à la place.

Créer et configurer la ressource Microsoft Foundry

Attribuer les autorisations nécessaires

Configurer des variables de connexion dans votre exemple d’application

1. Ouvrez .env. À l’aide des valeurs que vous avez copiées précédemment à partir du portail Foundry, configurez les variables suivantes :

   • LangGraph
   • Service de l’agent Foundry

   Variable	Descriptif
   AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint (copié depuis la page d’accueil du portail Foundry).
   AZURE_OPENAI_DEPLOYMENT_NAME	Nom du modèle dans le déploiement (copié depuis le model playground dans le nouveau portail Foundry).

   Note

   Pour simplifier le tutoriel, vous allez utiliser ces variables dans .env au lieu de les remplacer par des paramètres d’application dans App Service.

   Note

   Pour simplifier le tutoriel, vous allez utiliser ces variables dans .env au lieu de les remplacer par des paramètres d’application dans App Service.

   Les valeurs dans .env configurent la connexion sortante de l’application vers Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID configure la connexion OpenAPI entrante distincte de Foundry vers App Service et est stocké dans l’environnement AZD.

2. Se connecter à Azure avec Azure CLI :

   az login
   

   Cela permet à la bibliothèque cliente Azure Identity dans l’exemple de code de recevoir un jeton d’authentification pour l’utilisateur connecté. N’oubliez pas que vous avez ajouté le rôle requis pour cet utilisateur précédemment.

3. Exécutez l’application localement :

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

4. Lorsque vous voyez Votre application s’exécutant sur le port 3000 est disponible, sélectionnez Ouvrir dans le navigateur.

5. Validez les deux pivots séparément :

   • LangGraph :Sélectionnez LangGraph Agent, et demandez à l’agent de créer une tâche. LangGraph appelle l’outil de tâche en cours de traitement.
   • Service Foundry Agent : Sélectionnez le Foundry Agent, puis demandez à l’agent de créer une tâche. L’agent Foundry à distance appelle le point de terminaison /api/tasks déployé et protégé avec une identité gérée.

   La tâche créée par l’agent Foundry apparaît dans l’instance déployée du service applicatif, et non dans la base de données SQLite locale. L’outil OpenAPI de Foundry utilise toujours l’URL serveur intégrée dans le schéma OpenAPI.

6. De retour dans le codespace GitHub, déployez les modifications apportées à votre application.

   azd up
   

7. Naviguez à nouveau vers l’application déployée et testez les deux agents de chat. Le navigateur n’envoie que du texte de message ; il n’envoie ni d’identifiant de session ni d’identifiant de conversation pour aucun des deux agents.

Questions fréquemment posées

• Comment ajouter la génération augmentée par récupération (RAG) à l’agent Foundry ?

Comment ajouter la génération augmentée par récupération (RAG) à l’agent Foundry ?

Cette consigne s’applique au parcours Foundry Agent Service de ce tutoriel. Cela ne modifie pas les implémentations de LangGraph, Noyau sémantique ou Microsoft Agent Framework affichées dans l'autre onglet.

Créez ou sélectionnez une base de connaissances Foundry IQ, puis connectez cette base à l’agent du service d’agent Foundry. La connexion est mise à la disposition de l’agent sous la forme d’un outil de connaissances MCP géré.

Le code d’App Service continue d’invoquer le même agent en utilisant son nom via son client Foundry existant et agent_reference. L'application web n'a pas besoin d'une intégration directe Recherche Azure AI ni de son propre client MCP. Si l’interface affiche les sources, traitez les annotations de citation retournées par l’agent.

Nettoyer les ressources

Lorsque vous avez terminé avec l’application, vous pouvez supprimer les ressources App Service afin d’éviter des coûts supplémentaires :

azd down --purge

Le hook AZD postdown supprime également l’application Microsoft Entra créée au niveau du locataire pour l’authentification App Service.

Ensuite, supprime la ressource Foundry si tu l’as créée séparément.

Plus de ressources

• Intégrer l’IA à vos applications Azure App Service
• Qu’est-ce que le Service de l’agent Foundry ?
• LangGraph - Démarrage rapide
• Bibliothèque de client Azure AI Projects pour Python