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

• Un abonnement Azure. Créez-en un gratuitement.
• Un projet Foundry.
• Modèle de chat déployé (par exemple gpt-4.1) dans votre projet.
• Boîte à outils configurée dans votre projet Foundry. Notez son nom.
• Python 3.10 ou version ultérieure.
• Azure CLI connecté (az login) afin que DefaultAzureCredential puisse s’authentifier.

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. Fournissez-les en tant qu’arguments de constructeur ou via des variables d’environnement.

Définissez vos variables d’environnement :

import os

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

# Name of the toolbox configured in your Foundry project
os.environ["FOUNDRY_AGENT_TOOLBOX_NAME"] = "<your-toolbox-name>"

L’intégration accepte également la FOUNDRY_PROJECT_ENDPOINT variable d’environnement comme secours pour le point de terminaison du projet.

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
from azure.identity import DefaultAzureCredential

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

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 les variables d’environnement, vous pouvez omettre les arguments du constructeur :

toolbox = AzureAIProjectToolbox()

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.

Gérer le consentement OAuth

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.

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 peut exposer des compétences. 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: An 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

Contenu connexe

• Utiliser le service d'agent Foundry avec LangGraph
• Commencez avec les SDKs de Microsoft Foundry et points-de-terminaison
• package langchain-azure-ai sur PyPI