Déboguer les agents Foundry hébergés v2 avec Python

Introduction

La nouvelle commande azd ai agent init provisionne un projet Python ciblant Microsoft Foundry. C’est une excellente façon de démarrer rapidement, mais un point de friction apparaît immédiatement : appuyer sur F5 dans Visual Studio Code ne fonctionne pas. Le projet ne contient pas le fichier de configuration VS Code nécessaire au débogage.

Heureusement, c’est très simple à corriger.

La solution

Un fichier de configuration doit être ajouté dans le dossier .vscode à la racine de l’espace de travail.

launch.json

Ce fichier configure le débogueur. Il définit la configuration de lancement, pointe vers le point d’entrée de l’agent, et surtout injecte les variables d’environnement nécessaires pour connecter l’agent au projet Microsoft Foundry.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Agent",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/src/seattle-hotel-agent/main.py",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}/src/seattle-hotel-agent",
            "envFile": "${workspaceFolder}/.env",
            "justMyCode": true,
            "env": {
                "FOUNDRY_PROJECT_ENDPOINT": "https://foundry-project.services.ai.azure.com/api/projects/environment-name"
            }
        }
    ]
}

Remarque : Plusieurs valeurs dans launch.json doivent être adaptées à votre environnement :
seattle-hotel-agent : remplacez par le nom de votre agent.
environment-name : remplacez par le nom de l’environnement créé par azd (correspond généralement au nom du groupe de ressources ou de l’agent).
foundry-project : remplacez par le nom de votre projet Microsoft Foundry (visible dans le portail sous les points de terminaison du projet).

Invoquer l’agent

Une fois la configuration en place, posez vos points d’arrêt n’importe où dans le code de l’agent et appuyez sur F5 pour démarrer le débogueur. L’agent se lance localement et attend une invite.

Pour envoyer une invite à l’agent qui s’exécute en local, utilisez la commande suivante :

azd ai agent invoke "mon invite" --local

Les points d’arrêt sont déclenchés normalement et vous pouvez inspecter les variables, avancer pas à pas dans le code et diagnostiquer tout problème, exactement comme avec n’importe quelle autre application Python.

Conclusion

L’absence de prise en charge native du débogage VS Code pour les templates azd ai agent init est un léger inconvénient qui se règle rapidement avec un seul fichier de configuration. Une fois en place, l’expérience de débogage complète est disponible et vous pouvez itérer rapidement sur la logique de votre agent. J’espère que cela vous fera gagner du temps !