Tools hinzufügen und verwalten

Das Tooling-Modul hilft Entwicklern dabei, Model Context Protocol (MCP)-Server in KI-Agenten-Workflows zu entdecken, zu konfigurieren und zu integrieren. 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.

Übersicht

Die Agent 365 Tooling-Integration folgt diesem 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 in Ihrem Projektordner mit Serverkonfigurationen.
3. Anwenden von Berechtigungen auf blueprint – Ein globaler Administrator gewährt OAuth2-Berechtigungen für den Agent-blueprint, indem er a365 setup all (erstmaliges Setup) oder a365 setup permissions mcp ausführt (sofern der blueprint bereits vorhanden ist). In jedem Fall liest der Befehl ToolingManifest.json und erfordert die Zustimmung des Administrators. Dieser Schritt ist immer von dem Hinzufügen von Servern zum Manifest getrennt.
4. Integrieren sie in Code – Laden Sie Manifeste, und registrieren Sie Tools bei Ihrem Orchestrator.
5. 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 Mandanten

Agentenidentitätskonfiguration

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. Dieser Prozess erstellt die agentische App-ID und den agentischen Benutzer, die es Ihrem Agenten ermöglichen, sich zu authentifizieren und auf MCP-Tools zuzugreifen.

OBO-Authentifizierungseinrichtung

Wenn Sie On-Behalf-Of (OBO)-Authentifizierung statt agentischer Authentifizierung verwenden, kann Ihr Agent auf MCP-Tools zugreifen, indem er delegierte Benutzerberechtigungen ohne agentische Benutzeridentität verwendet. Im OBO-Flow tauscht der Agent das delegierte Token eines Benutzers aus, um Aktionen im Namen des Benutzers auszuführen.

Weitere Informationen darüber, wie der OBO-Fluss funktioniert, finden Sie unter Authentifizierungsflüsse. Ein vollständiges Implementierungsbeispiel finden Sie im Microsoft 365 Agents SDK im OBO-Autorisierungsbeispiel.

Service Principal einrichten

Führen Sie dieses einmalige Setup-Skript aus, um den Service Principal für Agent 365 Tools in Ihrem Tenant zu erstellen.

1. Lade das New-Agent365ToolsServicePrincipalProdPublic.ps1 Skript herunter.

2. Öffne PowerShell als Administrator und gehe ins Skriptverzeichnis.

3. Führen Sie das Skript aus.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Melden Sie sich mit Ihren Azure Anmeldeinformationen an, wenn Sie dazu aufgefordert werden.

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

Liste alle MCP-Server auf, die du konfigurieren kannst:

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

Konfigurierte Server auflisten

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

Für die vollständige CLI-Referenz siehe a365 develop-Befehl.

Verwenden Sie zum Testen den Mock Tooling Server

Für Tests und Entwicklung verwenden Sie den Agent 365 CLI Mock Tooling Server anstelle der Verbindung mit echten MCP-Servern. Der Mock-Server simuliert MCP-Server-Interaktionen, sodass du deinen Agenten lokal testen kannst, ohne externe Abhängigkeiten wie Authentifizierung.

Der Mock-Server bietet folgende Vorteile für lokale Entwicklung und Testung:

• Offline-Entwicklung: Testen Sie Ihren Agent ohne Internetverbindung oder externe Abhängigkeiten.
• Konsistente Tests: Erhalten Sie vorhersehbare Antworten für Tests von Randfällen.
• Debugging: Alle Anfragen und Antworten in Echtzeit ansehen
• Schnelle Iteration: Kein Warten auf externe API-Aufrufe oder das Einrichten komplexer Testumgebungen.

Starte den Mock-Tooling-Server mit dem a365 develop start-mock-tooling-server Befehl.

Lerne, wie man den Mock-Tooling-Server einrichtet und konfiguriert.

Verstehen des Werkzeug-Manifests

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

Parameter des Manifests

Jeder MCP-Servereintrag enthält Folgendes:

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.

Toolserver auflisten (optional)

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

• Abfrage aller konfigurierten MCP-Server aus der ToolingManifest.json Datei.
• Abrufe Server-Metadaten und -Funktionen.
• Überprüfen Sie die 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)

// Use McpToolServerConfigurationService.listToolServers
const { McpToolServerConfigurationService } = require('@microsoft/agents-a365-tooling');

const configService = new McpToolServerConfigurationService();
const toolServers = await configService.listToolServers(agentUserId, authToken);

// Use IMcpToolServerConfigurationService.ListToolServersAsync
using Microsoft.Agents.A365.Tooling.Services;

var configService = serviceProvider.GetRequiredService<IMcpToolServerConfigurationService>();
var toolServers = await configService.ListToolServersAsync(agentInstanceId, authToken);

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:

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

Auswählen Ihrer Orchestrator-Erweiterung

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

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

Implementierungsbeispiele

Die folgenden Beispiele zeigen, wie man Agent 365 Tooling mit verschiedenen Orchestrierungs-Frameworks integriert.

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

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

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

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

import { McpToolServerConfigurationService } from '@microsoft/agents-a365-tooling';
import { McpToolRegistrationService } from '@microsoft/agents-a365-tooling-extensions-langchain';

const toolService = new McpToolRegistrationService();

// Get MCP Tools
try {
  const agent = await toolService.addToolServersToAgent(
    agent,
    process.env.AGENTIC_USER_ID || '',
    authorization,
    turnContext,
    process.env.MCP_AUTH_TOKEN || "",
  );
} catch (error) {
  console.error('Error adding MCP tool servers:', error);
}

using Microsoft.Agents.A365.Tooling;
using Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel;

builder.Services.AddSingleton<IMcpToolRegistrationService, McpToolRegistrationService>();
builder.Services.AddSingleton<IMcpToolServerConfigurationService, McpToolServerConfigurationService>();

private readonly IMcpToolRegistrationService _toolsService;

// Simplified call (authentication configured automatically)
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, turnContext);

// Or with explicit authentication parameters:
if (useAgenticAuth)
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);
}
else
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext, authToken);
}

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

Weitere Möglichkeiten, auf Agent 365 MCP-Server zuzugreifen

Zusätzlich zum Agent 365 SDK können Sie über andere Entwicklungserfahrungen auf Agent 365 MCP-Server zugreifen:

• Visual Studio Code – Stellen Sie eine direkte Verbindung mit MCP-Servern für benutzerdefinierte Entwicklungsworkflows her.
• Microsoft Copilot Studio – Integrieren Sie MCP-Server in Konversationsabläufe mithilfe einer Low-Code-Plattform.
• Azure AI Foundry – Verwenden Sie MCP-Server mit vollständiger SDK-Unterstützung und erweiterten Orchestrierungsfunktionen.

Für einen vollständigen Überblick über verfügbare MCP-Server und Integrationsoptionen über diese Plattformen hinweg siehe Agent 365 Tooling Server Übersicht.

Ihren Agent testen

Nachdem Sie MCP-Tools in Ihren Agenten integriert haben, testen Sie die Tool-Aufrufe, um sicherzustellen, dass sie korrekt funktionieren und verschiedene Szenarien bewältigen. Folgen Sie dem Testleitfaden, um Ihre Umgebung einzurichten. Konzentriere dich dann hauptsächlich auf den Abschnitt Testwerkzeug-Invocations, um zu bestätigen, dass deine MCP-Tools wie erwartet funktionieren. Schau dir auch den Mock-Tooling-Server an, um die MCP-Serververbindung und Tool-Aufrufe ohne Authentifizierung zu testen.

Observierbarkeit hinzufügen

Fügen Sie Ihrem Agenten Observability hinzu, um die MCP-Tool-Aufrufe Ihres Agenten zu überwachen und nachzuverfolgen. Durch das Hinzufügen von Observabilitätsfunktionen können Sie die Leistung verfolgen, Probleme debuggen und Werkzeugnutzungsmuster verstehen. Erfahren Sie mehr über die Implementierung von Nachverfolgung und Überwachung.

Problembehandlung

Dieser Abschnitt listet häufige Probleme auf, wenn Sie MCP-Server und -Tools konfigurieren und verwenden.

MCP-Server- und Werkzeugprobleme

Symptome:

• Fehler beim Aufruf von Werkzeugen.
• "MCP-Server nicht gefunden"-Fehler.
• Fehler aufgrund verweigerter Berechtigungen beim Aufruf von Tools.

Grundursache:

• Der MCP-Server ist nicht konfiguriert.
• Fehlende Berechtigungen.
• Service Principal ist nicht konfiguriert.
• Verwirrung zwischen Mock- und Production-Servern.

Lösungen: Probieren Sie die folgenden Lösungen aus, um das Problem anzugehen.

• Überprüfen Sie, ob die MCP-Server konfiguriert sind

  Liste konfigurierte Server auf und füge alle fehlenden hinzu.

  # List configured servers
  a365 develop list-configured
  
  # If empty, add required servers (example: Mail MCP server)
  a365 develop add-mcp-servers mcp_MailTools
  

• Überprüfen, ob der Service Principal existiert

  Stellen Sie sicher, dass der erforderliche Service-Principal für die Werkzeuge erstellt wird.

  # Run the one-time setup script
  # https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
  

• Für die frühe Entwicklung und das Testen verwenden Sie Mock-Server

  Nutze den Mock-Tooling-Server für frühe lokale Entwicklung und Testung, wenn du den Rest deines Agenten ohne Produktionswerkzeugkomponenten testen möchtest.

  # Start mock tooling server
  a365 develop start-mock-tooling-server
  
  # Update your .env
  MCP_PLATFORM_ENDPOINT=http://localhost:5309
  

  Erfahren Sie mehr über den Mock-Tooling-Server.

• Berechtigungen im Verwaltungszentrum überprüfen

  Bestätigen Sie, dass Ihr Agent die erforderlichen MCP-Berechtigungen hat.

  • Überprüfen Sie, ob Ihre Agent-Blueprint-API-Berechtigungen im Azure Portal alle MCP-Serverberechtigungen anzeigen.

  Überprüfung:

  # Test a tool call in Agents Playground
  # Should execute without permission errors