Usare la casella degli strumenti Foundry con LangChain

Usa il pacchetto langchain-azure-ai per caricare strumenti e abilità da un Foundry Toolbox nei tuoi agenti LangChain e LangGraph. Una Toolbox Foundry è un server multi-MCP gestito che aggrega più strumenti configurati dietro un unico endpoint MCP (Model Context Protocol).

Si apprenderà come caricare gli strumenti, identificare gli strumenti che richiedono l'approvazione, caricare le competenze della casella degli strumenti come risorse e preparare le competenze per gli agenti avanzati.

Prerequisiti

  • Una sottoscrizione di Azure. Creane uno gratis.
  • Progetto Foundry.
  • Modello di chat distribuito (ad esempio, gpt-4.1) nel progetto.
  • Casella degli strumenti configurata nel progetto Foundry. Prendi nota del nome.
  • Python 3.10 o versione successiva.
  • Interfaccia della riga di comando di Azure connessa (az login) in modo che DefaultAzureCredential possa eseguire l'autenticazione.

Installare i pacchetti necessari:

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

L'integrazione della casella degli strumenti richiede langchain-mcp-adapters e httpx. Per caricare le competenze per i deep agent, installare anche deepagents.

Configurare il tuo ambiente

La casella degli strumenti richiede un endpoint del progetto e un nome della casella degli strumenti. Specificarli come argomenti del costruttore o tramite variabili di ambiente.

Impostare le variabili di ambiente:

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'integrazione accetta anche la FOUNDRY_PROJECT_ENDPOINT variabile di ambiente come fallback per l'endpoint del progetto.

Importare le classi comuni e inizializzare il modello usato in questo articolo:

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

Connettersi a una casella degli strumenti

Utilizzare AzureAIProjectToolbox dal namespace langchain_azure_ai.tools per connettersi a una toolbox. L'integrazione rileva la connessione al progetto quando si imposta la FOUNDRY_PROJECT_ENDPOINT variabile di ambiente. Microsoft Entra ID è il metodo di autenticazione predefinito.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Quando si impostano le variabili di ambiente, è possibile omettere gli argomenti del costruttore:

toolbox = AzureAIProjectToolbox()

Informazioni di riferimento:AzureAIProjectToolbox

Caricare gli strumenti dalla cassetta degli strumenti

Chiamare aget_tools() per aprire una sessione con il toolbox e caricare tutti gli strumenti che espone come istanze LangChain BaseTool. Ogni chiamata è priva di stato: apre una nuova sessione MCP, carica gli strumenti e li restituisce.

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)

Cosa fa questo frammento di codice: Si connette alla casella degli strumenti, carica gli strumenti e li associa a un agente. Quando si richiama l'agente, il modello può chiamare qualsiasi strumento fornito dalla casella degli strumenti per rispondere alla richiesta.

AzureAIProjectToolbox supporta anche il protocollo di gestione del contesto asincrono. Il comportamento è identico perché ogni aget_tools() chiamata gestisce la propria sessione:

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

Riferimento:create_agent

Identificare gli strumenti che richiedono l'approvazione

Alcuni strumenti della casella degli strumenti sono configurati per richiedere l'approvazione prima dell'esecuzione. Chiama get_tools_requiring_approval() per recuperare i nomi di tali strumenti, in modo da poter aggiungere un passaggio con intervento umano prima dell'esecuzione.

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

Cosa fa questo frammento di codice: Controlla i metadati della casella degli strumenti e restituisce i nomi degli strumenti i cui set di configurazione sono require_approvalalways. Usa questo elenco per subordinare le operazioni sensibili a un flusso di approvazione.

Questa funzionalità è indipendente dalla gestione del consenso OAuth. Per ulteriori informazioni sulle approvazioni con intervento umano, consultare Usare il Servizio agenti Foundry con LangGraph.

Toolbox in Microsoft Foundry può gestire i flussi di lavoro on-behalf-of. È possibile configurare i requisiti di autorizzazione quando si aggiungono gli strumenti alla casella degli strumenti.

Schermata che mostra come configurare un server MCP con un flusso di lavoro on-behalf-of.

Quando uno strumento della casella degli strumenti si connette a un servizio che non è ancora stato autorizzato, il gateway Foundry richiede il consenso OAuth. Anziché generare un'eccezione, get_tools()/aget_tools() restituisce uno strumento di fallback che espone l'URL di consenso in modo che l'agente possa presentarlo all'utente.

Quando si richiama un agente e il modello chiama lo strumento di fallback, la risposta contiene un messaggio simile al seguente:

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

Aprire l'URL in un browser per autorizzare l'accesso, quindi riavviare l'agente. Dopo aver fornito il consenso, la toolbox carica normalmente i suoi strumenti.

Carica le abilità dalla cassetta degli strumenti

Una casella degli strumenti può esporre competenze. Una toolbox espone le funzionalità come risorse MCP con URI del formato skill://{name}. Usare get_resources() per caricarli come oggetti LangChain Blob . Ogni Blob contiene il nome della risorsa nella proprietà source e il relativo URI grezzo in 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...'}

Cosa fa questo frammento di codice: Carica ogni skill:// risorsa dalla casella degli strumenti come .Blob Il filtro scheme="skills" restringe i risultati alle risorse relative alle competenze. La corrispondenza non fa distinzione tra maiuscole e minuscole e accetta il formato singolare o plurale ("skill" o "skills").

Per caricare risorse specifiche, passare gli URI in modo esplicito. Quando si specifica uris, il scheme filtro viene ignorato:

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

Usare aget_resources() per l'equivalente asincrono:

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

Competenze di caricamento per gli agenti avanzati

Se si utilizza il pacchetto deepagents, richiamare get_skills() per caricare le skill del toolbox come mappatura di file pronta all'uso per create_deep_agent. Questo metodo si basa su get_resources() ed elimina il lavoro ripetitivo necessario per convertire ogni Blob nel layout di file previsto dagli agenti deep.

Installare il pacchetto:

pip install deepagents

L'esempio seguente inizializza un StateBackend (quello predefinito). Lasciare l'argomento backend non impostato e passare il mapping restituito come payload files in 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})

Cosa fa questo frammento di codice: Carica le competenze della casella degli strumenti in un mapping di percorsi virtuali SKILL.md e li inserisce nello stato dell'agente attraverso il files payload. L'agente può quindi usare le abilità nel percorso di base /skills/.

Per inizializzare un back-end con archiviazione standalone, ad esempio FilesystemBackend, passarlo come argomento backend. Le competenze vengono scritte nel backend e viene restituita anche la stessa mappatura:

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

Per impostazione predefinita, i file delle competenze vengono collocati nel percorso di base /skills/. Passare un valore diverso base_path per modificare la posizione. Il valore deve iniziare e terminare con uno slash, e devi passare lo stesso valore all'argomento skills di create_deep_agent.

Passo successivo

Usare il servizio Foundry Agent con LangGraph

Contenuti correlati

  • Last updated on