Uso de Foundry Toolbox con LangChain

Utilice el paquete langchain-azure-ai para cargar herramientas y habilidades desde un Foundry Toolbox en sus agentes de LangChain y LangGraph. Foundry Toolbox es un servidor multi-MCP gestionado que agrupa varias herramientas configuradas en un único punto de conexión del Protocolo de Contexto de Modelo (MCP).

Aprenderá cómo cargar herramientas, identificar las herramientas que requieren aprobación, cargar las habilidades de la caja de herramientas como recursos y preparar habilidades para agentes avanzados.

Prerequisites

  • Una suscripción a Azure. Crear uno gratis.
  • Un proyecto de Foundry.
  • Un modelo de chat implementado (por ejemplo, gpt-4.1) en el proyecto.
  • Una caja de herramientas configurada en tu proyecto de Foundry. Anote su nombre.
  • Python 3.10 o posterior.
  • CLI de Azure ha iniciado sesión (az login) para que DefaultAzureCredential pueda autenticarse.

Instale los paquetes necesarios:

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

La integración del cuadro de herramientas requiere langchain-mcp-adapters y httpx. Para cargar habilidades para agentes deep, instale también deepagents.

Configuración del entorno

La caja de herramientas necesita un extremo del proyecto y un nombre de la caja de herramientas. Proporciónelos como argumentos de constructor o mediante variables de entorno.

Establezca las variables de entorno:

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>"

La integración también acepta la variable de entorno FOUNDRY_PROJECT_ENDPOINT como alternativa para el endpoint del proyecto.

Importe las clases comunes e inicialice el modelo usado en este artículo:

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")

Conexión a un cuadro de herramientas

Utilice AzureAIProjectToolbox del espacio de nombres langchain_azure_ai.tools para conectarse a un cuadro de herramientas. La integración detecta la conexión del proyecto al establecer la FOUNDRY_PROJECT_ENDPOINT variable de entorno. Microsoft Entra ID es el método de autenticación predeterminado.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Al establecer las variables de entorno, puede omitir los argumentos del constructor:

toolbox = AzureAIProjectToolbox()

Reference:AzureAIProjectToolbox

Carga de herramientas desde un cuadro de herramientas

Llame a aget_tools() para abrir una sesión con la caja de herramientas y cargar todas las herramientas que expone como instancias de LangChain BaseTool. Cada llamada no tiene estado: abre una nueva sesión de MCP, carga las herramientas y las devuelve.

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)

Qué hace este fragmento de código: Se conecta al cuadro de herramientas, carga sus herramientas y los enlaza a un agente. Al invocar al agente, el modelo puede llamar a cualquier herramienta que proporcione el cuadro de herramientas para responder a la solicitud.

AzureAIProjectToolbox también admite el protocolo de administrador de contexto asincrónico. El comportamiento es idéntico porque cada aget_tools() llamada administra su propia sesión:

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

Reference:create_agent

Identificación de herramientas que requieren aprobación

Algunas herramientas del cuadro de herramientas están configuradas para requerir aprobación antes de que se ejecuten. Llame a get_tools_requiring_approval() para recuperar los nombres de esas herramientas, de modo que pueda añadir un paso de supervisión humana antes de ejecutarlas.

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}")

Qué hace este fragmento de código: Inspecciona los metadatos del cuadro de herramientas y devuelve los nombres de las herramientas cuyos conjuntos de configuración se establecen require_approval en always. Utiliza esta lista para someter las operaciones sensibles a un flujo de aprobación.

Esta funcionalidad es independiente del control de consentimiento de OAuth. Para obtener más información sobre las aprobaciones con intervención humana, consulte Uso de Foundry Agent Service con LangGraph.

La caja de herramientas de Microsoft Foundry puede gestionar flujos de trabajo en nombre de otro usuario. Puede configurar los requisitos de autorización al agregar las herramientas al cuadro de herramientas.

Captura de pantalla que muestra cómo configurar un servidor MCP con un flujo de trabajo de suplantación.

Cuando una herramienta del cuadro de herramientas se conecta a un servicio que aún no se ha autorizado, la puerta de enlace de Foundry requiere el consentimiento de OAuth. En lugar de lanzar una excepción, get_tools()/aget_tools() devuelve una herramienta alternativa que expone la URL de consentimiento para que el agente se la presente al usuario.

Cuando se invoca un agente y el modelo llama a la herramienta de reserva, la respuesta contiene un mensaje similar al siguiente:

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/...

Abra la dirección URL en un explorador para autorizar el acceso y reinicie el agente. Después de dar tu consentimiento, la caja de herramientas carga sus herramientas con normalidad.

Cargar habilidades desde una caja de herramientas

Un cuadro de herramientas puede exponer aptitudes. Una caja de herramientas expone capacidades como recursos MCP con URI de la forma skill://{name}. Se usa get_resources() para cargarlos como objetos LangChain Blob . Cada Blob lleva el nombre del recurso en la propiedad source y su URI sin procesar en 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...'}

Qué hace este fragmento de código: Carga todos los skill:// recursos del cuadro de herramientas como .Blob El scheme="skills" filtro limita los resultados a los recursos de habilidades. La coincidencia no distingue mayúsculas de minúsculas y acepta la forma singular o plural ("skill" o "skills").

Para cargar recursos específicos, pase sus URI explícitamente. Cuando se proporciona uris, se omite el scheme filtro:

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

Use aget_resources() para el equivalente asincrónico:

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

Aptitudes de carga para agentes profundos

Si usa el paquete deepagents, llame a get_skills() para cargar las habilidades de Toolbox como una asignación de archivos lista para usar para create_deep_agent. Este método se basa en get_resources() y elimina el código repetitivo de convertir cada Blob en la estructura de archivos que esperan los agentes avanzados.

Instala el paquete:

pip install deepagents

El ejemplo siguiente propaga un StateBackend (el valor predeterminado). Deje sin establecer el argumento backend y pase el mapeo devuelto como la carga files en 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})

Qué hace este fragmento de código: Carga las habilidades de la caja de herramientas en una asignación de rutas virtuales SKILL.md y las incorpora al estado del agente a través de la files carga útil. A continuación, el agente puede usar las habilidades bajo la ruta de acceso base /skills/.

Para inicializar un back-end con almacenamiento independiente, como FilesystemBackend, páselo como argumento backend . Las habilidades se registran en el backend y también se devuelve el mismo mapeo:

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/"],
)

De forma predeterminada, los archivos de habilidades se colocan en la ruta base /skills/. Pase un valor diferente base_path para cambiar la ubicación. El valor debe comenzar y terminar con una barra diagonal, y pasar el mismo valor al argumento skills de create_deep_agent.

Paso siguiente

Utilice el servicio de agente Foundry con LangGraph

Contenido relacionado

  • Last updated on