Freigeben über

Tools hinzufügen und verwalten

Wichtig

Sie müssen Teil des Frontier-Vorschauversionsprogramms sein, um Vorabzugriff auf Microsoft Agent 365 zu erhalten. Frontier verbindet Sie direkt mit den neuesten KI-Innovationen von Microsoft. Frontier-Vorschauversionen unterliegen den bestehenden Vorschauversionsbedingungen Ihrer Kundenvereinbarungen. Da sich diese Funktionen noch in der Entwicklung befinden, können sich ihre Verfügbarkeit und Merkmale im Laufe der Zeit ändern.

Das Tooling-Modul ermöglicht Entwicklern das Ermitteln, Konfigurieren und Integrieren von MCP-Servern (Model Context Protocol) in AI-Agent-Workflows. MCP-Server machen externe Funktionen als Tools verfügbar, die KI-Agents aufrufen können. Eine Übersicht über verfügbare Toolingserver finden Sie unter Agent 365 Tooling-Servers.

Veranschaulicht den Anforderungs- und Antwortfluss

Übersicht

Die Agent 365 Tooling-Integration folgt einem vierstufigen Workflow:

  1. Konfigurieren von MCP-Servern – Verwenden der Agent 365 CLI zum Ermitteln und Hinzufügen von MCP-Servern
  2. Manifest generieren – CLI erstellt ToolingManifest.json mit Serverkonfigurationen
  3. Integrieren in Code – Laden des Manifests und Registrieren von Tools bei Ihrem Orchestrator
  4. Aufrufen von Tools – Agent ruft Tools während der Ausführung auf, um Vorgänge auszuführen

Voraussetzungen

Stellen Sie vor der Konfiguration von MCP-Servern sicher, dass Sie über Folgendes verfügen:

  • Agent 365 CLI installiert und konfiguriert
  • .NET 8.0 SDK oder höher – Download
  • Globale Administratorrechte in Ihrem Microsoft 365-Mandant

Agent-Identitätseinrichtung

Wenn Sie die agentische Authentifizierung verwenden, führen Sie den Agent-Registrierungsprozess aus, um Ihre Agent-Identität zu erstellen, bevor Sie MCP-Server konfigurieren. Dadurch werden die agentische App-ID und der agentische Benutzer erstellt, mit dem Ihr Agent MCP-Tools authentifizieren und darauf zugreifen kann.

Dienstprinzipal einrichten

Führen Sie dieses EINMALIGE Setupskript aus, um den Dienstprinzipal für Agent 365-Tools in Ihrem Mandanten zu erstellen.

Wichtig

Dies ist ein EINMALIGEr Vorgang pro Mandant, der globale Administratorrechte erfordert.

  1. Herunterladen des Skripts New-Agent365ToolsServicePrincipalProdPublic.ps1

  2. Öffnen Sie PowerShell als Admin und navigieren Sie zum Skriptverzeichnis

  3. Ausführen des Skripts:

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Wenn Sie dazu aufgefordert werden, melden Sie sich mit Ihren Azure-Anmeldeinformationen an

Nach Abschluss ist Ihr Mandant bereit für die Agent-Entwicklung und MCP-Serverkonfiguration.

MCP-Server konfigurieren

Verwenden Sie die Agent 365 CLI, um MCP-Server für Ihren Agent zu ermitteln, hinzuzufügen und zu verwalten. Eine vollständige Liste der verfügbaren MCP-Server und deren Funktionen finden Sie im MCP-Serverkatalog.

Entdecken Sie verfügbare Server

Auflisten aller MCP-Server, die konfiguriert werden können:

a365 develop list-available

MCP-Server hinzufügen

Einen oder mehrere MCP-Server zur Konfiguration Ihres Agents hinzufügen:

a365 develop add-mcp-servers mcp_MailTools

Auflisten konfigurierter Server

Aktuell konfigurierte MCP-Server anzeigen:

a365 develop list-configured

MCP-Server entfernen

Entfernen Sie einen MCP-Server aus Ihrer Konfiguration:

a365 develop remove-mcp-servers mcp_MailTools

Eine vollständige CLI-Referenz finden Sie unter a365 develop command.

Grundlegendes zum Toolmanifest

Wenn Sie a365 develop add-mcp-servers ausführen, generiert die CLI eine ToolingManifest.json Datei, die eine Konfiguration für alle MCP-Server enthält. Die Agent-Laufzeit verwendet dieses Manifest, um zu verstehen, welche Server verfügbar sind und wie Sie sich bei ihnen authentifizieren können.

Manifeststruktur

Beispiel:ToolingManifest.json

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Manifestparameter

Jeder MCP-Servereintrag enthält Folgendes:

Parameter Beschreibungen
mcpServerName Den Anzeigenamen des MCP-Servers
mcpServerUniqueName Den eindeutigen Bezeichner für die MCP-Serverinstanz
Bereich Der OAuth-Bereich, der für den Zugriff auf die Funktionen des MCP-Servers erforderlich ist (z. B. McpServers.Mail.All für E-Mail-Vorgänge). Dieser Wert wird aus dem MCP-Serverkatalog abgerufen, wenn Sie den add-mcp-servers Befehl ausführen.
Zielgruppe Der Microsoft Entra ID-URI, der die Ziel-API-Ressource identifiziert. Dieser Wert wird auch aus dem MCP-Serverkatalog abgerufen.

Anmerkung

Die Werte scope und audience werden automatisch von der Agent 365 CLI aufgefüllt, wenn Sie einen MCP-Server hinzufügen. Diese Werte stammen aus dem MCP-Serverkatalog und definieren die Berechtigungen, die für den Zugriff auf jeden MCP-Server erforderlich sind.

Tools in Ihren Agent integrieren

Integrieren Sie nach dem Generieren des Toolmanifests die konfigurierten MCP-Server in Ihren Agent-Code. In diesem Abschnitt werden der optionale Inspektionsschritt und die erforderlichen Integrationsschritte behandelt.

Listentoolserver (optional)

Trinkgeld

Dieser Schritt ist optional. Verwenden Sie den Toolserver-Konfigurationsdienst, um die verfügbaren Toolserver aus dem Toolmanifest zu prüfen, bevor Sie sie Ihrem Orchestrator hinzufügen.

Verwenden Sie den Toolserverkonfigurationsdienst, um zu ermitteln, welche Toolserver ihrem Agent über das Toolmanifest zur Verfügung stehen. Diese Methode ermöglicht Ihnen Folgendes:

  • Abfragen aller konfigurierten MCP-Server von der ToolingManifest.json
  • Abrufen von Servermetadaten und -funktionen
  • Überprüfen der Serververfügbarkeit vor der Registrierung

Die Methode zum Auflisten von Toolservern ist in den Kerntoolpaketen verfügbar:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

Parameter:

Parameter Typ Beschreibung Erwarteter Wert erforderlich/optional
agentic_app_id str Der eindeutige Bezeichner für die Agent-Anwendungsinstanz Gültige Agent-Anwendungs-ID-Zeichenfolge Erforderlich
auth_token str Bearertoken für die Authentifizierung mit dem MCP-Server-Gateway Gültiges OAuth-Bearertoken Erforderlich

Paket: @microsoft-agents-a365-tooling

Registrieren von Tools bei Ihrem Orchestrator

Verwenden Sie die framework-spezifische Erweiterungsmethode, um alle MCP-Server mit Ihrem Orchestrierungs-Framework zu registrieren:

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

Diese Methoden führen Folgendes aus:

  • Registrieren aller Tools von konfigurierten MCP-Servern bei Ihrem Orchestrator
  • Automatisches Einrichten von Authentifizierungs- und Verbindungsdetails
  • Tools sofort verfügbar machen, damit Ihr Agent aufgerufen werden kann

Auswählen Ihrer Orchestrator-Erweiterung

Das Agent 365 Tooling-Modul bietet dedizierte Erweiterungspakete für verschiedene Orchestrierungs-Frameworks:

  • microsoft-agents-a365-tooling: Kernfunktionen
  • microsoft-agents-a365-tooling-extensions-agentframework: Agent Framework-Integration
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Azure AI Foundry-Integration
  • microsoft-agents-a365-tooling-extensions-openai: OpenAI-Integration
  • microsoft-agents-a365-tooling-extensions-semantickernel: Semantischer Kernel-Integration

Anmerkung

Die Authentifizierung wird automatisch von der Agent 365 CLI konfiguriert, wenn Sie a365 develop add-mcp-servers ausführen. Die OAuth-Bereiche und Zielgruppenwerte werden aus dem MCP-Serverkatalog abgerufen und in der ToolingManifest.json aufgenommen. Die Erweiterungsmethoden verwenden diese Werte automatisch zum Einrichten der Authentifizierung – es ist keine manuelle Konfiguration erforderlich.

Ausführliche Implementierungsbeispiele finden Sie in den Agent 365-Beispielen.

Implementierungsbeispiele

Die folgenden Beispiele veranschaulichen die Integration von Agent 365-Tools in verschiedene Orchestrierungs-Frameworks.

Python mit OpenAI

In diesem Beispiel wird gezeigt, wie MCP-Tools in OpenAI in eine Python-Anwendung integriert werden.

1. Eine Importanweisung hinzufügen

Fügen Sie die erforderlichen Importe hinzu, um auf das Tooling-Modul und die OpenAI-Erweiterungen zuzugreifen:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. Initialisieren von Tooldiensten

Erstellen von Instanzen der Konfigurations- und Toolregistrierungsdienste:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. Registrieren von MCP-Tools bei OpenAI-Agent

Verwenden Sie die add_tool_servers_to_agent Methode, um alle konfigurierten MCP-Tools bei Ihrem OpenAI-Agent zu registrieren. Diese Methode behandelt sowohl agentische als auch nicht-agentische Authentifizierungsszenarien:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

Methodenparameter

In der folgenden Tabelle werden die mit add_tool_servers_to_agent zu verwendenden Parameter beschrieben.

Parameter Beschreibungen
agent Die OpenAI-Agent-Instanz zum Registrieren von Tools.
agentic_app_id Der eindeutige Bezeichner für den Agent (agentische App-ID).
auth Der Autorisierungskontext für den Benutzer.
context Der aktuelle Unterhaltungskontext aus dem Agents SDK. Stellt Benutzeridentität, Unterhaltungsmetadaten und Authentifizierungskontext für die sichere Toolregistrierung bereit.
auth_token (Optional) Bearertoken für nicht-agentische Authentifizierungsszenarien.

4. Aufruf während der Initialisierung

Stellen Sie sicher, dass Sie die Einrichtungsmethode während der Initialisierung aufrufen, bevor Sie den Agent ausführen:

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

Die add_tool_servers_to_agent Methode führt folgendes automatisch aus:

  • Lädt alle MCP-Server aus dem ToolingManifest.json
  • Registriert seine Tools beim OpenAI-Agent
  • Richtet die Authentifizierung basierend auf der Manifestkonfiguration ein
  • Stellt die Tools für den Aufruf ihres Agents zur Verfügung

Vollständige Arbeitsbeispiele finden Sie im Repository für Agent 365-Beispiele.

Testen und überwachen

Ihren Agent testen

Testen Sie nach der Integration von MCP-Tools in Ihren Agent die Toolaufrufe, um sicherzustellen, dass sie ordnungsgemäß funktionieren und verschiedene Szenarien verarbeiten. Folgen Sie dem Testhandbuch, um Ihre Umgebung einzurichten, und konzentrieren Sie sich in erster Linie auf den Abschnitt Testtoolaufrufe, um zu überprüfen, ob Ihre MCP-Tools wie erwartet funktionieren.

Einblick hinzufügen

Fügen Sie Ihrem Agent Einblick hinzu, um die MCP-Toolaufrufe Ihres Agents zu überwachen und nachzuverfolgen; fügen Sie die Einblick-Funktionen zum Nachverfolgen der Leistung, zum Debuggen von Problemen und zum Verständnis von Toolnutzungsmustern hinzu. Weitere Informationen zur Implementierung von Ablaufverfolgung und Überwachung

  • Last updated on