Vue d’ensemble des outils d’agent pour le service d’agent Foundry

Les outils étendent les capacités de vos agents dans Microsoft Foundry Agent Service. Un agent utilise lui-même un modèle Foundry pour générer du texte, mais les outils lui permettent de prendre des mesures : la recherche sur le web, l’exécution de code, l’interrogation de vos données ou l’appel de vos propres API. Cet article explique quels sont les outils, les types d’outils disponibles, comment utiliser un outil dans un agent et comment gérer l’authentification. Il présente également le catalogue d’outils Foundry où vous découvrez et configurez des outils. Pour utiliser des outils, vous devez accéder à un projet Foundry et l’autorisation de gérer les outils de ce projet.

Note

Le catalogue d’outils Foundry et l’infrastructure d’outils de base sont généralement disponibles. Certains outils individuels sont toujours en préversion, comme indiqué dans les listes d’outils tout au long de cet article. Chaque page de chaque outil indique également son état d’aperçu avec une bannière. Les outils en préversion sont soumis à des conditions d’utilisation supplémentaires.

Qu’est-ce que les outils ?

Un outil est une fonctionnalité qu’un agent peut appeler pendant une conversation pour effectuer une tâche spécifique. Lorsqu’un agent reçoit un message utilisateur, le modèle Foundry alimentant l’agent détermine s’il faut appeler un outil en fonction des instructions de l’agent et des définitions d’outils disponibles. L’agent envoie la demande d’outil, votre application ou le service l’exécute, et le résultat revient dans la conversation afin que l’agent puisse continuer avec des informations précises et up-to-date.

Les outils permettent aux agents d’aller au-delà de la génération de texte. Par exemple, un agent peut :

  • Recherchez les informations actuelles sur le web avant de répondre.
  • Exécutez Python code pour analyser un jeu de données et générer un graphique.
  • Interrogez un magasin de vecteurs de vos documents pour ancrer sa réponse dans vos données.
  • Appelez une API externe pour rechercher un enregistrement client ou créer un ticket de support.

Types d’outils

Le service De l’agent Foundry fournit deux catégories d’outils : les outils intégrés prêts à être utilisés après la configuration de base et les outils personnalisés qui vous permettent d’apporter vos propres fonctionnalités.

Outils intégrés

Le service Agent Foundry fournit des outils intégrés comme fonctionnalités préconfigurées. Vous activez ces outils sur votre agent et le service gère l’exécution. Ces outils ne nécessitent pas d’hébergement externe ou de code personnalisé.

Les outils intégrés les plus couramment utilisés sont les suivants :

  • Recherche web : ajoutez la recherche web à votre agent. L’agent récupère des informations en temps réel à partir du web public et retourne des réponses avec des citations inline. Cette méthode est la méthode recommandée pour ajouter un ancrage web. Pour des scénarios avancés tels que le filtrage spécifique au marché, consultez Ancrage avec les outils Bing et la vue d'ensemble de l'ancrage du web.
  • Code Interpreter : permettre aux agents d’écrire et d’exécuter du code Python dans un environnement bac à sable (sandbox) pour l’analyse des données, les mathématiques et la génération de graphique.
  • Recherche de fichiers : augmentez les agents avec des connaissances à partir de fichiers chargés ou de documents propriétaires à l’aide de la recherche vectorielle.
  • Appel de fonction : définissez des fonctions personnalisées que l’agent peut appeler. Votre application exécute la fonction et retourne le résultat.

Pour obtenir la liste complète des outils intégrés, consultez Tous les outils intégrés.

Outils personnalisés

Les outils personnalisés vous permettent d’étendre votre agent avec vos propres API, services ou autres agents. Utilisez des outils personnalisés lorsque les outils intégrés ne couvrent pas votre scénario.

Les options d’outils personnalisées les plus courantes sont les suivantes :

  • Modèle Context Protocol (MCP) : connectez votre agent aux outils hébergés sur un point de terminaison de serveur MCP. Il est préférable pour les outils partagés entre plusieurs agents ou gérés par une autre équipe.
  • Agent à agent (A2A) (préversion) : connectez votre agent à d’autres agents via des points de terminaison compatibles A2A pour la communication entre agents.
  • Outil OpenAPI : connectez votre agent aux API HTTP externes à l’aide d’une spécification OpenAPI 3.0 ou 3.1.

Pour obtenir la liste complète des options d’outils personnalisés, consultez Tous les outils personnalisés.

Boîte à outils (préversion)

Un toolbox est un ensemble organisé d’outils, tels que la recherche web, Recherche Azure AI, l’interpréteur de code, la recherche de fichiers, les serveurs MCP et les outils OpenAPI que vous configurez une fois et exposez en tant que point de terminaison compatible MCP unique. Au lieu d’attacher chaque outil individuellement à chaque définition d’agent, définissez la collection dans une boîte à outils et connectez n’importe quel agent au point de terminaison de la boîte à outils. Étant donné qu’une boîte à outils expose un point de terminaison compatible MCP, tout runtime compatible MCP peut l’utiliser, y compris les agents créés avec Microsoft Agent Framework, LangGraph, GitHub Copilot SDK et du code personnalisé.

Les boîtes à outils prennent en charge le contrôle de version. Créez plusieurs versions, testez une nouvelle version par rapport au point de terminaison spécifique à la version, puis faites-la passer par défaut lorsqu’elle est prête. Les agents qui se connectent au point de terminaison du consommateur de boîte à outils reçoivent automatiquement la version par défaut promue sans modification du code. Pour plus d’informations, consultez Gérer les versions de boîte à outils.

Gérez l’authentification pour les outils d’une boîte à outils de manière centralisée. La boîte à outils gère l'injection d'informations d'identification, l'actualisation des jetons et l'application de stratégie au moment de l'exécution à l'aide de Microsoft Entra ID et OAuth, de sorte que les agents consommant n'ont pas besoin de gérer les informations d'identification de chaque outil individuellement. Pour plus d’informations sur l’authentification, consultez Configurer l’authentification du serveur MCP.

Pour connaître les étapes de configuration, consultez Créer et utiliser une boîte à outils Foundry.

Utiliser un outil dans un agent logiciel

Pour ajouter un outil à un agent, incluez-le dans la liste des outils de l’agent lorsque vous créez ou mettez à jour la définition de l’agent. L’exemple suivant crée un agent avec l’outil de recherche web activé et envoie une requête :

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create an agent with web search enabled
agent = project.agents.create_version(
    agent_name="web-search-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)

# Send a query
response = openai.responses.create(
    input="What are the latest updates to Microsoft Foundry?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

Chaque type d’outil a sa propre configuration. Pour obtenir des exemples de configuration et de code détaillés dans toutes les langues prises en charge, consultez les guides pratiques de l’outil individuels liés dans les types d’outils de la section.

Personnaliser le comportement de l’outil au moment de l’exécution avec des entrées structurées

Par défaut, les configurations d’outils telles que les ID de fichier, les ID de magasin de vecteurs et les points de terminaison de serveur MCP sont fixes lorsque vous créez l’agent. Les entrées structurées dans les propriétés d’outil vous permettent de remplacer ces valeurs au moment de l’exécution sans créer de nouvelle version de l’agent.

Les entrées structurées sont utiles quand :

  • Différents utilisateurs ont besoin de magasins ou de fichiers vectoriels différents en fonction de leur contexte.
  • Vous souhaitez réutiliser la même définition d’agent dans les environnements (développement, préproduction, production).
  • Les points de terminaison de serveur MCP ou les jetons d’authentification varient selon la demande.

Les propriétés d’outil suivantes prennent en charge la personnalisation via des entrées structurées :

Type d’outil Propriété Description
file_search vector_store_ids Tableau d'ID d'entrepôt de vecteurs. Les valeurs vides sont supprimées au moment de l’exécution.
code_interpreter container, container.file_ids ID de conteneur ou ID de fichier au sein d’un conteneur automatique. Les valeurs vides sont supprimées au moment de l’exécution.
mcp server_label, server_url, headers Étiquette de serveur MCP, URL et valeurs d’en-tête HTTP.

Par exemple, une définition d’agent avec un stockage de vecteurs à base de modèle :

{
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["vs_base_kb", "{{customer_kb}}"]
    }
  ],
  "structured_inputs": {
    "customer_kb": {
      "description": "Vector store ID for the customer's knowledge base",
      "required": true,
      "schema": { "type": "string" }
    }
  }
}

Au moment de l’exécution, fournissez la valeur réelle :

{
  "agent": { "type": "agent_reference", "name": "support-agent", "version": "1" },
  "input": [{ "type": "text", "text": "How do I upgrade my account?" }],
  "structured_inputs": {
    "customer_kb": "vs_premium_kb_2024"
  }
}

Gérer l’authentification pour les outils

Différents outils nécessitent différentes approches d’authentification. La compréhension de ces options vous permet de connecter des outils en toute sécurité.

Outils intégrés

La plupart des outils intégrés, tels que l’interpréteur de code et la recherche de fichiers, s’authentifient automatiquement via le service Foundry Agent et ne nécessitent aucune configuration supplémentaire. Les outils qui se connectent à des sources de données externes, comme Recherche Azure AI ou SharePoint, utilisent les connections que vous configurez dans votre projet Foundry.

Serveurs MCP

Les serveurs MCP prennent en charge plusieurs méthodes d’authentification en fonction du serveur : authentification basée sur des clés (clé API ou jeton), authentification Microsoft Entra (identité managée) et OAuth pour le passage d’identité au niveau de l’utilisateur.

L’exemple suivant se connecte à un serveur MCP à l’aide de l’authentification basée sur des clés. Stockez les informations d’identification dans une connexion de projet, puis référencez le nom de connexion lorsque vous créez l’outil :

from azure.ai.projects.models import MCPTool

tool = MCPTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id="my-github-connection",
)

Pour l’authentification Microsoft Entra, utilisez l’identité de l’agent ou l’identité managée du projet au lieu d’une connexion. Le service demande automatiquement un jeton. Pour le passage d’identité OAuth (authentification par utilisateur), Agent Service génère un lien de consentement que les utilisateurs autorisent à leur première utilisation.

Pour connaître les étapes d’installation détaillées de toutes les méthodes, consultez Configurer l’authentification du serveur MCP.

Conseil

En cas de doute, commencez par Microsoft Entra l’authentification si le serveur MCP le prend en charge. Il élimine la nécessité de gérer les secrets et fournit une rotation de jeton intégrée.

Outils OpenAPI

Les outils OpenAPI prennent en charge l’authentification anonyme, de clé API et d’identité managée. La configuration de l’authentification fait partie de la définition de l’outil.

Authentification anonyme : utilisez quand l’API ne nécessite pas d’informations d’identification :

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_spec,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

Authentification par clé API : stockez la clé dans une connexion de projet, puis référencez-la. Votre spécification OpenAPI doit inclure securitySchemes et security sections :

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiKeyAuthDetails,
)

api_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_orders",
        spec=openapi_spec,
        description="Look up customer orders.",
        auth=OpenApiKeyAuthDetails(
            project_connection_id="my-api-connection"
        ),
    )
)

Pour la configuration des identités managées, consultez Connecter des agents aux outils OpenAPI.

Conseil

Traitez toutes les informations d’identification comme des secrets. Fournissez uniquement les en-têtes minimum requis, n’incluez pas d’informations d’identification dans les invites et passez en revue les pratiques de gestion des données du fournisseur. Pour connaître les contrôles de gouvernance tels que les limites de débit et les restrictions IP sur les outils MCP, consultez Gouvernance des outils MCP à l’aide d’une passerelle IA.

Tous les outils intégrés

Le tableau suivant répertorie tous les outils intégrés disponibles dans le service de l’agent Foundry.

Outil Description
Recherche web Récupérez des informations en temps réel à partir du web public et retournez des réponses avec des citations inline.
Interpréteur de code Écrivez et exécutez du code Python dans un environnement sandboxé.
Interpréteur de code personnalisé (préversion) Personnalisez les ressources de l'interpréteur de code, les packages Python et l'environnement Container Apps.
Recherche de fichiers Fournissez aux agents des connaissances issues de fichiers téléchargés ou de documents propriétaires.
Recherche Azure AI Agents au sol équipés de données issues d'un index existant d'Recherche Azure AI.
Azure Functions Permettre aux agents d’appeler votre Azure Functions pour effectuer des actions personnalisées et récupérer des données dynamiques.
Appel de fonction Définissez des fonctions personnalisées que l’agent peut appeler. Votre application exécute la fonction et retourne le résultat.
Génération d’image (préversion) Générez des images dans le cadre de conversations et de flux de travail.
Browser Automation (préversion) Effectuez des tâches de navigateur au moyen de commandes en langage naturel.
Utilisation de l’ordinateur (préversion) Interagissez avec les systèmes informatiques via leurs interfaces utilisateur.
Microsoft Fabric (préversion) Connectez-vous à un agent de données Microsoft Fabric pour l’analyse des données.
SharePoint (préversion) Discuter avec des documents privés stockés dans SharePoint.

Conseil

Pour les scénarios avancés de référencement web, référez-vous à Référencement avec les outils Bing et à l'aperçu du référencement web.

Tous les outils personnalisés

Le tableau suivant répertorie toutes les options d’outil personnalisées pour connecter vos propres fonctionnalités à un agent.

Outil Description
Model Context Protocol (MCP) Connectez votre agent aux outils hébergés sur un point de terminaison de serveur MCP.
Outil OpenAPI Connectez votre agent à des API externes à l’aide d’une spécification OpenAPI 3.0 ou 3.1.
Agent-à-agent (A2A) (aperçu) Connectez votre agent à d’autres agents via des points de terminaison compatibles avec A2A.
Boîte à outils (preview) Regroupez plusieurs outils dans un seul point de terminaison MCP pour la réutilisation entre les agents.

Concepts clés

Utilisez ces définitions pour assurer la cohérence de la terminologie :

Terme Sens
Outils de fonderie L’expérience du portail dans laquelle vous découvrez, configurez et gérez des outils pour les agents et les flux de travail.
Catalogue d’outils Liste des outils disponibles, y compris les outils publics et organisationnels.
Catalogue d’outils privés Catalogue étendu à l’organisation pour les outils que seuls les utilisateurs de votre organisation peuvent découvrir et configurer.
Serveur MCP Serveur qui expose des outils à l’aide du protocole MCP (Model Context Protocol).
Serveur MCP distant Un serveur MCP hébergé par l’éditeur. Vous le configurez en fournissant les paramètres requis, tels qu’un point de terminaison et des détails d’authentification.
Serveur MCP local Un serveur MCP que vous hébergez vous-même, puis connectez-vous à Foundry en fournissant son point de terminaison distant.
Outil personnalisé Un outil que vous ajoutez en fournissant votre propre point de terminaison ou spécification, tel qu’un point de terminaison MCP, une spécification OpenAPI ou des points de terminaison agent à agent (A2A).
Boîte à outils Ensemble organisé d’outils que vous configurez une fois et exposez en tant que point de terminaison MCP unique pour une utilisation sur plusieurs agents.

Note

Si vous souhaitez apporter vos serveurs MCP officiels et distants à tous les clients Foundry, remplissez ce formulaire.

Considérations relatives à l’utilisation de serveurs et non-services Microsoft

Votre utilisation de serveurs et de non-services Microsoft connectés (« non-services Microsoft ») est soumise aux conditions entre vous et le fournisseur de services. Les services non Microsoft sont des produits non Microsoft sous votre contrat régissant votre utilisation des services en ligne de Microsoft. Lorsque vous vous connectez à des services non-Microsoft, certaines de vos données (telles que le contenu de l’invite) sont envoyées au service non-Microsoft, ou votre application peut recevoir des données de ce service. Vous êtes responsable de votre utilisation de données et non services Microsoft, ainsi que des frais associés à cette utilisation.

Les tiers (et non Microsoft) créent les services non-Microsoft, y compris les serveurs MCP distants, auxquels vous choisissez de vous connecter. Microsoft ne teste pas ou ne vérifie pas ces serveurs. Microsoft n’a aucune responsabilité vis-à-vis de vous ou d’autres personnes en ce qui concerne votre utilisation de n’importe quel autre services Microsoft.

Examinez et suivez attentivement les serveurs MCP que vous ajoutez au service De l’agent Foundry. Reposez sur les serveurs hébergés par des fournisseurs de services approuvés eux-mêmes plutôt que sur des proxys.

L’outil MCP peut transmettre des en-têtes personnalisés qu’un serveur MCP distant peut nécessiter pour l’authentification. Traitez les informations d’identification comme des secrets :

  • Fournissez uniquement les en-têtes minimum requis.
  • N’incluez pas d’informations d’identification dans les invites.
  • Si vous consignez des demandes d’audit, évitez d'enregistrer les secrets ou le contenu sensible de l’invite.
  • Passez en revue les pratiques de gestion des données du fournisseur, notamment la rétention et l’emplacement des données.

Découvrir et gérer des outils dans le portail

Dans le portail Foundry, accédez à votre projet et sélectionnez Build>Tools pour ouvrir Foundry Tools. À partir de là, vous pouvez parcourir le catalogue d’outils, configurer des outils et les ajouter aux agents ou aux flux de travail. Si vous avez besoin d’outils visibles uniquement au sein de votre organisation, créez un catalogue d’outils privé.

Pour explorer les outils lors de la construction, utilisez le terrain de jeu des agents. Pour plus d’informations, consultez Microsoft Foundry Playgrounds.

Types d’outils dans le catalogue

Le catalogue d’outils comprend trois types d’entrées :

Serveur MCP distant : l’éditeur héberge le serveur et fournit un point de terminaison statique ou dynamique. Suivez les instructions de configuration pour fournir les paramètres requis, tels qu’un point de terminaison et des détails d’authentification.

Serveur MCP local : vous hébergez le serveur vous-même, puis connectez-le à Foundry en fournissant son point de terminaison. Pour générer et inscrire votre propre serveur, consultez Générer et inscrire un serveur MCP. Pour connecter un point de terminaison MCP à un agent, consultez Se connecter aux serveurs MCP.

Custom : serveurs MCP convertis à partir de connecteurs d’application logique Azure. Ces serveurs nécessitent une configuration supplémentaire pour effectuer la conversion en serveurs MCP distants.

Les outils Foundry fournissent les filtres suivants pour vous aider à trouver les outils appropriés :

Filtre Description
Éditeur éditeur Microsoft ou non-Microsoft
Catégorie Catégories telles que les bases de données, l’analytique, le web et bien plus encore
Registre Public : Serveurs MCP locaux et distants publics dans le catalogue.
connecteurs Logic Apps : connecteurs Azure Logic Apps que vous convertissez en serveurs MCP distants pour un catalogue d’outils privé.
Authentification supportée Méthode d’authentification prise en charge par un serveur MCP. Pour plus d’informations, consultez méthodes d’authentification.

Capture d'écran d'une page de détails de l'outil dans le portail Foundry montrant les informations de configuration et d'installation.

Lorsque vous sélectionnez un outil, Foundry Tools affiche les détails de configuration dont vous avez besoin pour le configurer.

Gérer les outils configurés

Dans votre liste d’outils, vous trouverez les outils que vous avez configurés, ainsi que des détails tels que les points de terminaison et les paramètres d’authentification. Vous pouvez également ajouter des outils aux agents et aux flux de travail.

Avant de supprimer un outil, vérifiez quels agents ou flux de travail l’utilisent. La suppression d’un outil peut interrompre les exécutions qui en dépendent.

Disponibilité et limitations

La disponibilité des outils varie selon le modèle et la région.

Pour obtenir les derniers détails de prise en charge du modèle et de la région dans les outils, consultez les meilleures pratiques d'utilisation des outils dans le service de l’agent Foundry.

Dépannage

Utilisez ces vérifications pour résoudre les problèmes courants :

  • Vous ne trouvez pas le catalogue d’outils : vérifiez que vous êtes dans le projet correct, puis accédez à Build>Tools.
  • Un outil est visible, mais vous ne pouvez pas le configurer : passez en revue les entrées d’authentification et de configuration requises de l’outil et vérifiez que vous avez accès à tous les services dépendants.
  • Votre agent n’appelle pas d’outil : utilisez les conseils de validation dans Meilleures pratiques pour l'utilisation des outils dans le service d'Agent Foundry.

Contenu connexe

  • Last updated on