Använda Foundry Toolbox med LangChain

langchain-azure-ai Använd paketet för att läsa in verktyg och färdigheter från en Foundry Toolbox till dina LangChain- och LangGraph-agenter. En Foundry Toolbox är en hanterad multi-MCP-server som aggregerar flera konfigurerade verktyg bakom en enda MCP-slutpunkt (Model Context Protocol).

Du lär dig hur du laddar verktyg, identifierar verktyg som kräver godkännande, laddar verktygslådans färdigheter som resurser och förbereder färdigheter för djupgående agenter.

Förutsättningar

• Ett Azure-abonnemang. Skapa en kostnadsfritt.
• Ett Foundry-projekt.
• En distribuerad chattmodell (till exempel gpt-4.1) i projektet.
• En verktygslåda som konfigurerats i ditt Foundry-projekt. Anteckna namnet.
• Python 3.10 eller senare.
• Azure CLI inloggad (az login) så DefaultAzureCredential kan autentisera.

Installera de paket som krävs:

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

Verktygslådans integrering kräver langchain-mcp-adapters och httpx. Om du vill ladda färdigheter för deep agents installerar du även deepagents.

Konfigurera din miljö

Verktygslådan behöver en projektslutpunkt och ett verktygslådans namn. Ange dem som konstruktorargument eller via miljövariabler.

Ange miljövariabler:

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

Integreringen FOUNDRY_PROJECT_ENDPOINT accepterar även miljövariabeln som en reserv för projektslutpunkten.

Importera de vanliga klasserna och initiera modellen som används i den här artikeln:

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

Ansluta till en verktygslåda

Använd AzureAIProjectToolbox från namnområdet langchain_azure_ai.tools för att ansluta till en verktygslåda. Integreringen identifierar projektanslutningen när du anger FOUNDRY_PROJECT_ENDPOINT miljövariabeln. Microsoft Entra ID är standardautentiseringsmetoden.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

När du anger miljövariablerna kan du utelämna konstruktorargumenten:

toolbox = AzureAIProjectToolbox()

Referens:AzureAIProjectToolbox

Ladda in verktyg från verktygslådan

Anropa aget_tools() för att öppna en session med verktygslådan och ladda in varje verktyg som den exponerar som LangChain-BaseToolinstanser. Varje anrop är tillståndslöst: det öppnar en ny MCP-session, läser in verktygen och returnerar dem.

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)

Vad det här kodfragmentet gör: Ansluter till verktygslådan, läser in dess verktyg och binder dem till en agent. När du anropar agenten kan modellen anropa alla verktyg som verktygslådan tillhandahåller för att besvara begäran.

AzureAIProjectToolbox stöder också det asynkrona context manager-protokollet. Beteendet är identiskt eftersom varje aget_tools() anrop hanterar sin egen session:

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

Referens:create_agent

Identifiera verktyg som kräver godkännande

Vissa verktygslådeverktyg är konfigurerade för att kräva godkännande innan de körs. Anropa get_tools_requiring_approval() för att hämta namnen på dessa verktyg så att du kan lägga till ett mänskligt-i-loop-steg före körning.

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

Vad det här kodfragmentet gör: Inspekterar verktygslådans metadata och returnerar namnen på verktyg vars konfigurationsuppsättningar require_approval är always. Använd den här listan för att lägga känsliga åtgärder bakom ett godkännandeflöde.

Den här funktionen är oberoende av OAuth-medgivandehantering. Mer information om godkännanden med människa i loopen finns i Använd Foundry Agent Service med LangGraph.

Hantera OAuth-medgivande

Toolbox i Microsoft Foundry kan hantera arbetsflöden där man agerar för någon annans räkning. Du kan konfigurera auktoriseringskraven när du lägger till verktygen i verktygslådan.

När ett verktygslådeverktyg ansluter till en tjänst som inte har auktoriserats ännu kräver Foundry-gatewayen OAuth-medgivande. I stället för att skapa ett undantag get_tools()/aget_tools() returnerar ett reservverktyg som visar medgivande-URL:en så att din agent kan presentera den för användaren.

När du anropar en agent och modellen anropar återställningsverktyget innehåller svaret ett meddelande som liknar följande:

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

Öppna URL:en i en webbläsare för att auktorisera åtkomst och starta sedan om agenten. När du har gett ditt samtycke laddar verktygslådan sina verktyg som vanligt.

Läs in kunskaper från en verktygslåda

En verktygslåda kan visa färdigheter. En verktygslåda exponerar färdigheter som MCP-resurser med URI:er av formen skill://{name}. Använd get_resources() för att läsa in dem som LangChain-objekt Blob . Varje Blob bär resursnamnet i egenskapen source och sin rå-URI under 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...'}

Vad det här kodfragmentet gör: Läser in varje skill:// resurs från verktygslådan som en Blob. scheme="skills" Filtret begränsar resultatet till kunskapsresurser. Matchningen är skiftlägesokänslig och accepterar singular- eller pluralformen ("skill" eller "skills").

Om du vill ladda specifika resurser anger du deras URI:er uttryckligen. När du anger urisscheme ignoreras filtret:

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

Använd aget_resources() för den asynkrona motsvarigheten:

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

Läs in kunskaper för djupagenter

Om du använder deepagents-paketet, anropar du get_skills() för att ladda in verktygslådefärdigheter som en färdiganvänd filmappning för create_deep_agent. Den här metoden bygger på get_resources() och eliminerar standardkoden för att konvertera varje Blob till den filstruktur som deep agents förväntar sig.

Installera paketet:

pip install deepagents

Följande exempel anger ett startvärde för StateBackend (standardinställningen). Lämna argumentet backend oinställt och skicka den returnerade mappningen som nyttolast i files på 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})

Vad det här kodfragmentet gör: Läser in verktygslådans färdigheter till en mappning av virtuella SKILL.md sökvägar och lägger in dem i agentens tillstånd via files-payloaden. Agenten kan sedan använda färdigheterna under bassökvägen /skills/.

Om du vill initiera en backend med fristående lagring, till exempel FilesystemBackend, skickar du den som argumentet backend. Färdigheterna skrivs in i serverdelen och samma mappning returneras också:

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

Som standard placeras kunskapsfiler under bassökvägen /skills/. Ange en annan base_path för att ändra placeringen. Värdet måste börja och sluta med ett snedstreck och du skickar samma värde till skills argumentet create_deep_agent.

Nästa steg

Relaterat innehåll

• Använd Foundry Agent Service med LangGraph
• Kom igång med Microsoft Foundry SDK och endpoints
• langchain-azure-ai-paket på PyPI