Použití sady nástrojů Foundry s jazykem LangChain

langchain-azure-ai Balíček použijte k načtení nástrojů a dovedností ze sady nástrojů Foundry do agentů LangChain a LangGraph. Foundry Toolbox je spravovaný server pro více MCP, který sdružuje několik nakonfigurovaných nástrojů za jediným koncovým bodem MCP (Model Context Protocol).

Naučíte se načítat nástroje, identifikovat nástroje, které vyžadují schválení, načítat dovednosti z panelu nástrojů jako prostředky a připravit dovednosti pro agenty Deep.

Předpoklady

• Předplatné služby Azure. Vytvořte si ho zdarma.
• Projekt Foundry.
• Nasazený chatovací model (například gpt-4.1) v projektu.
• Sada nástrojů nakonfigurovaná v projektu Foundry Poznamenejte si jeho název.
• Python 3.10 nebo novější.
• Azure CLI je přihlášen (az login), takže DefaultAzureCredential se může ověřit.

Nainstalujte požadované balíčky:

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

Integrace sady nástrojů vyžaduje langchain-mcp-adapters a httpx. Chcete-li načíst dovednosti pro agenty deep, nainstalujte také deepagents.

Konfigurujte své prostředí

Sada nástrojů potřebuje koncový bod projektu a název sady nástrojů. Zadejte je jako argumenty konstruktoru nebo prostřednictvím proměnných prostředí.

Nastavte proměnné prostředí:

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

Integrace také podporuje proměnnou prostředí FOUNDRY_PROJECT_ENDPOINT jako záložní možnost pro endpoint projektu.

Importujte běžné třídy a inicializujete model použitý v tomto článku:

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

Připojení k sadě nástrojů

Použijte AzureAIProjectToolbox z jmenného prostoru langchain_azure_ai.tools pro připojení k panelu nástrojů. Integrace rozpozná propojení projektu, když nastavíte proměnnou prostředí FOUNDRY_PROJECT_ENDPOINT. Microsoft Entra ID je výchozí metoda ověřování.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Při nastavování proměnných prostředí můžete vynechat argumenty konstruktoru:

toolbox = AzureAIProjectToolbox()

Referenční informace:AzureAIProjectToolbox

Načtení nástrojů ze sady nástrojů

Zavolejte aget_tools() a otevřete relaci se sadou nástrojů a načtěte všechny nástroje, které zpřístupňuje, jako instance LangChain BaseTool. Každé volání je bezstavové: otevře novou relaci MCP, načte nástroje a vrátí je.

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)

Co tento fragment kódu dělá: Připojuje se k sadě nástrojů, načítá její nástroje a přiřazuje je agentovi. Při vyvolání agenta může model volat libovolný nástroj, který sada nástrojů poskytuje k zodpovězení požadavku.

AzureAIProjectToolbox podporuje také asynchronní protokol správce kontextu. Chování je stejné, protože každé aget_tools() volání spravuje vlastní relaci:

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

Referenční informace:create_agent

Identifikace nástrojů, které vyžadují schválení

Některé nástroje sady nástrojů jsou nakonfigurované tak, aby před spuštěním vyžadovaly schválení. Zavolejte get_tools_requiring_approval(), chcete-li získat názvy těchto nástrojů, abyste před spuštěním mohli přidat krok se zapojením člověka.

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

Co tento fragment kódu dělá: Zkontroluje metadata panelu nástrojů a vrátí názvy nástrojů, jejichž konfigurace je nastavena require_approval na always. Tento seznam slouží k podmínění citlivých operací schvalovacím procesem.

Tato funkce je nezávislá na zpracování souhlasu OAuth. Další informace o schvalování se zapojením člověka naleznete v tématu Použití služby Foundry Agent Service s LangGraph.

Zpracování souhlasu OAuth

Toolbox v Microsoft Foundry podporuje pracovní postupy typu on-behalf-of. Požadavky na autorizaci můžete nakonfigurovat při přidávání nástrojů do sady nástrojů.

Když se nástroj sady nástrojů připojí ke službě, která ještě nebyla autorizovaná, brána Foundry vyžaduje souhlas OAuth. Místo vyvolání výjimky vrátí náhradní nástroj, který zobrazí adresu URL souhlasu, get_tools()/aget_tools() aby ho váš agent mohl uživateli prezentovat.

Když vyvoláte agenta a model volá záložní nástroj, odpověď obsahuje zprávu podobnou této:

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

Otevřete adresu URL v prohlížeči, abyste autorizovali přístup, a restartujte agenta. Po udělení souhlasu sada nástrojů normálně načte své nástroje.

Načtení dovedností z panelu nástrojů

Sada nástrojů může zpřístupnit dovednosti. Sada nástrojů zpřístupňuje dovednosti jako prostředky MCP s identifikátory URI ve tvaru skill://{name}. Použijte get_resources() k jejich načtení jako objektů LangChain Blob. Každý Blob obsahuje název prostředku ve vlastnosti source a jeho nezpracované URI v 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...'}

Co tento úryvek kódu dělá: Načte všechny skill:// prostředky ze sady nástrojů jako Blob. Filtr scheme="skills" omezuje výsledky na zdroje dovedností. Porovnání nerozlišuje malá a velká písmena a akceptuje jednotné nebo množné číslo ("skill" nebo "skills").

Chcete-li načíst konkrétní zdroje, předejte jejich adresy URI výslovně. Když zadáte uris, scheme filtr se ignoruje:

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

Používá se aget_resources() pro asynchronní ekvivalent:

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

Dovednosti při načítání pro hluboké agenty

Pokud používáte balíček deepagents, zavolejte get_skills() pro načtení dovedností sady nástrojů jako předem připraveného mapování souborů pro create_deep_agent. Tato metoda vychází z get_resources() a odstraňuje nutnost rutinního převodu každého Blob do struktury souborů, kterou pokročilí agenti očekávají.

Nainstalujte balíček:

pip install deepagents

Následující příklad naplní StateBackend počátečními daty (výchozí). Ponechte argument backend nenastavený a předejte vrácené mapování jako datovou část files u 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})

Co tento fragment kódu dělá: Načte dovednosti sady nástrojů do mapování virtuálních SKILL.md cest a zasadí je do stavu agenta prostřednictvím files datové části. Agent pak může využívat dovednosti pod základní cestou /skills/.

Chcete-li inicializovat backend se samostatným úložištěm, například FilesystemBackend, předejte jej jako argument backend. Dovednosti se zapisují do backendu a vrací se také stejné mapování:

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

Ve výchozím nastavení jsou soubory dovedností umístěny v základní cestě /skills/. Chcete-li změnit umístění, předejte jiné base_path. Hodnota musí začínat i končit lomítkem a stejnou hodnotu předáte do argumentu skills prvku create_deep_agent.

Další krok

Použijte službu Foundry Agent s LangGraph

Související obsah

• Použijte službu Foundry Agent s LangGraph
• Začínáme s Microsoft Foundry SDK a koncovými body
• balíček langchain-azure-ai v PyPI