Verwenden einer Toolbox mit einem gehosteten Agent

Verwenden des Microsoft-Agent-Frameworks

Das verwaltete Python Beispiel verwendet FoundryToolbox aus dem Agent Framework-Hostingpaket. Die Klasse ermittelt die Toolbox aus TOOLBOX_ENDPOINT oder aus FOUNDRY_PROJECT_ENDPOINT und TOOLBOX_NAME. Außerdem authentifiziert es MCP-Anfragen und leitet die pro Anfrage vergebene Aufruf-ID der gehosteten Laufzeitumgebung weiter.

Installieren Sie Python 3.12 oder höher, Azure Developer CLI (azd) 1.25 oder höher, und die microsoft.foundry Erweiterung, bevor Sie das Beispiel initialisieren.

1. Initialisieren Sie ein Projekt anhand des Hosted-Agent-Toolbox-Beispiels:

   mkdir my-toolbox-agent && cd my-toolbox-agent
   azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml
   

2. Legen Sie den Toolboxnamen fest. Im Beispiel wird der Consumer-Endpunkt aus dem Projektendpunkt und diesem Namen zusammengesetzt:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Führen Sie den Agenten lokal aus:

   azd ai agent run
   

4. Überprüfen Sie in einem anderen Terminal, ob der Agent die Toolboxtools erkennt:

   azd ai agent invoke --local "List the tools you can use and briefly describe each one."
   

Die Antwort listet die Tools auf, die die Toolbox von MCP tools/listzurückgibt. Wenn die Antwort keine Tools der Toolbox enthält, siehe Problembehandlung für die Verbindung.

Verwenden von LangGraph

Verwenden Sie AzureAIProjectToolbox, wenn Ihr Hosted-Agent-Code mit LangGraph erstellt wurde. Die Integration lädt die Tools der Toolbox als LangChain-Tools und übernimmt die Authentifizierung für den Consumerendpunkt.

1. Installieren Sie die LangChain Azure Integration und deren Hostingabhängigkeiten:

   pip install "langchain-azure-ai[hosting]>=1.2.8"
   

2. Legen Sie FOUNDRY_PROJECT_ENDPOINT in der Umgebung des gehosteten Agents fest. Die Laufzeit liefert diesen Wert nach der Bereitstellung. Legen Sie es für lokale Entwicklung selbst fest.

3. Laden Sie die Tools nach Toolboxname:

import asyncio

from langchain_azure_ai.tools import AzureAIProjectToolbox

async def load_tools():
   toolbox = AzureAIProjectToolbox(toolbox_name="<toolbox-name>")
   tools = await toolbox.get_tools()
   print("\n".join(tool.name for tool in tools))

asyncio.run(load_tools())

Die Ausgabe enthält die Namen, die die Toolbox von MCP tools/list zurückgibt:

<tool-name>
<tool-name>

Referenz:AzureAIProjectToolbox

1. Übergeben Sie die geladenen Tools an Ihren LangGraph-Agent, und führen Sie eine Eingabeaufforderung aus, die eines der Toolboxtools erfordert. Eine vollständige Implementierung finden Sie im Beispiel der LangGraph-Toolbox.

Verwenden Sie die Agent Framework Foundry-Hostingintegration, um eine Toolbox anhand des Namens zu registrieren. AddFoundryToolboxes konstruiert den Consumer-Endpunkt aus FOUNDRY_PROJECT_ENDPOINT, ruft MCP tools/list beim Start auf und fügt die ermittelten Tools jeder Agentenanforderung hinzu.

Installieren Sie das .NET 10 SDK und Azure CLI, bevor Sie das verwaltete Beispiel ausführen.

1. Starten Sie aus dem Beispiel für die öffentliche gehostete Toolbox, oder fügen Sie das Foundry-Hostingpaket einem vorhandenen Agent Framework-Host hinzu.

2. Legen Sie diese Umgebungsvariablen für die lokale Entwicklung fest:

   AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
   AZURE_AI_MODEL_DEPLOYMENT_NAME=<model-deployment-name>
   TOOLBOX_NAME=<toolbox-name>
   

   Foundry stellt dem bereitgestellten Container FOUNDRY_PROJECT_ENDPOINT zur Verfügung. Behalten Sie den Toolboxnamen in TOOLBOX_NAME; andere FOUNDRY_* Variablennamen werden von der gehosteten Laufzeit reserviert.

3. Registrieren Sie in Program.cs den Agenten mit AddFoundryResponses und anschließend die Toolbox mit AddFoundryToolboxes(credential, toolboxName). Nachdem Sie die Webanwendung erstellt haben, rufen Sie MapFoundryResponses vor Run auf. Das öffentlich verfügbare Beispiel enthält die erforderlichen Importe, Pakete, die Agent-Konstruktion und die Konfiguration der Anmeldeinformationen.

4. Starten Sie den Host, und rufen Sie ihn dann mit einer Eingabeaufforderung auf, die ein Toolboxtool erfordert. Der /readiness Endpunkt gibt einen fehlerhaften Status zurück, wenn der Host die Toolboxtools nicht aufzählen kann.

Die Integrationen der Toolbox für gehostete Agents in diesem Artikel sind für Python und .NET verfügbar. Um den MCP-Endpunkt aus einer anderen Laufzeit aufzurufen, verwenden Sie einen MCP Streamable HTTP-Client, authentifizieren sich mit einem Token für https://ai.azure.com/.defaultund implementieren den Laufzeitvertrag für gehosteten Agent.

Die Integrationen der Toolbox für gehostete Agents in diesem Artikel sind für Python und .NET verfügbar. Um den MCP-Endpunkt aus einer anderen Laufzeit aufzurufen, verwenden Sie einen MCP Streamable HTTP-Client, authentifizieren sich mit einem Token für https://ai.azure.com/.defaultund implementieren den Laufzeitvertrag für gehosteten Agent.

Verwenden Sie das Microsoft Foundry Toolkit für Visual Studio Code, um ein Gerüst für ein Beispiel für gehostete Agent zu erstellen, das mit einer Toolbox verbunden ist.

Installieren Sie Visual Studio Code, die Microsoft Foundry Toolkit-Erweiterung und das Erweiterungspaket für Ihre Programmiersprache, bevor Sie das Gerüst für das Projekt erstellen.

1. Wählen Sie in der Aktivitätsleiste Foundry Toolkit aus.
2. Erweitern Sie unter My Resources zunächst Ihr Projekt und dann Tools.
3. Suchen Sie auf der Registerkarte Toolboxes die Toolbox, und wählen Sie dann Gerüstcodevorlage aus.
4. Wählen Sie in der Befehlspalette einen Projektordner aus.
5. Öffnen Sie das generierte README.mdElement, und führen Sie dann die lokalen Ausführungs- und Bereitstellungsschritte aus.
6. Führen Sie eine Eingabeaufforderung aus, die ein Toolboxtool erfordert, und bestätigen Sie, dass der Agent das erwartete Tool aufruft.

Übergeben Sie den Namen der Toolbox an ein Beispiel mit einem gehosteten Agent, das den Consumerendpunkt aus FOUNDRY_PROJECT_ENDPOINT erstellt:

Installieren Sie Azure Developer CLI (azd) 1.25 oder höher und die microsoft.foundry Erweiterung, bevor Sie diese Befehle ausführen.

1. Überprüfen Sie die Toolbox und die aktuelle Standardversion:

   azd ai toolbox show <toolbox-name> --output json
   

   Die Ausgabe verwendet die endpoint Eigenschaft. Der von diesem Befehl zurückgegebene Endpunkt identifiziert die ausgewählte Version und eignet sich zum Testen dieser Version.

2. Speichern Sie den Toolboxnamen in der azd Umgebung:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Um den gehosteten Agent lokal auszuführen, verwenden Sie Folgendes:

   azd ai agent run
   

   Um stattdessen den gehosteten Agent bereitzustellen, verwenden Sie Folgendes:

   azd deploy
   

Wenn Ihre Anwendung nur eine vollständige URL akzeptiert, legen Sie TOOLBOX_ENDPOINT auf den nicht versionierten Consumerendpunkt über Toolbox-Endpunkt auswählen fest.