Utiliser la boîte à outils Foundry avec LangChain

Utilisez le langchain-azure-ai package pour charger des outils et des compétences d’une boîte à outils Foundry dans vos agents LangChain et LangGraph. Une boîte à outils Foundry est un serveur multi-MCP managé qui agrège plusieurs outils configurés derrière un seul point de terminaison MCP (Model Context Protocol).

Vous découvrez comment charger des outils, identifier les outils qui nécessitent une approbation, charger des compétences de boîte à outils en tant que ressources et préparer des compétences pour les agents profonds.

Prerequisites

Installez les packages nécessaires :

pip install -U langchain-azure-ai langchain-mcp-adapters httpx azure-identity

L’intégration de la boîte à outils nécessite langchain-mcp-adapters et httpx. Pour charger des compétences pour les agents profonds, installez également deepagents.

Configurer votre environnement

La boîte à outils a besoin d’un point de terminaison de projet et d’un nom de boîte à outils. Définissez le point de terminaison en tant que variable d’environnement et transmettez le nom de la boîte à outils au constructeur.

Définissez votre point de terminaison de projet :

import os

os.environ["FOUNDRY_PROJECT_ENDPOINT"] = (
    "https://<resource>.services.ai.azure.com/api/projects/<project>"
)

L’intégration lit soit FOUNDRY_PROJECT_ENDPOINT, soit AZURE_AI_PROJECT_ENDPOINT pour le point de terminaison du projet. Aucune variable d’environnement ne fournit le nom de la boîte à outils, donc passez toujours toolbox_name au constructeur.

Importez les classes courantes et initialisez le modèle utilisé dans cet article :

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage

model = init_chat_model("azure_ai:gpt-4.1")

La boîte à outils s’authentifie avec DefaultAzureCredential, qui récupère votre az login session. Vous n’avez pas besoin de créer vous-même des informations d’identification.

Se connecter à une boîte à outils

Utilisez AzureAIProjectToolbox de l’espace de noms langchain_azure_ai.tools pour vous connecter à une boîte à outils. L’intégration détecte la connexion de projet lorsque vous définissez la variable d’environnement FOUNDRY_PROJECT_ENDPOINT . Microsoft Entra ID est la méthode d’authentification par défaut.

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    toolbox_name="my-toolbox",
)

Lorsque vous définissez le point de terminaison dans l’environnement, vous pouvez omettre project_endpoint. Vous devez toujours fournir toolbox_name:

toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")

Note

AzureAIProjectToolbox est en préversion et déclenche une ExperimentalWarning lorsque vous en créez un. Son API est susceptible de changer.

Reference :AzureAIProjectToolbox

Charger des outils à partir d’une boîte à outils

Appelez aget_tools() pour ouvrir une session avec la boîte à outils et charger chaque outil qu’il expose en tant qu’instances LangChain BaseTool . Chaque appel est sans état : il ouvre une nouvelle session MCP, charge les outils et les retourne.

async def main():
    toolbox = AzureAIProjectToolbox(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        toolbox_name="my-toolbox",
    )

    tools = await toolbox.aget_tools()

    agent = create_agent(model=model, tools=tools)

    result = await agent.ainvoke(
        {"messages": [HumanMessage("What can you do?")]}
    )
    print(result["messages"][-1].content)

Ce que fait cet extrait de code : Se connecte à la boîte à outils, charge ses outils et les lie à un agent. Lorsque vous appelez l’agent, le modèle peut appeler n’importe quel outil fourni par la boîte à outils pour répondre à la demande.

AzureAIProjectToolbox prend également en charge le protocole de gestionnaire de contexte asynchrone. Le comportement est identique, car chaque aget_tools() appel gère sa propre session :

async with AzureAIProjectToolbox(toolbox_name="my-toolbox") as toolbox:
    tools = await toolbox.aget_tools()

Référence :create_agent

Identifier les outils qui nécessitent une approbation

Certains outils de boîte à outils sont configurés pour exiger l’approbation avant leur exécution. Appelez get_tools_requiring_approval() pour récupérer les noms de ces outils afin de pouvoir ajouter une étape human-in-the-loop avant l’exécution.

tools_needing_approval = await toolbox.get_tools_requiring_approval()

print("Tools that require approval before execution:")
for name in tools_needing_approval:
    print(f"- {name}")

Ce que fait cet extrait de code : Inspecte les métadonnées de la boîte à outils et renvoie les noms des outils dont la configuration définit require_approval sur always. Utilisez cette liste pour soumettre les opérations sensibles à un workflow d’approbation.

Cette fonctionnalité est indépendante de la gestion du consentement OAuth. Pour plus d’informations sur les approbations avec intervention humaine, consultez Use Foundry Agent Service with LangGraph.

Toolbox dans Microsoft Foundry peut gérer des flux de travail « au nom de ». Vous pouvez configurer les exigences d’autorisation lorsque vous ajoutez les outils à votre boîte à outils.

Capture d’écran de la configuration d’un serveur MCP avec un workflow « pour le compte de l’utilisateur ».

Lorsqu’un outil de boîte à outils se connecte à un service qui n’a pas encore été autorisé, la passerelle Foundry requiert le consentement OAuth. Au lieu de déclencher une exception, get_tools()/aget_tools() retourne un outil de secours qui expose l’URL de consentement afin que votre agent puisse le présenter à l’utilisateur.

Lorsque vous appelez un agent et que le modèle appelle l’outil de secours, la réponse contient un message similaire à ce qui suit :

OAuth consent is required before this toolbox can be used. Open the following
URL in a browser to authorize access, then restart the agent:

  https://consent.azure-apim.net/...

Ouvrez l’URL dans un navigateur pour autoriser l’accès, puis redémarrez l’agent. Une fois que vous accordez le consentement, la boîte à outils charge normalement ses outils.

Charger des compétences à partir d’une boîte à outils

Une boîte à outils expose les compétences sous forme de ressources MCP avec des URI de la forme skill://{name}. Utilisez get_resources() pour les charger en tant qu’objets LangChain Blob. Chacun Blob porte le nom de la ressource dans sa source propriété et son URI brut sous metadata["uri"].

skill_blobs = toolbox.get_resources(scheme="skills")

for blob in skill_blobs:
    print(f"Skill: {blob.source}")
    print(blob.as_string())

Skill: jokes-teller/SKILL.md
{'content': '---\nname: jokes-teller\ndescription: A skill to tell jokes\n---\n\nUse...'}

Ce que fait cet extrait de code : Charge chaque skill:// ressource de la boîte à outils en tant que Blob. Le filtre scheme="skills" restreint les résultats aux ressources de compétences. La correspondance ne respecte pas la casse et accepte la forme singulière ou plurielle ("skill" ou "skills").

Pour charger des ressources spécifiques, transmettez explicitement leurs URI. Lorsque vous fournissez uris, le scheme filtre est ignoré :

skill_blobs = toolbox.get_resources(uris="skill://my-skill/SKILL.md")

Utiliser aget_resources() pour l’équivalent asynchrone :

skill_blobs = await toolbox.aget_resources(scheme="skills")

Charger des compétences pour les agents profonds

Si vous utilisez le package deepagents, appelez get_skills() pour charger les compétences de la boîte à outils sous forme de mappage de fichiers prêt à l’emploi pour create_deep_agent. Cette méthode s’appuie sur get_resources() et supprime le code répétitif lié à la conversion de chaque Blob en la structure de fichiers attendue par les agents profonds.

Installez le package :

pip install deepagents

L’exemple suivant montre comment ensemer une StateBackend (valeur par défaut). Laissez l’argument backend non défini et transmettez le mappage retourné en tant que files charge utile sur invoke:

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
skill_files = toolbox.get_skills()

agent = create_deep_agent(
    model="azure_ai:gpt-4.1",
    backend=StateBackend(),
    skills=["/skills/"],
)

agent.invoke({"messages": [HumanMessage("Use a skill")], "files": skill_files})

Ce que fait cet extrait de code : Charge les compétences de la boîte à outils dans une correspondance de chemins virtuels SKILL.md et les injecte dans l’état de l’agent via la charge utile files. L’agent peut ensuite utiliser les compétences sous le chemin de base /skills/.

Pour initialiser un backend avec un stockage autonome, comme FilesystemBackend, spécifiez-le comme argument backend. Les compétences sont définies dans le backend, et la même correspondance est également renvoyée :

from deepagents.backends import FilesystemBackend

backend = FilesystemBackend(root_dir="./my-project")
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
await toolbox.aget_skills(backend=backend)

agent = create_deep_agent(
    model="azure_ai:gpt-4.1",
    backend=backend,
    skills=["/skills/"],
)

Par défaut, les fichiers de compétence sont placés sous le chemin de base /skills/. Passez un autre base_path pour modifier l’emplacement. La valeur doit commencer et se terminer par une barre oblique, et vous passez la même valeur à l’argument skills de create_deep_agent.

Étape suivante

Utiliser le service d'agent Foundry avec LangGraph

Contenu connexe

  • Dernière mise à jour :