Użyj Foundry Toolbox z LangChain

Użyj pakietu langchain-azure-ai, aby wczytać narzędzia i umiejętności z zestawu narzędzi Foundry do agentów LangChain i LangGraph. Przybornik Foundry to zarządzany serwer wielo-MCP, który agreguje wiele skonfigurowanych narzędzi za pośrednictwem jednego punktu końcowego protokołu Model Context Protocol (MCP).

Dowiesz się, jak wczytywać narzędzia, identyfikować narzędzia wymagające zatwierdzenia, wczytywać umiejętności zestawu narzędzi jako zasoby oraz przygotowywać umiejętności dla agentów głębokich.

Wymagania wstępne

• Subskrypcja platformy Azure. Utwórz je bezpłatnie.
• Projekt Foundry.
• Wdrożony model czatu (na przykład gpt-4.1) w projekcie.
• Przybornik skonfigurowany w projekcie Foundry. Zanotuj jego nazwę.
• Python 3.10 lub nowszy.
• Azure CLI jest zalogowane (az login), więc DefaultAzureCredential może się uwierzytelnić.

Zainstaluj wymagane pakiety:

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

Integracja z przybornikiem wymaga langchain-mcp-adapters i httpx. Aby załadować umiejętności dla agentów Deep, zainstaluj również deepagents.

Konfigurowanie środowiska

Zestaw narzędzi potrzebuje punktu końcowego projektu i nazwy zestawu narzędzi. Podaj je jako argumenty konstruktora lub za pomocą zmiennych środowiskowych.

Ustaw zmienne środowiskowe:

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

Integracja akceptuje również zmienną FOUNDRY_PROJECT_ENDPOINT środowiskową jako rezerwę dla punktu końcowego projektu.

Zaimportuj typowe klasy i zainicjuj model używany w tym artykule:

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

Połącz z zestawem narzędzi

Użyj AzureAIProjectToolbox z przestrzeni nazw langchain_azure_ai.tools, aby nawiązać połączenie z przybornikiem. Integracja wykrywa połączenie projektu podczas ustawiania zmiennej środowiskowej FOUNDRY_PROJECT_ENDPOINT . Microsoft Entra ID jest domyślną metodą uwierzytelniania.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Po ustawieniu zmiennych środowiskowych można pominąć argumenty konstruktora:

toolbox = AzureAIProjectToolbox()

Dokumentacja:AzureAIProjectToolbox

Załaduj narzędzia z przybornika

Wywołaj aget_tools(), aby otworzyć sesję z zestawem narzędzi i załadować wszystkie udostępniane przez niego narzędzia jako instancje LangChain BaseTool. Każde wywołanie jest bezstanowe: otwiera nową sesję MCP, ładuje narzędzia i zwraca 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 robi ten fragment kodu: Łączy się z zestawem narzędzi, ładuje jego narzędzia i przypisuje je do agenta. Po wywołaniu agenta model może użyć dowolnego narzędzia udostępnianego przez zestaw narzędzi, aby odpowiedzieć na żądanie.

AzureAIProjectToolbox Obsługuje również protokół asynchronicznego menedżera kontekstu. Zachowanie jest identyczne, ponieważ każde aget_tools() wywołanie zarządza własną sesją:

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

Dokumentacja:create_agent

Identyfikowanie narzędzi wymagających zatwierdzenia

Niektóre narzędzia z zestawu narzędzi są skonfigurowane tak, by przed uruchomieniem wymagały zatwierdzenia. Wywołaj get_tools_requiring_approval(), aby pobrać nazwy tych narzędzi, dzięki czemu będzie można dodać krok z udziałem człowieka przed ich uruchomieniem.

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 robi ten fragment kodu: Sprawdza metadane zestawu narzędzi i zwraca nazwy narzędzi, których konfiguracja ustawia require_approval na always. Użyj tej listy, aby objąć wrażliwe operacje procesem zatwierdzania.

Ta funkcja jest niezależna od obsługi zgody protokołu OAuth. Aby uzyskać więcej informacji na temat zatwierdzania z udziałem człowieka, zobacz Używanie usługi Foundry Agent Service z LangGraph.

Obsługa zgody OAuth

Toolbox w Microsoft Foundry może obsługiwać przepływy pracy typu on-behalf-of. Wymagania dotyczące autoryzacji można skonfigurować podczas dodawania narzędzi do przybornika.

Gdy narzędzie z przybornika łączy się z usługą, która nie została jeszcze autoryzowana, brama Foundry wymaga zgody OAuth. Zamiast zgłaszać wyjątek, get_tools()/aget_tools() zwraca narzędzie rezerwowe, które wyświetla adres URL zgody, aby agent mógł przedstawić go użytkownikowi.

Gdy wywołasz agenta, a model użyje narzędzia zapasowego, odpowiedź będzie zawierać komunikat podobny do poniższego:

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

Otwórz adres URL w przeglądarce, aby autoryzować dostęp, a następnie uruchom ponownie agenta. Po wyrażeniu zgody zestaw narzędzi ładuje się prawidłowo.

Załaduj umiejętności z przybornika

Zestaw narzędzi może udostępniać umiejętności. Zestaw narzędzi udostępnia umiejętności jako zasoby MCP z identyfikatorami URI w postaci skill://{name}. Użyj get_resources(), aby załadować je jako obiekty LangChain Blob. Każdy Blob zawiera nazwę zasobu we właściwości source oraz jego nieprzetworzony identyfikator URI we właściwości 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 robi ten fragment kodu: Ładuje każdy skill:// zasób z przybornika jako Blob. Filtr scheme="skills" ogranicza wyniki do zasobów dotyczących umiejętności. Dopasowanie jest niewrażliwe na wielkość liter i akceptuje postać pojedynczą lub mnogą ("skill" lub "skills").

Aby załadować określone zasoby, przekaż jawnie ich identyfikatory URI. Po podaniu uris filtr scheme jest ignorowany:

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

Użyj aget_resources() dla odpowiednika asynchronicznego:

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

Ładuj umiejętności dla agentów głębokich

Jeśli używasz pakietu deepagents, wywołaj get_skills(), aby załadować umiejętności zestawu narzędzi jako gotowe do użycia mapowanie plików dla create_deep_agent. Ta metoda opiera się na get_resources() i eliminuje żmudną, powtarzalną konieczność konwertowania każdego Blob do układu plików, jakiego oczekują agenci deep.

Zainstaluj pakiet:

pip install deepagents

Poniższy przykład zawiera element ( StateBackend wartość domyślna). Pozostaw argument backend nieustawiony i przekaż zwrócone mapowanie jako ładunek files w 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 robi ten fragment: Ładuje umiejętności zestawu narzędzi do mapowania wirtualnych ścieżek SKILL.md i wprowadza je do stanu agenta za pośrednictwem ładunku danych files. Agent może następnie korzystać z umiejętności w ramach ścieżki /skills/ podstawowej.

Aby zainicjować backend z samodzielnym magazynem danych, takim jak FilesystemBackend, należy przekazać go jako argument backend. Umiejętności są zapisywane w backendzie, a zwracane jest również to samo mapowanie:

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

Domyślnie pliki umiejętności są umieszczane w ścieżce podstawowej /skills/. Przekaż inny base_path element, aby zmienić lokalizację. Wartość musi zaczynać się i kończyć ukośnikiem, a tę samą wartość przekazujesz do argumentu skills elementu create_deep_agent.

Następny krok

Użyj usługi Foundry Agent z LangGraph

Treści powiązane

• Użyj usługi Foundry Agent z LangGraph
• Rozpocznij pracę z zestawami SDK i punktami końcowymi Microsoft Foundry
• pakiet langchain-azure-ai w PyPI