Démarrage rapide : Configurer et exécuter l’exemple d’assistant Agent Framework Python

Dans ce guide de démarrage rapide, parcourez la configuration d’un Agent Framework Python fonctionnel utilisant l’outillage d’Agent 365, les notifications, l’observabilité, ainsi que le test de l’assistant à l’aide d’Agents Playground et de Teams.

Configuration requise

• Si vous envisagez d’utiliser Visual Studio Code, vous devez installer .NET. (.NET 8.0 est recommandé.)

• Python 3.11 ou ultérieur installé

• Gestionnaire de packages UV installé. Installez-le dans un terminal à l’aide de pip install uv.

• Dépendances du kit d’outils des assistants Microsoft / Agent Framework

  L’exemple utilisé dans le guide de démarrage s’appuie sur les bibliothèques Agent Framework fournies via le kit d’outils Microsoft 365 Agents (ATK). Ces éléments seront installés automatiquement lorsque vous utiliserez l’extension Agents Toolkit dans VS Code pour générer l’exemple, ou vous pouvez installer le package manuellement à l’aide de la commande suivante :

  uv pip install -e . --find-links ../dist --pre
  

• Accès à GitHub

• Un projet Assistant IA existant. Ce démarrage rapide utilise un exemple d’assistant Agent 365 à partir du kit d’outils Microsoft 365 Agent également appelé ATK dans VS Code.

• CLI A365

• Authentification d’identité de l’assistant

Configurer l’exemple Agent framework + Python à partir du kit d’outils Microsoft 365 Agents

Pour tout préparer, installez le kit d’outils Microsoft 365 Agents dans VS Code, ouvrez la galerie d’exemples et générez la structure de l’exemple Agent Framework + Python en local afin de pouvoir le configurer et l’exécuter ultérieurement. Les captures d’écran suivantes montrent ce à quoi vous pouvez vous attendre au fil de la procédure.

1. Ouvrez Visual Studio Code, puis ouvrez le panneau ExtensionsCtrl+Maj+X.

2. Dans la barre de recherche, saisissez « Agents Toolkit ».
   Vous devez voir le résultat affiché dans la capture d’écran ici :

   

3. Sélectionnez Kit d’outils Microsoft 365 Agents.

4. Cliquez sur Installer.

   VS Code affiche une vue des détails de l’extension similaire à celle-ci :

   

5. Une fois installé, l’icône Kit d’outils M365 Agents s’affiche dans la barre de navigation de gauche.

6. Sélectionnez-la pour ouvrir l’écran d’accueil.

   Vous devez maintenant voir des options telles que Générer un assistant déclaratif, Créer un assistant/une application et Afficher des exemples, comme illustré ici :

   

7. Sélectionnez Afficher des exemples.

8. Faites défiler la liste des exemples pour rechercher l’exemple d’assistant Agent Framework + Python .

9. Sélectionnez-le.

   Vous verrez deux choix : Créer (structurer localement) ou Afficher sur GitHub.

10. Cliquez sur Créer.

    

11. Lorsque vous y êtes invité(e), sélectionnez un dossier sur votre ordinateur où l’exemple doit être généré. Par exemple : C:\A365-python-sample

    Le kit d'outils génère automatiquement l’exemple Agent Framework + Python dans un sous-dossier (tel que sample_agent), puis l’ouvre automatiquement dans VS Code.

    Une fois la génération du projet terminée, vous disposez d’un projet d’assistant Python basé sur Agent Framework, entièrement fonctionnel sur votre appareil

12. Installez les packages Agent 365 requis

    Avant d’exécuter l’exemple, ouvrez le fichier package.json dans votre projet et vérifiez que toutes les dépendances Agent 365 et Agent Framework requises sont répertoriées. L’exemple généré par le kit d’outils Microsoft 365 Agents inclut déjà ces entrées.

    Une fois que vous avez examiné le fichier package.json, installez le tout en exécutant la commande suivante :

    uv pip install -e
    

    Cette étape télécharge l’ensemble des bibliothèques du SDK Agent 365, les dépendances d’Agent Framework, les composants d’hébergement, ainsi que toutes les autres dépendances définies dans l’exemple.

13. Après l’installation, vérifiez que le projet se construit et s’exécute correctement en lançant le serveur de développement à l’aide de cette commande :

    uv run python start_with_generic_host.py
    

Ajouter des outils Microsoft 365 (serveurs MCP)

Vous pouvez explorer et gérer des serveurs MCP à l’aide des commandes a365 develop de la CLI.

Lorsque vous travaillez avec des serveurs mCP, vous pouvez :

• Découvrir quels serveurs MCP sont disponibles
• Ajouter un ou plusieurs serveurs MCP à votre configuration de l’assistant
• Examiner les serveurs MCP actuellement configurés
• Supprimer les serveurs MCP dont vous n’avez plus besoin

Une fois les serveurs MCP ajoutés, le manifeste d’outillage de votre assistant s’enrichit pour inclure des entrées similaires à :

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

Découvrez comment ajouter et gérer des outils

Abonnement et gestion des notifications

L’exemple d’assistant s’abonne à toutes les notifications du SDK Agent 365 au moyen de onAgentNotification("*") et les achemine vers un gestionnaire unique. Ce gestionnaire permet à l’assistant de réagir à des événements en arrière-plan ou à des événements système, et pas uniquement aux messages provenant directement de l’utilisateur.

Découvrez comment notifier des assistants

Le code suivant montre comment la notification est configurée dans le fichier agent.py.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

Observabilité

Cet extrait de code montre les modifications minimales nécessaires pour activer l’observabilité dans l’exemple. Il initialise le SDK d’observabilité Agent 365 et encapsule chaque invocation d’assistant dans un InferenceScope, afin que les entrées, les sorties et les métadonnées puissent être capturées automatiquement.

Le code suivant montre un exemple d’observabilité rationalisée dans le fichier agent.py.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

Ce code constitue la configuration complète de l’observabilité requise pour l’exemple Python + Agent Framework. En savoir plus sur l’observabilité

Tester votre assistant

Définissez les variables d’environnement requises, choisissez un mode d’authentification et démarrez l’assistant en local. Vous pouvez tout tester de bout en bout avec Agents Playground sans avoir besoin d’un locataire Microsoft 365, sauf si vous souhaitez publier l’assistant et l’utiliser dans des applications comme Teams ou Outlook.

Vue d’ensemble des étapes de test

• Ajoutez vos clés API et vos paramètres de modèle à un fichier .env afin que l’exemple puisse communiquer avec un grand modèle de langage.
• Choisissez votre mode d’authentification. Pour le développement en local, l’exemple prend en charge l’authentification agentique à l’aide des valeurs créées à partir de votre blueprint d’assistant.
• Démarrer l’assistant localement, ce qui l’expose à des outils tels qu’Agents Playground.
• Utiliser Agents Playground pour tester les messages, les outils et les notifications sans configurer un locataire ou déployer quoi que ce soit.
• Lorsque vous serez prêt pour un comportement en conditions réelles, publiez dans un locataire Microsoft 365 et testez l’assistant dans Teams, Outlook ou d’autres surfaces Microsoft 365.

En savoir plus sur les tests

Publier votre agent

Lorsque votre assistant est prêt pour de véritables expériences Microsoft 365, comme des conversations Teams, des messages Outlook ou des @mentions dans Word, vous le publiez dans un locataire Microsoft 365. La commande Agent 365 CLIpublish gère l’empaquetage : elle met à jour votre manifeste, regroupe tous les éléments et charge l’assistant dans le Centre d’administration Microsoft.

Lors de la publication, révisez et personnalisez le nom, la description, les icônes et la version de l’assistant avant de finaliser le chargement. Une fois publié, votre assistant devient découvrable et installable au sein du locataire.

Vous pouvez voir les assistants publiés ici : https://admin.cloud.microsoft/#/agents/all

En savoir plus sur le flux de travail complet et les instructions pas à pas