Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Verwenden Sie das langchain-azure-ai Paket, um Tools und Fähigkeiten aus einer Foundry Toolbox in Ihre LangChain- und LangGraph-Agents zu laden. Eine Foundry Toolbox ist ein verwalteter Multi-MCP-Server, der mehrere konfigurierte Tools hinter einem einzelnen MCP-Endpunkt (Model Context Protocol) aggregiert.
Sie erfahren, wie Sie Tools laden, Tools identifizieren, für die eine Genehmigung erforderlich ist, Skills aus der Toolbox als Ressourcen laden und Skills für Deep Agents vorbereiten.
Voraussetzungen
- Ein Azure-Abonnement. Erstellen Sie ein kostenloses Konto.
- Ein Foundry-Projekt.
- Ein bereitgestelltes Chatmodell (z. B.
gpt-4.1) in Ihrem Projekt. - Eine Toolbox, die in Ihrem Foundry-Projekt konfiguriert ist. Notieren Sie sich seinen Namen.
- Python 3.10 oder höher.
- Azure CLI ist angemeldet (
az login), damitDefaultAzureCredentialsich authentifizieren kann.
Installieren Sie die erforderlichen Pakete:
pip install -U langchain-azure-ai langchain-mcp-adapters httpx azure-identity
Die Toolboxintegration erfordert langchain-mcp-adapters und httpx. Um Fähigkeiten für Deep Agents zu laden, installieren Sie auch deepagents.
Konfigurieren Ihrer Umgebung
Die Toolbox benötigt einen Projektendpunkt und einen Toolboxnamen. Stellen Sie sie als Konstruktorargumente oder über Umgebungsvariablen bereit.
Festlegen von Umgebungsvariablen:
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>"
Die Integration akzeptiert auch die FOUNDRY_PROJECT_ENDPOINT Umgebungsvariable als Fallback für den Projektendpunkt.
Importieren Sie die allgemeinen Klassen, und initialisieren Sie das in diesem Artikel verwendete Modell:
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")
Mit einer Toolbox verbinden
Verwenden Sie AzureAIProjectToolbox aus dem Namespace langchain_azure_ai.tools, um eine Verbindung zu einer Toolbox herzustellen. Die Integration erkennt die Projektverbindung, wenn Sie die FOUNDRY_PROJECT_ENDPOINT Umgebungsvariable festlegen. Microsoft Entra ID ist die Standardauthentifizierungsmethode.
from langchain_azure_ai.tools import AzureAIProjectToolbox
toolbox = AzureAIProjectToolbox(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
toolbox_name="my-toolbox",
)
Wenn Sie die Umgebungsvariablen festlegen, können Sie die Konstruktorargumente weglassen:
toolbox = AzureAIProjectToolbox()
Referenz:AzureAIProjectToolbox
Laden von Tools aus einer Toolbox
Rufen Sie aget_tools() auf, um eine Sitzung mit der Toolbox zu öffnen und alle Tools zu laden, die sie als LangChain-BaseTool-Instanzen bereitstellt. Jeder Aufruf ist zustandslos: Es öffnet eine neue MCP-Sitzung, lädt die Tools und gibt sie zurück.
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)
Funktionsweise dieses Codeausschnitts: Stellt eine Verbindung mit der Toolbox bereit, lädt seine Tools und bindet sie an einen Agent. Wenn Sie den Agent aufrufen, kann das Modell jedes Tool aufrufen, das von der Toolbox bereitgestellt wird, um die Anforderung zu beantworten.
AzureAIProjectToolbox unterstützt auch das asynchrone Kontext-Manager-Protokoll. Das Verhalten ist identisch, da jeder aget_tools() Anruf eine eigene Sitzung verwaltet:
async with AzureAIProjectToolbox(toolbox_name="my-toolbox") as toolbox:
tools = await toolbox.aget_tools()
Reference:create_agent
Identifizieren von Tools, die eine Genehmigung erfordern
Einige Tools in der Toolbox sind so konfiguriert, dass sie vor der Ausführung eine Genehmigung erfordern. Rufen Sie get_tools_requiring_approval() auf, um die Namen dieser Werkzeuge abzurufen, damit Sie vor der Ausführung einen Schritt mit menschlicher Beteiligung hinzufügen können.
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}")
Was dieser Codeausschnitt macht: Überprüft die Toolbox-Metadaten und gibt die Namen der Tools zurück, deren Konfiguration require_approval auf always setzt. Verwenden Sie diese Liste, um vertrauliche Vorgänge hinter einem Genehmigungsworkflow zu schützen.
Diese Funktion ist unabhängig von der OAuth-Zustimmungsverarbeitung. Weitere Informationen zu Genehmigungen mit menschlicher Freigabe finden Sie unter Verwenden von Foundry Agent Service mit LangGraph.
OAuth-Einwilligung verarbeiten
Toolbox in Microsoft Foundry kann On-Behalf-Of-Workflows verarbeiten. Sie können die Autorisierungsanforderungen konfigurieren, wenn Sie die Tools zu Ihrer Toolbox hinzufügen.
Wenn ein Toolboxtool eine Verbindung mit einem Dienst herstellt, der noch nicht autorisiert wurde, erfordert das Foundry-Gateway OAuth-Zustimmung. Statt eine Ausnahme auszulösen, wird ein Fallbacktool zurückgegeben, get_tools()/aget_tools() mit dem die Zustimmungs-URL angezeigt wird, damit ihr Agent sie dem Benutzer präsentieren kann.
Wenn Sie einen Agent aufrufen und das Modell das Fallbacktool aufruft, enthält die Antwort eine Meldung ähnlich der folgenden:
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/...
Öffnen Sie die URL in einem Browser, um den Zugriff zu autorisieren, und starten Sie den Agent neu. Nachdem Sie die Zustimmung erteilt haben, lädt die Toolbox ihre Tools normal.
Fertigkeiten aus einer Toolbox laden
Eine Toolbox kann Fähigkeiten verfügbar machen. Eine Toolbox macht Fähigkeiten als MCP-Ressourcen mit URIs des Formulars skill://{name}verfügbar. Verwenden Sie get_resources(), um sie als LangChain-Objekte Blob zu laden. Jeder Blob enthält den Ressourcennamen in seiner source-Eigenschaft und die rohe URI unter 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...'}
Funktionsweise dieses Codeausschnitts: Lädt jede skill:// Ressource aus der Toolbox als eine Blob. Der scheme="skills" Filter beschränkt die Ergebnisse auf Qualifikationsressourcen. Die Übereinstimmung berücksichtigt die Groß-/Kleinschreibung nicht und akzeptiert die Singular- oder Pluralform ("skill" oder "skills").
Um bestimmte Ressourcen zu laden, übergeben Sie ihre URIs explizit. Wenn Sie angeben uris, wird der scheme Filter ignoriert:
skill_blobs = toolbox.get_resources(uris="skill://my-skill/SKILL.md")
Verwenden Sie aget_resources() für das asynchrone Äquivalent:
skill_blobs = await toolbox.aget_resources(scheme="skills")
Laden von Skills für Deep-Agents
Wenn Sie das deepagents-Paket verwenden, rufen Sie get_skills() auf, um Toolbox-Skills als gebrauchsfertige Dateizuordnung für create_deep_agent zu laden. Diese Methode baut auf get_resources() auf und beseitigt den Boilerplate-Code für die Konvertierung jedes Blob in das Dateilayout, das Deep-Agents erwarten.
Installiere das Paket:
pip install deepagents
Im folgenden Beispiel wird standardmäßig ein StateBackend verwendet. Lassen Sie das backend-Argument nicht festgelegt, und übergeben Sie die zurückgegebene Zuordnung als files-Payload für 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})
Was dieser Codeausschnitt macht: Er lädt die Skills der Toolbox in eine Zuordnung virtueller SKILL.md-Pfade und fügt sie über die files-Payload in den Agentstatus ein. Der Agent kann dann die unter dem /skills/ Basispfad verfügbaren Fähigkeiten verwenden.
Um ein Backend mit eigenständigem Speicher zu initialisieren, wie FilesystemBackend, übergeben Sie ihn als Argument backend. Die Fähigkeiten werden im Backend hinterlegt, und dieselbe Zuordnung wird ebenfalls zurückgegeben:
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/"],
)
Standardmäßig werden Qualifikationsdateien unter dem /skills/ Basispfad platziert. Übergeben Sie einen anderen base_path, um den Speicherort zu ändern. Der Wert muss mit einem Schrägstrich beginnen und enden, und Sie übergeben denselben Wert an das skills Argument von create_deep_agent.