Arten von Tools im Foundry Agent Service

Tools erweitern, was Ihre Agents in Microsoft Foundry Agent Service tun können. Während ein Agent ein Foundry-Modell zum Generieren von Antworten verwenden kann, können Tools Aktionen wie das Durchsuchen des Webs, das Ausführen von Code, den Zugriff auf Unternehmensdaten und das Aufrufen externer Dienste oder APIs ausführen. In diesem Artikel werden die verfügbaren Tooltypen vorgestellt, erläutert, wie Sie Tools mit Agents verbinden und Authentifizierungs- und Autorisierungsüberlegungen beschreiben.

Die empfohlene Methode zum Verfügbarmachen von Tools für Agents erfolgt über eine Toolbox. Mit einer Toolbox werden Tools über einen verwalteten MCP-Endpunkt verfügbar gemacht, Anmeldeinformationen und Richtlinienverwaltung zentralisiert, und Sie können Tools aktualisieren oder versionieren, ohne den Agentcode zu ändern. Obwohl Tools auch direkt an einzelne Agents angefügt werden können, vereinfacht eine Toolbox die Verwaltung und fördert die Wiederverwendung von Tools über Agents hinweg. Um Tools zu verwenden, müssen Sie über Berechtigungen in Ihrem Foundry-Projekt verfügen, um Tools zu verwalten und auf den Foundry-Toolkatalog zuzugreifen. Weitere Informationen finden Sie unter Was ist eine Toolbox? Und erstellen und verwalten Sie eine Toolbox in Foundry.

Der Gießereitoolskatalog und Toolboxen sind allgemein verfügbar. Einige einzelne Tools befinden sich in der Vorschau und werden in den Toolauflistungen und toolspezifischen Dokumentationen identifiziert. Vorschautools unterliegen ergänzenden Nutzungsbedingungen.

Was sind Tools?

Ein Tool ist eine Funktion, die ein Agent während einer Unterhaltung aufrufen kann, um eine bestimmte Aufgabe auszuführen. Wenn ein Agent eine Benutzernachricht empfängt, entscheidet das Gießereimodell, das den Agent aktiviert, ob ein Tool basierend auf den Anweisungen des Agents und den verfügbaren Tooldefinitionen aufgerufen werden soll. Der Agent sendet die Toolanfrage, Ihre Anwendung oder der Dienst führt sie aus, und das Ergebnis fließt zurück in die Unterhaltung, damit der Agent mit genauen, aktuellen Informationen fortfahren kann.

Mit Tools können Agents über die Textgenerierung hinausgehen. Beispielsweise kann ein Agent:

• Durchsuchen Sie das Web nach aktuellen Informationen, bevor Sie antworten.
• Führen Sie Python Code aus, um ein Dataset zu analysieren und ein Diagramm zu generieren.
• Greifen Sie auf den Vektorspeicher Ihrer Dokumente zu, um die Antwort in Ihren Daten zu verankern.
• Rufen Sie eine externe API auf, um einen Kundendatensatz nachzuschlagen oder ein Supportticket zu erstellen.

Arten von Tools

Foundry Agent Service gruppiert Tools in zwei Kategorien: integrierte Tools, die nach der grundlegenden Konfiguration verwendet werden können, und benutzerdefinierte Tools, mit denen Sie Ihre eigenen Funktionen nutzen können. Je nachdem, zu welcher Kategorie ein Tool gehört, besteht die empfohlene Möglichkeit, es einem Agent zur Verfügung zu stellen, über eine Toolbox.

Integrierte Tools

Der Foundry Agent Service bietet integrierte Tools als vorkonfigurierte Funktionen. Sie aktivieren diese Tools für Ihren Agent, und der Dienst verarbeitet die Ausführung. Für diese Tools ist kein externes Hosting oder benutzerdefinierter Code erforderlich.

Zu den am häufigsten verwendeten integrierten Tools gehören:

• Websuche – Hinzufügen der Websuche zu Ihrem Agent. Der Agent ruft Echtzeitinformationen aus dem öffentlichen Web ab und gibt Antworten mit Inlinezitationen zurück. Diese Methode ist die empfohlene Methode zum Hinzufügen von Web-Grounding. Erweiterte Szenarien wie marktbezogene Filterung finden Sie unter Grundlagen mit Bing-Tools und der Übersicht über die Web-Grundlagen.
• Code Interpreter – Lassen Sie Agents Python Code in einer Sandkastenumgebung für Datenanalyse, Mathematik und Diagrammgenerierung schreiben und ausführen.
• Dateisuche – Erweitern Sie Agents mit Wissen aus hochgeladenen Dateien oder proprietären Dokumenten mithilfe der Vektorsuche.
• Funktionsaufrufe – Definieren sie benutzerdefinierte Funktionen, die der Agent aufrufen kann. Die Anwendung führt die Funktion aus und gibt das Ergebnis zurück.

Die vollständige Liste der integrierten Tools finden Sie unter "Alle integrierten Tools".

Benutzerdefinierte Tools

Mit benutzerdefinierten Tools können Sie Ihren Agent mit Ihren eigenen APIs, Diensten oder anderen Agents erweitern. Verwenden Sie benutzerdefinierte Tools, wenn integrierte Tools Ihr Szenario nicht abdecken.

Zu den gängigsten optionen für benutzerdefinierte Tools gehören:

• Model Context Protocol (MCP) – Verbinden Sie Ihren Agent mit Tools, die auf einem MCP-Serverendpunkt gehostet werden. Dies ist am besten für Tools, die für mehrere Agents freigegeben oder von einem anderen Team verwaltet werden.
• Agent-to-Agent (A2A) (Vorschau) – Verbinden Sie Ihren Agent mit anderen Agents über A2A-kompatible Endpunkte für die agentübergreifende Kommunikation.
• OpenAPI-Tool – Verbinden Sie Ihren Agent mit externen HTTP-APIs mithilfe einer OpenAPI 3.0- oder 3.1-Spezifikation.

Die vollständige Liste der benutzerdefinierten Tooloptionen finden Sie unter "Alle benutzerdefinierten Tools".

Verwenden eines Tools in einem Agent

Um einem Agent ein Tool hinzuzufügen, platzieren Sie das Tool in einer Toolbox , und fügen Sie die Toolbox als MCP-Tool an den Agent an. Im folgenden Beispiel wird eine Toolbox mit dem Websuchtool erstellt, die Toolbox an einen Agent angefügt und eine Abfrage gesendet:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool, MCPTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# 1. Add the tool to a toolbox. Using a toolbox is the recommended way to give
#    agents tools: you curate tools once and reuse the toolbox across agents.
toolbox = project.toolboxes.create_toolbox_version(
    name="web-search-toolbox",
    description="Toolbox with the web search tool",
    tools=[WebSearchTool()],
)

# 2. The toolbox exposes an MCP-compatible endpoint.
TOOLBOX_MCP_URL = (
    f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
    f"/versions/{toolbox.version}/mcp?api-version=v1"
)

# 3. Create a remote-tool project connection that points at the toolbox endpoint.
#    Call a user Entra token so the caller's identity is passed through.
#    Create the connection once with the Azure Developer CLI:
#    
#    azd ai connection create web-search-toolbox-conn \
#      --kind remote-tool \
#      --target "<TOOLBOX_MCP_URL>" \
#      --auth-type user-entra-token \
#      --audience https://ai.azure.com
TOOLBOX_CONNECTION_NAME = "web-search-toolbox-conn"

# 4. Attach the toolbox to the agent as an MCP tool.
agent = project.agents.create_version(
    agent_name="web-search-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[
            MCPTool(
                server_label="toolbox",
                server_url=TOOLBOX_MCP_URL,
                require_approval="never",
                project_connection_id=TOOLBOX_CONNECTION_NAME,
            )
        ],
    ),
)

# Send a query
response = openai.responses.create(
    input="What are the latest updates to Microsoft Foundry?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

Jeder Tooltyp verfügt über eine eigene Konfiguration. Ausführliche Setup- und Codebeispiele in allen unterstützten Sprachen finden Sie in den einzelnen Anleitungen zu Tools, die in den Abschnitten "Tools" verknüpft sind.

Das Verhalten von Tools zur Laufzeit mit strukturierten Eingaben anpassen

Standardmäßig sind Toolkonfigurationen wie Datei-IDs, Vektorspeicher-IDs und MCP-Serverendpunkte beim Erstellen des Agenten festgelegt. Strukturierte Eingaben in Tooleigenschaften ermöglichen es Ihnen, diese Werte zur Laufzeit außer Kraft zu setzen, ohne eine neue Agentversion zu erstellen.

Strukturierte Eingaben sind nützlich, wenn:

• Verschiedene Benutzer benötigen Vektorspeicher oder Dateien basierend auf ihrem Kontext.
• Sie möchten dieselbe Agentdefinition in umgebungenübergreifend wiederverwenden (Entwicklung, Staging, Produktion).
• MCP-Serverendpunkte oder Authentifizierungstoken variieren je nach Anforderung.

Die folgenden Tooleigenschaften unterstützen anpassungen über strukturierte Eingaben:

Beispielsweise eine Agentdefinition mit einem vorlagenbasierten Vektorspeicher:

{
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["vs_base_kb", "{{customer_kb}}"]
    }
  ],
  "structured_inputs": {
    "customer_kb": {
      "description": "Vector store ID for the customer's knowledge base",
      "required": true,
      "schema": { "type": "string" }
    }
  }
}

Geben Sie zur Laufzeit den tatsächlichen Wert an:

{
  "agent": { "type": "agent_reference", "name": "support-agent", "version": "1" },
  "input": [{ "type": "text", "text": "How do I upgrade my account?" }],
  "structured_inputs": {
    "customer_kb": "vs_premium_kb_2024"
  }
}

Verwalten der Authentifizierung für Tools

Verschiedene Tools erfordern unterschiedliche Authentifizierungsansätze. Wenn Sie diese Optionen verstehen, können Sie Tools sicher verbinden.

Integrierte Tools

Die meisten integrierten Tools, z. B. Codedolmetscher und Dateisuche, authentifizieren sich automatisch über den Foundry Agent Service und erfordern keine zusätzliche Konfiguration. Tools, die eine Verbindung mit externen Datenquellen herstellen, wie Azure KI-Suche oder SharePoint, verwenden die connections, die Sie in Ihrem Foundry-Projekt konfigurieren.

MCP-Server

MCP-Server unterstützen je nach Server mehrere Authentifizierungsmethoden: schlüsselbasierte Authentifizierung (API-Schlüssel oder Token), Microsoft Entra Authentifizierung (verwaltete Identität) und OAuth für die Passthrough auf Benutzerebene.

Im folgenden Beispiel wird mithilfe der schlüsselbasierten Authentifizierung eine Verbindung mit einem MCP-Server hergestellt. Speichern Sie die Anmeldeinformationen in einer Projektverbindung, und verweisen Sie dann beim Erstellen des Tools auf den Verbindungsnamen:

from azure.ai.projects.models import MCPTool

tool = MCPTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id="my-github-connection",
)

Verwenden Sie für Microsoft Entra Authentifizierung die Agentidentität oder die vom Projekt verwaltete Identität anstelle einer Verbindung. Der Dienst fordert automatisch ein Token an. Für OAuth-Identity-Passthrough (Benutzerauthentifizierung) erzeugt der Agent Service einen Zustimmungslink, den Benutzer beim ersten Gebrauch autorisieren.

Ausführliche Einrichtungsschritte für alle Methoden finden Sie unter Einrichten der MCP-Serverauthentifizierung.

OpenAPI Tools

OpenAPI-Tools unterstützen anonyme, API-Schlüssel und verwaltete Identitätsauthentifizierung. Die Authentifizierungskonfiguration ist Teil der Tooldefinition.

Anonyme Authentifizierung – Verwendung, wenn die API keine Anmeldeinformationen erfordert:

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_spec,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

API-Schlüsselauthentifizierung – Speichern Sie den Schlüssel in einer Projektverbindung, und verweisen Sie darauf. Ihre OpenAPI-Spezifikation muss Abschnitte enthalten securitySchemes und security :

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiKeyAuthDetails,
)

api_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_orders",
        spec=openapi_spec,
        description="Look up customer orders.",
        auth=OpenApiKeyAuthDetails(
            project_connection_id="my-api-connection"
        ),
    )
)

Informationen zur Konfiguration der verwalteten Identität finden Sie unter Verbinden von Agents mit OpenAPI-Tools.

Alle integrierten Tools

In der folgenden Tabelle sind alle integrierten Tools aufgeführt, die im Foundry Agent Service verfügbar sind.

Alle benutzerdefinierten Tools

In der folgenden Tabelle sind alle benutzerdefinierten Tooloptionen zum Verbinden Ihrer eigenen Funktionen mit einem Agent aufgeführt.

Schlüsselkonzepte

Verwenden Sie diese Definitionen, um die Terminologie konsistent zu halten:

Überlegungen zur Verwendung von nicht-Microsoft-Diensten und -Servern

Ihre Nutzung verknüpfter nicht-Microsoft-Dienste und -Server ("nicht-Microsoft-Dienste") unterliegt den Bestimmungen zwischen Ihnen und dem Dienstanbieter. Nicht-Microsoft-Dienste sind nicht Microsoft Produkte gemäß Ihrer Vereinbarung über die Verwendung von Microsoft Onlinedienste. Wenn Sie eine Verbindung mit nicht Microsoft-Dienste herstellen, werden einige Ihrer Daten (z. B. Eingabeaufforderungsinhalte) an den Dienst ohne Microsoft gesendet, oder Ihre Anwendung empfängt möglicherweise Daten vom Dienst ohne Microsoft. Sie sind für die Verwendung von nicht Microsoft-Dienste und Daten sowie für alle Gebühren verantwortlich, die dieser Nutzung zugeordnet sind.

Dritte (nicht Microsoft) erstellen die nicht-Microsoft-Dienste, einschließlich Remote-MCP-Servern, mit denen Sie eine Verbindung herstellen möchten. Microsoft testet oder überprüft diese Server nicht. Microsoft hat keine Verantwortung für Sie oder andere Personen in Bezug auf Ihre Nutzung jeglicher nicht Microsoft-Dienste.

Überprüfen und nachverfolgen Sie die MCP-Server, die Sie dem Foundry Agent Service hinzufügen. Verlassen Sie sich auf Server, die von vertrauenswürdigen Dienstanbietern selbst und nicht von Proxys gehostet werden.

Das MCP-Tool kann benutzerdefinierte Header übergeben, die von einem Remote-MCP-Server möglicherweise für die Authentifizierung erforderlich sind. Behandeln Sie Zugangsdaten als vertrauliche Informationen.

• Stellen Sie nur die mindestens erforderlichen Kopfzeilen bereit.
• Geben Sie keine Anmeldeinformationen in Eingabeaufforderungen ein.
• Wenn Sie Anforderungen für Prüfungen protokollieren, vermeiden Sie das Protokollieren von Geheimnissen oder sensiblen Eingabeinhalten.
• Überprüfen Sie die Verfahren zur Datenverarbeitung des Anbieters, einschließlich Aufbewahrung und Datenspeicherort.

Entdecken und Verwalten von Tools im Portal

Wechseln Sie im Foundry-Portal zu Ihrem Projekt, und wählen Sie "Buildtools>" aus, um foundry Tools zu öffnen. Von dort aus können Sie den Toolkatalog durchsuchen, Tools konfigurieren und zu Agents hinzufügen. Wenn Sie Tools benötigen, die nur in Ihrer Organisation sichtbar sind, erstellen Sie einen privaten Toolkatalog.

Verwenden Sie den Agents Playground, um Werkzeuge während des Bauens zu erkunden. Weitere Informationen finden Sie unter Microsoft Foundry Playgrounds.

Tooltypen im Katalog

Der Toolkatalog enthält drei Arten von Einträgen:

Remote-MCP-Server: Der Herausgeber hostt den Server und stellt einen statischen oder dynamischen Endpunkt bereit. Befolgen Sie die Konfigurationsanleitungen, um die erforderlichen Einstellungen bereitzustellen, z. B. einen Endpunkt und Authentifizierungsdetails.

Lokaler MCP-Server: Sie hosten den Server selbst und stellen dann eine Verbindung mit Foundry her, indem Sie seinen Endpunkt angeben. Informationen zum Erstellen und Registrieren Ihres eigenen Servers finden Sie unter Erstellen und Registrieren eines MCP-Servers. Informationen zum Verbinden eines MCP-Endpunkts mit einem Agent finden Sie unter Herstellen einer Verbindung mit MCP-Servern.

Custom: MCP-Server, die aus Azure Logic App Connectors konvertiert wurden. Für diese Server ist eine zusätzliche Konfiguration erforderlich, um in Remote-MCP-Server zu konvertieren.

Filtern und Suchen

Foundry Tools bietet die folgenden Filter, die Ihnen helfen, die richtigen Tools zu finden:

Wenn Sie ein Tool auswählen, zeigt Foundry Tools die Einrichtungsdetails an, die Sie für die Konfiguration benötigen.

Verwalten von konfigurierten Tools

In Ihrer Toolsliste finden Sie die von Ihnen konfigurierten Tools sowie Details wie Endpunkte und Authentifizierungseinstellungen. Sie können Agenten auch Werkzeuge hinzufügen.

Bevor Sie ein Tool löschen, überprüfen Sie, welche Agents es verwenden. Das Löschen eines Tools kann die Ausführung unterbrechen, die davon abhängig ist.

Verfügbarkeit und Einschränkungen

Die Verfügbarkeit des Tools variiert je nach Modell und Region.

Die neuesten Supportdetails für Modell und Region finden Sie in den bewährten Methoden für die Verwendung von Tools im Foundry Agent Service.

Problembehandlung

Verwenden Sie diese Prüfungen, um häufige Probleme zu beheben:

• Sie können den Toolkatalog nicht finden: Bestätigen Sie, dass Sie sich im richtigen Projekt befinden, und wechseln Sie dann zu "Buildtools>".
• Ein Tool ist sichtbar, Sie können es jedoch nicht konfigurieren: Überprüfen Sie die erforderlichen Authentifizierungs- und Konfigurationseingaben des Tools, und überprüfen Sie, ob Sie Zugriff auf abhängige Dienste haben.
• Ihr Agent ruft kein Tool auf: Verwenden Sie die Validierungsleitfaden in bewährten Methoden für die Verwendung von Tools im Foundry Agent Service.

Verwandte Inhalte

• Bewährte Methoden für den Foundry Agent Service
• Erstellen und Verwenden einer Foundry Toolbox
• Einrichten der MCP-Serverauthentifizierung
• Steuern von MCP-Tools mithilfe eines KI-Gateways
• Erstellen eines privaten Toolkatalogs
• Erstellen und Registrieren eines MCP-Servers
• Bewährte Methoden und Sicherheitsanleitungen für Foundry MCP Server