Partager via

Ajouter et gérer les outils

Important

Vous devez faire partie du programme Frontier en version préliminaire pour obtenir un accès anticipé à Microsoft Agent 365. Frontier vous connecte directement aux dernières innovations d’IA de Microsoft. Les versions préliminaires Frontier sont soumises aux conditions existantes de vos contrats clients qui régissent les versions préliminaires. Comme ces fonctionnalités sont encore en cours de développement, leur disponibilité et leurs capacités peuvent évoluer au fil du temps.

Le module Outils aide les développeurs à découvrir, configurer et intégrer les serveurs Model Context Protocol (MCP) dans les flux de travail des agents 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 un manifeste : l’interface CLI crée ToolingManifest.json avec des configurations de serveur
  3. Intégrer dans le code : chargez le manifeste et inscrivez des outils auprès de votre orchestrateur
  4. 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. Ce processus crée l’identifiant d’application et l’utilisateur agent qui permettent à votre agent d’authentifier et d’accéder aux outils MCP.

Configurer le principal de service

Exécutez ce script de configuration unique pour créer le principal de service pour Agent 365 Tools dans votre locataire.

Important

Il s’agit d’une opération unique par locataire nécessitant des privilèges d’administrateur global.

  1. Téléchargez le scriptNew-Agent365ToolsServicePrincipalProdPublic.ps1 .

  2. Ouvre PowerShell en tant qu’administrateur et va dans le répertoire des scripts.

  3. Exécutez le script.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Connectez-vous en utilisant vos identifiants Azure quand vous vous le demandez.

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

Listez tous les serveurs MCP que vous pouvez configurer :

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

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 mock pour les tests

Pour les tests et le développement, utilisez le serveur d’outils fictifs Agent 365 CLI 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 mock offre les avantages suivants pour le développement local et les tests :

  • Développement hors ligne : Testez votre agent 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 de simulation en utilisant la a365 develop start-mock-tooling-server commande.

Apprenez à configurer et à configurer le serveur d’outils de simulation.

Note

Les sections suivantes pour configurer les manifestes et intégrer des outils dans votre agent fonctionnent de la même maman, que vous utilisiez le serveur d’outils mock ou les véritables serveurs MCP. Réglez votre MCP_PLATFORM_ENDPOINT variable d’environnement pour qu’elle pointe vers le serveur mock (par exemple : ) http://localhost:5309au lieu du 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ètres Descriptions
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 add-mcp-servers commande récupère cette valeur du catalogue serveur MCP.
public URI de Microsoft Entra ID qui identifie la ressource d’API cible. La add-mcp-servers commande récupère cette valeur du catalogue serveur MCP.

Note

La CLI de l’Agent 365 remplit automatiquement les scope valeurs et audience 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.

Serveurs d’outils de liste (optionnel)

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 depuis le ToolingManifest.json fichier.
  • Récupérer les métadonnées et capacités du serveur.
  • Vérifiez la disponibilité des serveurs avant l’enregistrement.

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 Obligatoires/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 Requise
auth_token str Jeton du porteur pour l’authentification auprès de la passerelle de serveur MCP Jeton du porteur OAuth valide Requise

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 :

  • microsoft-agents-a365-tooling : fonctionnalité d’outils de base
  • microsoft-agents-a365-tooling-extensions-agentframework : intégration d’Agent Framework
  • microsoft-agents-a365-tooling-extensions-azureaifoundry : intégration d’Azure AI Foundry
  • microsoft-agents-a365-tooling-extensions-openai : intégration d’OpenAI
  • microsoft-agents-a365-tooling-extensions-semantickernel : intégration de Semantic Kernel

Note

L’authentification est automatiquement configurée par l’interface CLI Agent 365 lorsque vous exécutez a365 develop add-mcp-servers. Le catalogue serveur MCP récupère les champs OAuth et les valeurs d’audience et les inclut dans le ToolingManifest.jsonfichier . Les méthodes d’extension utilisent automatiquement ces valeurs pour configurer l’authentification. Aucune configuration manuelle n’est requise.

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 les outils Agent 365 avec différents frameworks 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ètres Descriptions
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 depuis le fichier ToolingManifest.json.
  • Enregistre leurs outils auprès de l’agent OpenAI.
  • Configure l’authentification en fonction de la configuration du manifeste.
  • Cela met à disposition les outils que votre agent peut utiliser.

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

Tester votre assistant

Après avoir intégré les outils MCP dans votre agent, testez les invocations d’outils pour vous assurer qu’elles fonctionnent correctement et gèrent différents scénarios. Suivez le guide de test pour configurer votre environnement. Ensuite, concentrez-vous principalement sur la section des invocations des outils de test pour valider que vos outils MCP fonctionnent comme prévu. Regarde aussi le serveur d’outils mock pour tester la connexion au serveur MCP et les invocations d’outils sans avoir à gérer l’authentification.

Ajouter l’observabilité

Ajoutez de la visibilité à votre agent pour surveiller et tracer les invocations de l’outil MCP de votre agent. 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 la mise en œuvre du traçage et du suivi.

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 de l’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’outillage

Symptômes :

  • Défaillances d’appel d’outils.
  • Erreurs « serveur MCP non trouvé ».
  • Erreurs de refus lors de l’appel d’outils à l’autorisation.

Cause racine :

  • Le serveur MCP n’est pas configuré.
  • Permissions manquantes.
  • Le principal de service n’est pas établi.
  • 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 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 l’existence du principe de service

    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 mock pour le développement local et les tests précoces si vous souhaitez tester le reste de votre agent 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

    Découvrez le serveur de mock tooling

  • Vérifier les permissions dans le centre d’administration

    Confirmez que votre agent a les autorisations MCP nécessaires.

    • Validez que les permissions de votre API de l’agent Blueprint dans le portail Azure affichent toutes les permissions du serveur MCP.

    Vérification :

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