Foundry Toolbox gebruiken met LangChain

Gebruik het langchain-azure-ai pakket om hulpprogramma's en vaardigheden van een Foundry Toolbox in uw LangChain- en LangGraph-agents te laden. Een Foundry Toolbox is een beheerde multi-MCP-server waarmee meerdere geconfigureerde hulpprogramma's achter één MCP-eindpunt (Model Context Protocol) worden samengevoegd.

U leert hoe u hulpmiddelen laadt, hulpmiddelen identificeert waarvoor goedkeuring is vereist, vaardigheden uit de toolbox als bronnen laadt en vaardigheden voorbereidt voor deep agents.

Prerequisites

• Een Azure-abonnement. Maak er gratis een.
• Een Gieterij-project.
• Een geïmplementeerd chatmodel (bijvoorbeeld gpt-4.1) in uw project.
• Een toolbox die in uw Foundry-project is geconfigureerd. Noteer de naam.
• Python 3.10 of hoger.
• Azure CLI aangemeld (az login), zodat DefaultAzureCredential kan authenticeren.

Installeer de vereiste pakketten:

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

De integratie van de werkset vereist langchain-mcp-adapters en httpx. Om vaardigheden voor deep agents te laden, moet u ook deepagents installeren.

Uw omgeving configureren

De toolbox heeft een project-eindpunt en een toolboxnaam nodig. Geef deze op als constructorargumenten of via omgevingsvariabelen.

Stel uw omgevingsvariabelen in:

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

De integratie accepteert ook de FOUNDRY_PROJECT_ENDPOINT omgevingsvariabele als een terugval voor het projecteindpunt.

Importeer de algemene klassen en initialiseer het model dat in dit artikel wordt gebruikt:

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

Verbinden met een gereedschapskist

Gebruik AzureAIProjectToolbox uit de naamruimte langchain_azure_ai.tools om verbinding te maken met een toolbox. De integratie detecteert de projectverbinding wanneer u de FOUNDRY_PROJECT_ENDPOINT omgevingsvariabele instelt. Microsoft Entra ID is de standaardverificatiemethode.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Wanneer u de omgevingsvariabelen instelt, kunt u de constructorargumenten weglaten:

toolbox = AzureAIProjectToolbox()

Naslaginformatie:AzureAIProjectToolbox

Hulpmiddelen laden uit een gereedschapskist

Roep aget_tools() aan om een sessie met de toolbox te openen en laad alle tools die deze beschikbaar stelt als LangChain-BaseTool-instanties. Elke aanroep is staatloos: er wordt een verse MCP-sessie geopend, de hulpprogramma's worden geladen en vervolgens teruggegeven.

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)

Wat dit codefragment doet: Maakt verbinding met de werkset, laadt de hulpprogramma's en verbindt deze met een agent. Wanneer u de agent aanroept, kan het model elk hulpprogramma aanroepen dat de werkset biedt om de aanvraag te beantwoorden.

AzureAIProjectToolbox ondersteunt ook het asynchrone contextbeheerprotocol. Het gedrag is identiek omdat elke aget_tools() aanroep een eigen sessie beheert:

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

Verwijzing:create_agent

Hulpprogramma's identificeren waarvoor goedkeuring is vereist

Sommige toolboxhulpmiddelen zijn zo geconfigureerd dat ze goedkeuring vereisen voordat ze kunnen worden uitgevoerd. Roep get_tools_requiring_approval() aan om de namen van deze hulpprogramma's op te halen, zodat u vóór de uitvoering een human-in-the-loop-stap kunt toevoegen.

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

Wat dit codefragment doet: Inspecteert de metagegevens van de werkset en retourneert de namen van hulpprogramma's waarvan de configuratie is ingesteld require_approval op always. Gebruik deze lijst om gevoelige bewerkingen af te schermen achter een goedkeuringsworkflow.

Deze mogelijkheid is onafhankelijk van de verwerking van OAuth-toestemmingen. Zie Foundry Agent Service gebruiken met LangGraph voor meer informatie over goedkeuringen met menselijke tussenkomst.

OAuth-toestemming verwerken

Werkset in Microsoft Foundry kan namens werkstromen worden verwerkt. U kunt de autorisatievereisten configureren wanneer u de hulpprogramma's aan uw werkset toevoegt.

Wanneer een hulpprogramma voor werksets verbinding maakt met een service die nog niet is geautoriseerd, vereist de Foundry-gateway OAuth-toestemming. In plaats van een uitzondering te genereren, retourneert get_tools()/aget_tools() een fallbacktool die de consent-URL toont, zodat uw agent die aan de gebruiker kan tonen.

Wanneer u een agent aanroept en het model het terugvalhulpprogramma aanroept, bevat het antwoord een bericht dat vergelijkbaar is met het volgende:

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

Open de URL in een browser om toegang te autoriseren en start de agent opnieuw op. Nadat u toestemming hebt verleend, laadt de toolbox zijn hulpprogramma's normaal.

Vaardigheden uit een gereedschapskist laden

Een werkset kan vaardigheden blootstellen. Een toolbox stelt vaardigheden beschikbaar als MCP-bronnen met URI's in de vorm skill://{name}. Gebruik get_resources() om ze te laden als LangChain-Blobobjecten. Elke Blob bevat de naam van de resource in de eigenschap source en de ruwe URI onder 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...'}

Wat dit codefragment doet: Laadt elke skill:// resource uit de werkset als een Blob. De scheme="skills"-filter beperkt de resultaten tot hulpbronnen voor vaardigheden. Er wordt geen onderscheid gemaakt tussen hoofdletters en kleine letters en zowel het enkelvoud als het meervoud wordt geaccepteerd ("skill" of "skills").

Als u specifieke resources wilt laden, geeft u hun URI's expliciet door. Wanneer u opgeeft uris, wordt het scheme filter genegeerd:

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

Gebruik aget_resources() voor de asynchrone tegenhanger:

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

Vaardigheden voor diepe agents laden

Als u het deepagents-pakket gebruikt, roep get_skills() aan om toolboxvaardigheden te laden als een kant-en-klare bestandstoewijzing voor create_deep_agent. Deze methode bouwt voort op get_resources() en verwijdert de standaard voor het converteren van elk Blob bestand naar de bestandsindeling die deep agents verwachten.

Installeer het pakket:

pip install deepagents

In het volgende voorbeeld wordt een StateBackend (de standaardinstelling) gezaaid. Laat het argument backend niet ingesteld en geef de geretourneerde mapping door als de files payload op 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})

Wat dit codefragment doet: Laadt de vaardigheden uit de toolbox in een koppeling van virtueleSKILL.mdpaden en voegt ze via de files payload toe aan de agentstatus. De agent kan vervolgens de vaardigheden onder het basispad /skills/ gebruiken.

Als u een back-end wilt seeden met zelfstandige opslag, zoals FilesystemBackend, geeft u deze door als het backend argument. De vaardigheden worden in de backend opgeslagen en dezelfde mapping wordt eveneens geretourneerd:

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

Standaard worden vaardigheidsbestanden onder het /skills/ basispad geplaatst. Geef een andere base_path door om de locatie te wijzigen. De waarde moet beginnen en eindigen met een slash en u geeft dezelfde waarde door aan het skills argument van create_deep_agent.

Volgende stap

Verwante inhoud

• Foundry Agent Service gebruiken met LangGraph
• Aan de slag met Microsoft Foundry SDK's en eindpunten
• langchain-azure-ai-pakket op PyPI