Ajouter et gérer les outils

Le module Tooling permet aux développeurs de découvrir, configurer et intégrer des serveurs MCP (Model Context Protocol) dans des workflows d’assistant IA. Les serveurs MCP exposent des fonctionnalités externes en tant qu’outils que les assistants IA peuvent appeler. Pour obtenir une vue d’ensemble des serveurs d’outils disponibles, consultez Serveurs d’outils Agent 365.

Illustre le flux de demande et de réponse

Vue d’ensemble

L’intégration d’Agent 365 Tooling respecte un workflow en quatre étapes :

  1. Configurer des serveurs MCP : utilisez l’interface CLI Agent 365 pour découvrir et ajouter des serveurs MCP
  2. Générer le manifeste - la CLI crée ToolingManifest.json dans votre dossier de projet avec les configurations du serveur.
  3. Appliquer des permissions au blueprint – Un administrateur général accorde des permissions OAuth2 au blueprint de l’assistant en exécutant la commande a365 setup all (configuration initiale) ou a365 setup permissions mcp (si le blueprint existe déjà). Dans tous les cas, la commande lit ToolingManifest.json et nécessite le consentement de l’administrateur. Cette étape est toujours séparée de l’ajout de serveurs au manifeste.
  4. Intégrer dans le code : chargez le manifeste et inscrivez des outils auprès de votre orchestrateur.
  5. Appeler des outils : l’assistant appelle des outils pendant l’exécution pour effectuer des opérations.

Configuration requise

Avant de configurer les serveurs MCP, assurez-vous d’avoir :

  • La CLI Agent 365 installée et configurée
  • Sdk .NET 8.0 ou version ultérieure – Télécharger
  • Privilèges du rôle Administrateur général dans votre client Microsoft 365

Configuration de l’identité de l’assistant

Si vous utilisez l’authentification agentique, effectuez le processus d’inscription de l’assistant pour créer votre identité d’assistant avant de configurer des serveurs MCP. Cela crée l’identifiant d’assistant Entra et l’utilisateur assistant qui permet à votre assistant d’authentifier et d’accéder aux outils MCP.

Configuration de l’authentification OBO

Si vous utilisez l’authentification On-Behalf-Of (OBO) plutôt que l’authentification agentique, votre assistant peut accéder aux outils MCP en utilisant des permissions utilisateur déléguées sans identité d’assistant utilisateur. Dans le flux OBO, l’assistant échange le jeton délégué d’un utilisateur pour effectuer des actions en son nom.

Pour plus d’informations sur le fonctionnement du flux OBO, consultez les flux d’authentification. Pour un exemple complet d’implémentation, consultez l’exemple d’autorisation OBO dans le Microsoft 365 Agents SDK.

Configurer le principal de service

Exécutez ce script de configuration UNIQUE pour créer le principal de service pour les outils Agent 365 dans votre client.

Important

Il s’agit d’une opération UNIQUE par client qui nécessite des privilèges d’administrateur général.

  1. Téléchargez le script New-Agent365ToolsServicePrincipalProdPublic.ps1.

  2. Ouvrez PowerShell en tant qu’administrateur et accédez au répertoire de script.

  3. Exécutez le script.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. À l’invite, connectez-vous avec vos informations d’identification Azure.

Une fois l’opération terminée, votre client est prêt pour le développement d’assistant et la configuration du serveur MCP.

Configurer les serveurs MCP

Utilisez l’interface CLI Agent 365 pour découvrir, ajouter et gérer des serveurs MCP pour votre assistant. Pour obtenir la liste complète des serveurs MCP disponibles et de leurs fonctionnalités, consultez le catalogue de serveur MCP.

Découvrir les serveurs disponibles

Répertoriez tous les serveurs MCP qui peuvent être configurés :

a365 develop list-available

Ajouter des serveurs MCP

Ajoutez un ou plusieurs serveurs MCP à votre configuration de l’assistant :

a365 develop add-mcp-servers mcp_MailTools

Important

Cette commande ne se met à jour ToolingManifest.json que dans votre dossier de projet — elle n’accorde aucune permission au blueprint. La façon dont les autorisations sont appliquées dépend de l’étape à laquelle vous vous trouvez dans le processus de configuration :

  • Avant la configuration initiale : Exécutez a365 develop add-mcp-servers en premier, puis procédez à a365 setup all. La commande setup all inclut l’étape des permissions MCP dans la création du Blueprint.
  • Une fois le blueprint déjà existant : un administrateur général doit exécuter a365 setup permissions mcp séparément. L’administrateur a365.config.json doit avoir deploymentProjectPath pointant vers le dossier de projet contenant la version mise à jour ToolingManifest.json. Jusqu’à ce que cette étape soit terminée, les nouvelles autorisations du serveur MCP ne sont pas visibles dans le Blueprint.

Répertorier les serveurs configurés

Affichez les serveurs MCP actuellement configurés :

a365 develop list-configured

Supprimer les serveurs MCP

Supprimez un serveur MCP de votre configuration :

a365 develop remove-mcp-servers mcp_MailTools

Pour obtenir une référence CLI complète, consultez la commande de développement a365.

Utilisez le serveur d’outils fictif pour les tests

Pour les tests et le développement, utilisez le serveur d’outils fictifs Agent 365 au lieu de vous connecter aux véritables serveurs MCP. Le serveur mock simule les interactions avec les serveurs MCP, vous pouvez donc tester votre agent localement sans dépendances externes telles que l’authentification.

Le serveur simulé offre les avantages suivants pour le développement local et les tests :

  • Développement hors ligne : testez votre assistant sans connexion Internet ni dépendances externes.
  • Tests cohérents : recevez des réponses prévisibles pour tester des cas limites.
  • Débogage : voir toutes les requêtes et réponses en temps réel
  • Itération rapide : pas besoin d’attendre des appels API externes ni de configurer des environnements de test complexes.

Démarrez le serveur d’outils fictif à l’aide de la commande a365 develop start-mock-tooling-server.

Apprenez à configurer le serveur d’outils de simulation.

Remarque

Les sections suivantes pour la configuration du manifeste et l’intégration d’outils dans votre assistant fonctionnent de la même manière, que vous utilisiez le serveur d’outils fictif ou de véritables serveurs MCP. Définissez votre variable d’environnement MCP_PLATFORM_ENDPOINT pour qu’elle pointe vers le serveur simulé (par exemple : http://localhost:5309) plutôt que vers le point de terminaison de production.

Comprendre le manifeste d’outils

Lorsque vous exécutez a365 develop add-mcp-servers, l’interface CLI génère un fichier ToolingManifest.json contenant la configuration de tous les serveurs MCP. L’environnement d’exécution de l’assistant utilise ce manifeste pour comprendre quels serveurs sont disponibles et comment s’authentifier avec eux.

Structure du manifeste

Exemple ToolingManifest.json:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Paramètres de manifeste

Chaque entrée de serveur MCP contient :

Paramètre Description
mcpServerName Nom complet du serveur MCP.
mcpServerUniqueName L’identificateur unique de l’instance du serveur MCP.
étendue Étendue OAuth requise pour accéder aux fonctionnalités du serveur MCP (par exemple : McpServers.Mail.All pour les opérations de messagerie). La commande add-mcp-servers récupère cette valeur à partir du catalogue de serveurs MCP.
public URI de Microsoft Entra ID qui identifie la ressource d’API cible. La commande add-mcp-servers récupère cette valeur à partir du catalogue de serveurs MCP.

Remarque

Les valeurs scope et audience sont automatiquement remplies par l’interface CLI Agent 365 lorsque vous ajoutez un serveur MCP. Ces valeurs proviennent du catalogue de serveurs MCP et définissent les autorisations requises pour accéder à chaque serveur MCP.

Intégrer des outils dans votre assistant

Après avoir généré le manifeste d’outils, intégrez les serveurs MCP configurés dans votre code d’assistant. Cette section décrit l’étape d’inspection facultative et les étapes d’intégration requises.

Répertorier les serveurs d’outils (facultatif)

Astuce

Cette étape est facultative. Utilisez le service de configuration du serveur d’outils pour inspecter les serveurs d’outils disponibles à partir du manifeste d’outils avant de les ajouter à votre orchestrateur.

Utilisez le service de configuration du serveur d’outils pour découvrir quels serveurs d’outils sont disponibles pour votre assistant à partir du manifeste d’outils. Cette méthode vous permet d’effectuer ce qui suit :

  • Interrogez tous les serveurs MCP configurés à partir du fichier ToolingManifest.json.
  • Récupérez les métadonnées et fonctionnalités du serveur.
  • Vérifiez la disponibilité du serveur avant l’inscription.

La méthode permettant de répertorier les serveurs d’outils est disponible dans les packages d’outils principaux :

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

Paramètres :

Paramètre Type Description Valeur attendue Obligatoire/facultatif
agentic_app_id str Identificateur unique de l’instance d’application de l’assistant Chaîne d’ID d’application de l’assistant valide Obligatoire
auth_token str Jeton du porteur pour l’authentification auprès de la passerelle de serveur MCP Jeton du porteur OAuth valide Obligatoire

Package : microsoft_agents.a365.tooling

Inscrire des outils auprès de votre orchestrateur

Utilisez la méthode d’extension spécifique à l’infrastructure pour inscrire tous les serveurs MCP auprès de votre infrastructure d’orchestration :

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

Ces méthodes :

  • Inscrire tous les outils à partir de serveurs MCP configurés auprès de votre orchestrateur
  • Configurer automatiquement les détails de l’authentification et de la connexion
  • Rendre les outils immédiatement disponibles pour que votre assistant appelle

Choisir votre extension d’orchestrateur

Le module Agent 365 Tooling fournit des packages d’extension dédiés pour différents cadres d’orchestration :

Remarque

Lorsque vous exécutez a365 develop add-mcp-servers, l’interface CLI récupère automatiquement les étendues OAuth et les valeurs d’audience du catalogue de serveurs MCP et les écrit dans ToolingManifest.json. Les méthodes d’extension utilisent automatiquement ces valeurs pour configurer l’authentification. Aucune configuration manuelle n’est requise dans votre code d’assistant. Cependant, un administrateur global doit toujours accorder ces autorisations au Blueprint de l’assistant avant que votre assistant puisse les utiliser en production : soit via a365 setup all (première configuration), soit via a365 setup permissions mcp (si le Blueprint existe déjà).

Pour obtenir des exemples d’implémentation détaillés, consultez les exemples Agent 365.

Exemples d’implémentation

Les exemples suivants montrent comment intégrer l’outil Agent 365 à différents cadres d’orchestration.

Python avec OpenAI

Cet exemple montre comment intégrer des outils MCP à OpenAI dans une application Python.

1. Ajouter des instructions d’importation

Ajoutez les importations requises pour accéder au module Tooling et aux extensions OpenAI :

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. Initialiser les services d’outils

Créez des instances des services d’inscription de configuration et d’outil :

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. Inscrire des outils MCP auprès de l’assistant OpenAI

Utilisez la méthode add_tool_servers_to_agent pour inscrire tous les outils MCP configurés auprès de votre assistant OpenAI. Cette méthode gère à la fois les scénarios d’authentification agentique et nonagentique :

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

Paramètres de la méthode

La table suivante décrit les paramètres à utiliser avec add_tool_servers_to_agent.

Paramètre Description
agent Instance de l’assistant OpenAI avec laquelle inscrire des outils.
agentic_app_id Identificateur unique de l’assistant (ID d’application agentique).
auth Contexte d’autorisation de l’utilisateur.
context Contexte de tour de conversation actuel à partir du kit de développement logiciel (SDK) Agents. Fournit l’identité de l’utilisateur, les métadonnées de conversation et le contexte d’authentification pour l’inscription sécurisée des outils.
auth_token (Facultatif) Jeton du porteur pour les scénarios d’authentification nonagentique.

4. Appel pendant l’initialisation

Veillez à appeler la méthode d’installation pendant l’initialisation avant d’exécuter l’assistant :

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

La méthode add_tool_servers_to_agent automatiquement :

  • Charge tous les serveurs MCP à partir du fichier ToolingManifest.json.
  • Inscrit ses outils auprès de l’assistant OpenAI.
  • Configure l’authentification en fonction de la configuration du manifeste.
  • Rend les outils disponibles pour que votre assistant appelle.

Pour obtenir des exemples de travail complets, consultez les exemples de référentiel Agent 365.

Autres moyens d’accéder aux serveurs MCP Agent 365

En plus du SDK Agent 365, vous pouvez accéder aux serveurs MCP Agent 365 par le biais d’autres expériences de développement :

  • Visual Studio Code - Connectez-vous directement aux serveurs MCP pour des flux de travail de développement personnalisés.
  • Microsoft Copilot Studio - Intégrez les serveurs MCP dans les flux conversationnels en utilisant une expérience low-code.
  • Azure AI Foundry - Utilisez les serveurs MCP avec une prise en charge complète du SDK et des capacités d’orchestration avancées.

Pour un aperçu complet des serveurs de tooling MCP disponibles et des options d’intégration sur ces plateformes, voir Agent 365 Tooling Servers Overview.

Apportez votre propre serveur MCP (BYO)

La fonctionnalité Bring Your Own (BYO) pour serveur MCP vous permet d’enregistrer vos propres serveurs MCP externes auprès de Microsoft Agent 365 afin qu’ils puissent être gouvernés, approuvés et surveillés de manière centralisée dans le Centre d’administration Microsoft 365. Il achemine ces serveurs via la passerelle de tooling Agent 365, donnant aux administrateurs le contrôle sur l’approbation, l’accès et les stratégies, tout en permettant aux équipes de sécurité de suivre l’utilisation grâce à la télémétrie. En tant que développeur, vous pouvez enregistrer votre serveur MCP à l’aide de la CLI Agent 365, puis demander à votre administrateur de vérifier et d’approuver l’enregistrement et d’accorder les autorisations. Le serveur approuvé peut ensuite être utilisé dans les outils clients pris en charge, une surveillance continue garantissant la conformité et la visibilité sur l’ensemble des intégrations.

Pour des instructions complètes, voir Apportez votre propre serveur MCP (BYO).

Tester votre assistant

Après avoir intégré les outils MCP à votre assistant, testez les appels d’outils pour vous assurer qu’ils fonctionnent correctement et gèrent différents scénarios. Suivez le guide de test pour configurer votre environnement. Concentrez-vous principalement sur la section Appels d’outils de test afin de valider que vos outils MCP fonctionnent comme prévu. Consultez également le serveur d’outils de simulation pour tester la connexion au serveur MCP et les appels d’outils sans gérer l’authentification.

Ajouter l’observabilité

Ajoutez de l’observabilité à votre assistant pour surveiller et tracer les invocations de ses outils MCP. En ajoutant des capacités d’observabilité, vous pouvez suivre les performances, déboguer des problèmes et comprendre les schémas d’utilisation des outils. En savoir plus sur l’implémentation du suivi et de la surveillance.

Résolution des problèmes

Cette section liste les problèmes courants lors de la configuration et de l’utilisation des serveurs et outils MCP.

Astuce

Le Guide de dépannage Agent 365 contient des recommandations générales de dépannage, les meilleures pratiques et des liens vers du contenu de dépannage pour chaque étape du cycle de développement de l’Agent 365.

Problèmes de serveur MCP et d’outils

Symptômes :

  • Les défaillances des appels d’outils.
  • Erreurs Serveur MCP introuvable.
  • Erreurs de refus de permission lors de l’appel d’outils.

Cause racine :

  • Le serveur MCP n’est pas configuré.
  • Autorisations manquantes.
  • Le principal de service n’est pas configuré.
  • Confusion entre les serveurs simulés et de production.

Solutions : Essayez les solutions suivantes pour résoudre le problème.

  • Vérifiez que les serveurs MCP sont configurés

    Listez les serveurs configurés et ajoutez tous ceux qui manquent.

    # List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

  • Vérifiez que le principal de service existe

    Assurez-vous que le principal de service requis est créé pour les outillages.

    # Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Pour le développement et les tests précoces, utilisez des serveurs fictifs

    Utilisez le serveur d’outils de simulation pour le développement local et les tests précoces si vous souhaitez tester le reste de votre assistant sans composants d’outils de production.

    # Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309

    Apprenez-en plus sur le serveur d’outils de simulation.

  • Vérifier les autorisations dans le Centre d’administration

    Confirmez que votre assistant dispose des autorisations MCP nécessaires.

    • Vérifiez que les autorisations de l’API Blueprint de votre assistant dans le Portail Azure incluent toutes les autorisations du serveur MCP.

    Vérification :

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Last updated on