Tester des assistants à l’aide du kit de développement logiciel (SDK) Microsoft Agent 365

Testez votre assistant localement à l’aide d’Agents Playground avant le déploiement. Ce guide traite de la configuration de votre environnement de développement, de la configuration de l’authentification et de la validation des fonctionnalités de votre assistant avec l’outil de test Agents Playground.

Une fois que votre assistant fonctionne localement, vous pouvez le déployer et le publier pour le tester dans les applications Microsoft 365 telles que Teams.

Configuration requise

Avant de commencer à tester votre assistant, assurez-vous que les prérequis suivants sont en place :

Conditions préalables courantes

• Éditeur de code  : n’importe quel éditeur de code de votre choix. Visual Studio Code est recommandé
• Agents Playground : Installez Agents Playground via l’une des méthodes suivantes :
  • Windows : winget install agentsplayground
  • npm : npm install -g @microsoft/m365agentsplayground
• Interface CLI A365 : obligatoire pour le déploiement et la gestion de l’assistant. Installer l’interface CLI Agent 365
• Accès à l’API LLM : choisissez le service approprié en fonction de la configuration de votre assistant ou de votre fournisseur de modèles préféré :
  • Clé d’API OpenAI : Obtenir votre clé d’API OpenAI
  • Azure OpenAI : Créer et déployer une ressource Azure OpenAI pour obtenir votre clé d’API et votre point de terminaison
• Configuration du portail développeur : Après avoir publié votre agent, vous devez configurer le blueprint de l’agent dans le portail développeur avant de créer des instances. Voir Configurer le plan d’agent dans le portail développeur.

Conditions préalables spécifiques à la langue

Configurer l’environnement de test de l’assistant

Cette section traite de la définition des variables d’environnement, de l’authentification de votre environnement de développement et de la préparation de votre Agent 365 à des fins de test.

La configuration de votre environnement de test de l’assistant suit un flux de travail séquentiel :

1. Configurer votre environnement - Créer ou mettre à jour votre fichier de configuration d’environnement

2. Configuration LLM – Obtenir des clés d’API et configurer les paramètres OpenAI ou Azure OpenAI

3. Configurer l’authentification – Configurer l’authentification agentique

4. Référence sur les variables d’environnement – Configurer les variables d’environnement requises :

   1. Variables d’authentification
   2. Configuration du point de terminaison
   3. Variables d’observabilité
   4. Configuration du serveur d’applications de l’assistant

Une fois ces étapes terminées, vous êtes prêt à commencer à tester votre assistant dans Agents Playground.

Étape 1 : Configurer votre environnement

Configurer votre fichier de configuration :

cp .env.template .env

cp .env.template .env

Étape 2 : configuration de LLM

Configurez les paramètres OpenAI ou Azure OpenAI pour les tests locaux. Ajoutez vos clés API et points de terminaison de service obtenus à partir des prérequis à votre fichier de configuration, ainsi que tous les paramètres de modèle.

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

{
  "AIServices": {
    "AzureOpenAI": {
      "DeploymentName": "", // Deployment (as opposed to model) name of the Azure OpenAI model
      "Endpoint": "", // Endpoint of the Azure OpenAI model deployment
      "ApiKey": "" // API Key of the Azure OpenAI model deployment
    },
    "OpenAI": {
      "ModelId": "", // Model ID of the OpenAI model
      "ApiKey": "" // API Key of the OpenAI model
    },
    "UseAzureOpenAI": true // Flag to use Azure OpenAI vs OpenAI
  }
}

Étape 3 : Configurez l’authentification de votre agent

Choisissez l’une des méthodes d’authentification suivantes pour votre agent :

• Authentification agente - Recommandée pour les scénarios de production ou lorsqu’un agent est disponible.
• Authentification par jeton porteur - À utiliser uniquement pour des scénarios de développement et de test précoces avant la disponibilité des utilisateurs agents.

Authentification agentique

Utilisez la commande CLI A365 a365 config display pour récupérer vos informations d’identification de blueprint d’assistant.

a365 config display -g

Cette commande affiche la configuration du blueprint de votre assistant. Copiez les valeurs suivantes :

Utilisez ces valeurs pour configurer l’authentification agentique dans votre assistant :

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

USE_AGENTIC_AUTH=true
connections__service_connection__settings__clientId=<agentBlueprintId>
connections__service_connection__settings__clientSecret=<agentBlueprintClientSecret>
connections__service_connection__settings__tenantId=<your-tenant-id>

{
  "AgentBluePrint": {
    "Settings": {
      "ClientId": "<agentBlueprintId>",
      "ClientSecret": "<agentBlueprintClientSecret>",
      "TenantId": "<your-tenant-id>"
    }
  }
}

Authentification des jetons du porteur

Pour les scénarios de développement et de test précoces où les utilisateurs d’agents ne sont pas disponibles, vous pouvez utiliser l’authentification par jeton porteur pour tester votre agent.

D’abord, utilisez a365 develop add-permissions pour ajouter les permissions serveur MCP requises à votre application :

a365 develop add-permissions

Ensuite, utilisez a365 develop get-token pour récupérer et configurer les jetons porteurs :

a365 develop get-token

La get-token commande automatique :

• Récupère les jetons porteurs pour tous les serveurs MCP configurés dans votre ToolingManifest.json fichier
• Met à jour vos fichiers de configuration de projet avec la BEARER_TOKEN variable environnement

Étape 4 : Référence sur les variables d’environnement

Terminez la configuration de votre environnement en configurant les variables d’environnement requises suivantes :

• Variables d’authentification – Paramètres requis pour l’authentification agentique
• Configuration du point de terminaison MCP : spécifier le point de terminaison de la plateforme Agent 365
• Variables d’observabilité : activez la journalisation et le suivi distribué
• Configuration du serveur d’application de l’assistant : configurez le port sur lequel votre serveur d’assistant s’exécute

Variables d’authentification

Configurez les paramètres du gestionnaire d’authentification requis pour que l’authentification agentique fonctionne correctement.

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION

# Agentic Authentication Options
agentic_type=agentic
agentic_altBlueprintConnectionName=service_connection
agentic_scopes=ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default

# Set service connection as default
connectionsMap__0__serviceUrl=*
connectionsMap__0__connection=service_connection

{
  "AgentApplication": {
    "StartTypingTimer": false,
    "RemoveRecipientMention": false,
    "NormalizeMentions": false,
    "UserAuthorization": {
      "AutoSignin": false,
      "Handlers": {
        "agentic": {
          "Type": "AgenticUserAuthorization",
          "Settings": {
            "Scopes": [
              "https://graph.microsoft.com/.default"
            ]
          }
        }
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ]
}

Configuration du point de terminaison MCP

La configuration du point de terminaison MCP (Model Context Protocol) est nécessaire pour spécifier le point de terminaison de plateforme Agent 365 auquel votre assistant doit se connecter. Lorsque vous générez le manifeste d’outils qui définit les serveurs d’outil pour votre assistant, vous devez spécifier le point de terminaison de la plateforme MCP. Ce point de terminaison détermine l’environnement (préprod, test ou production) auquel les serveurs d’outils MCP se connectent pour les fonctionnalités d’intégration de Microsoft 365.

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

{
  "profiles": {
    "Sample Agent": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "MCP_PLATFORM_ENDPOINT": "<MCP endpoint>"
      },
      "applicationUrl": "https://localhost:64896;http://localhost:64897"
    }
  }
}

Variables d’observabilité

Configurez ces variables requises pour activer la journalisation et le suivi distribué pour votre assistant. En savoir plus sur les fonctionnalités d’observabilité et les meilleures pratiques

Configuration du serveur d’applications de l’assistant

Configurez le port dans lequel votre serveur d’applications d’assistant s’exécute. Ce paramètre est optionnel et s’applique aux agents Python et JavaScript.

# Server Configuration
PORT=3978

# Server Configuration
PORT=3978

Installer les dépendances et démarrer le serveur d’applications de l’assistant

Une fois votre environnement configuré, vous devez installer les dépendances requises et démarrer votre serveur d’applications d’assistant localement pour les tests.

Installer des dépendances

uv pip install -e .

python <main.py>

uv run python <main.py>

npm install

npm run dev

dotnet restore

dotnet build

dotnet run --launch-profile "Sample Agent with MCP Platform"

Votre serveur d’assistant doit maintenant être en cours d’exécution et prêt à recevoir des demandes des applications Agents Playground ou Microsoft 365.

Tester l’assistant dans Agents Playground

Agents Playground est un outil de test local qui simule l’environnement Microsoft 365 sans nécessiter de configuration complète du locataire. Il s’agit du moyen le plus rapide de valider la logique et les appels d’outils de votre assistant. Pour plus d’informations, consultez Tester avec Agents Playground.

Ouvrez un nouveau terminal (PowerShell sur Windows) et démarrez Agents Playground :

agentsplayground

Cette commande ouvre un navigateur web avec l’interface Agents Playground. L’outil affiche une interface de conversation dans laquelle vous pouvez envoyer des messages à votre assistant.

Test de base

Commencez par vérifier que votre assistant est correctement configuré. Envoyez un message à l’assistant :

What can you do?

L’agent répond avec les instructions qu’il a configurées, en fonction des instructions système et des capacités de votre agent. Cette réponse confirme que :

• Votre assistant s’exécute correctement
• L’assistant peut traiter les messages et répondre
• La communication entre Agents Playground et votre assistant fonctionne

Appels d’outils de test

Après avoir configuré vos serveurs d’outils MCP dans toolingManifest.json (consultez Outils pour obtenir des instructions d’installation), les appels d’outils de test avec des exemples tels que ceux-ci :

Tout d’abord, vérifiez quels outils sont disponibles :

List all tools I have access to

Testez ensuite les appels d’outils spécifiques :

Outils de messagerie

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Réponse attendue : l’assistant envoie un courrier électronique à l’aide du serveur MCP de messagerie et confirme que le message a été envoyé.

Outils de calendrier

List my calendar events for today

Réponse attendue : L’agent récupère et affiche vos événements du calendrier pour le jour en cours.

Outils SharePoint

List all SharePoint sites I have access to

Réponse attendue : l’assistant interroge SharePoint et retourne une liste de sites auxquels vous avez accès.

Vous pouvez afficher les appels d’outils dans :

• Fenêtre de conversation : voir la réponse de l’assistant et les appels d’outils
• Volet Journal : consultez des informations détaillées sur l’activité, y compris les paramètres et les réponses de l’outil

Tester avec les activités de notification

Pendant le développement local, vous pouvez tester des scénarios de notification en simulant des activités personnalisées dans Agents Playground. Cette simulation vous permet de vérifier la gestion des notifications par votre agent avant de la déployer en production.

Avant de tester les activités de notification, vérifiez que vous disposez des points suivants :

• Configuré les serveurs d’outils MCP requis dans votre toolingManifest.json. En savoir plus sur les outils
• Notifications activées pour votre assistant Découvrez comment configurer la notification

Les notifications nécessitent une configuration appropriée des outils et une configuration de notification pour fonctionner correctement. Vous pouvez tester des scénarios tels que des commentaires Notifications par courrier électronique ou Word à l’aide de la fonctionnalité d’activité personnalisée.

Pour envoyer des activités personnalisées :

1. Démarrer votre assistant et Agents Playground
2. Dans Agents Playground, accédez à Simuler une activité>Activité personnalisée
3. Copiez conversationId depuis l’activité (l’ID de conversation change chaque fois que Agents Playground est redémarré)
4. Collez votre code JSON d’activité personnalisée et mettez à jour le champ personal-chat-id avec l’ID de conversation que vous avez copié. Reportez-vous à l’exemple de notification par courrier électronique
5. Sélectionnez Envoyer une activité
6. Afficher le résultat à la fois dans la conversation de conversation et dans le volet Journal

Notification par e-mail

Cette configuration simule un e-mail envoyé à l’agent. Remplacez les valeurs d’espace réservé par vos détails d’assistant réels :

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Afficher les journaux d’observabilité

Pour afficher les journaux d’observabilité pendant le développement local, instrumentez votre assistant avec un code d’observabilité (consultez Observabilité pour obtenir des exemples de code) et configurez les variables d’environnement comme décrit dans les variables d’observabilité. Après configuration, les traces en temps réel s’affichent dans la console montrant :

• Les traces d’appel de l’assistant
• Détails de l’exécution de l’outil
• Les appels d’inférence LLM
• Les messages d’entrée et de sortie
• Utilisation d’un jeton
• Temps de réponse
• Informations sur l’erreur

Ces journaux vous aident à déboguer des problèmes, à comprendre le comportement de l’assistant et à optimiser les performances.

Résolution des problèmes

Cette section fournit des solutions aux problèmes courants que vous pouvez rencontrer lors du test de votre assistant localement.

Problèmes de connexion et d’environnement

Ces problèmes concernent la connectivité réseau, les conflits de ports et les problèmes de configuration de l’environnement qui peuvent empêcher votre assistant de communiquer correctement.

Problèmes de connexion Agents Playground

Symptôme : Agents Playground ne peut pas se connecter à votre assistant

Solutions :

• Vérifier que votre serveur d’assistant est en cours d’exécution
• Vérifiez que les numéros de port correspondent entre votre assistant et Agents Playground
• Assurez-vous qu’aucune règle de pare-feu ne bloque les connexions locales
• Essayez de redémarrer l’assistant et Agents Playground

Version obsolète d’Agents Playground

Symptôme : Erreurs inattendues ou fonctionnalités manquantes dans Agents Playground

Solution : Désinstaller et réinstaller Agents Playground :

winget uninstall agentsplayground
winget install agentsplayground

Conflits au niveau des ports

Symptôme : Erreur indiquant que le port est déjà utilisé

Solution :

• Arrêter toutes les autres instances de votre assistant
• Modifier le port de votre configuration
• Supprimez tous les processus à l’aide du port :

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Impossible d’ajouter DeveloperMCPServer

Symptôme : Erreur lors de la tentative d’ajout de DeveloperMCPServer dans VS Code

Solution : fermez et rouvrez Visual Studio Code, puis réessayez d’ajouter le serveur.

Problèmes d’authentification

Ces problèmes se produisent lorsque votre assistant ne peut pas s’authentifier correctement auprès des services Microsoft 365 ou lorsque les informations d’identification ont expiré ou sont mal configurées.

Jeton du porteur expiré

Symptôme : Erreurs d’authentification ou réponses non autorisées 401

Solution : les jetons du porteur expirent après environ 1 heure. Acquérir un nouveau jeton et mettre à jour votre configuration.

Erreurs d’authentification agentique dans Python

Symptôme : Erreur lors de l’acquisition du jeton d’instance agentique

Solution : vérifiez le ALT_BLUEPRINT_NAME paramètre dans votre .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Problèmes liés à l’outil et à la notification

Ces problèmes impliquent des problèmes liés aux appels d’outils, aux interactions de serveur MCP et à la remise des notifications.

Courrier électronique non reçu

Symptôme : l’assistant indique que le courrier électronique a été envoyé, mais que vous ne le recevez pas

Solutions :

• Vérifiez votre dossier Courrier indésirable/Corbeille
• La remise des courriers électroniques peut être retardée de quelques minutes : patientez jusqu’à 5 minutes
• Vérifiez que l’adresse e-mail du destinataire est correcte
• Vérifier les journaux d’activité de l’assistant pour toutes les erreurs lors de l’envoi de courrier électronique

Réponses aux commentaires Word qui ne fonctionnent pas

Problème connu : le service de notification ne peut pas répondre directement aux commentaires Word. Cette fonctionnalité est en cours de développement.

Les messages n’atteignent pas l’agent

Symptôme : Les messages envoyés à l’agent dans Teams ne sont pas reçus par votre candidature d’agent

Causes possibles :

• Blueprint d’agent non configuré dans le portail développeur
• Problèmes avec Azure Web App (échecs de déploiement, application qui ne tourne pas, erreurs de configuration)
• Instance d’agent mal créée dans Teams

Solutions :

1. Vérifier la configuration du portail développeur :

   Assurez-vous d’avoir complété la configuration du blueprint de l’agent dans le Portail Développeur. Consultez Configurer le plan de l’agent dans le portail développeur pour des étapes détaillées.

2. Check Azure Web App Health :

   Si votre agent est déployé sur Azure, vérifiez que l’application Web fonctionne correctement :

   1. Naviguer vers Azure Portal
   2. Rendez-vous sur la ressource de votre application Web
   3. Vérifierle statut> (devrait afficher « En cours »)
   4. Vérifiez le flux de journal sous Surveillance pour détecter des erreurs d’exécution
   5. Examinez les journaux du Centre de déploiement pour vérifier que le déploiement a réussi
   6. Vérifier la configuration Les>paramètres de l’application contiennent toutes les variables d’environnement requises

3. Vérifier la création d’instance d’agent :

   Assurez-vous d’avoir bien créé l’instance de l’agent dans Microsoft Teams :

   1. Open Microsoft Teams
   2. Allez dans Applications et recherchez votre agent
   3. Vérifier que l’agent apparaît dans les résultats de recherche
   4. Si elle n’est pas trouvée, vérifiez qu’elle est publiée dans le Centre d’administration Microsoft 365 - Agents
   5. Créez une nouvelle instance en sélectionnant Ajouter votre agent
   6. Pour des instructions détaillées, voir Agents à bord

Obtenir de l’aide

Si vous rencontrez des problèmes non abordés dans cette section de résolution des problèmes, explorez ces ressources :

Référentiels du kit de développement logiciel (SDK) Microsoft Agent 365

• Kit de développement logiciel (SDK) Microsoft Agent 365 - Référentiel C# /.NET
• Kit de développement logiciel (SDK) Microsoft Agent 365 - Référentiel Python
• Kit de développement logiciel (SDK) Microsoft Agent 365 - référentiel Node.js/TypeScript
• Référentiel d’exemples du Kit de développement logiciel (SDK) Microsoft Agent 365

Plus de support

• Passez en revue l’exemple de code et la documentation dans les référentiels du kit de développement logiciel (SDK) Microsoft Agent 365
• Envoyer des problèmes via GitHub Issues dans le référentiel approprié

Étapes suivantes

Après avoir testé votre agent localement avec succès, vous êtes prêt à le déployer sur Azure et à le publier sur Microsoft 365 :

• Déployez et publiez des agents : Apprenez à déployer votre agent sur Azure Web App et à le publier dans Microsoft Admin Center, afin de le rendre accessible à votre organisation pour découvrir et créer des instances d’agents dans Microsoft 365.