Hulpmiddelen toevoegen en beheren

Met de module Hulpprogramma's kunnen ontwikkelaars MCP-servers (Model Context Protocol) detecteren, configureren en integreren in AI-agentwerkstromen. MCP-servers maken externe mogelijkheden beschikbaar als hulpprogramma's die AI-agents kunnen aanroepen. Zie Agent 365-hulpprogrammaservers voor een overzicht van de beschikbare hulpprogrammaservers.

Overzicht

De integratie van Agent 365-hulpprogramma's volgt deze werkstroom:

1. MCP-servers configureren - Agent 365 CLI gebruiken om MCP-servers te detecteren en toe te voegen
2. Manifest genereren:: CLI maakt ToolingManifest.json in uw projectmap met serverconfiguraties.
3. Machtigingen toepassen op blauwdruk: een globale beheerder verleent OAuth2-machtigingen aan de agentblauwdruk door a365 setup all uit te voeren (bij eerste installatie) of a365 setup permissions mcp (als de blauwdruk al bestaat). Hoe dan ook, de opdracht leest ToolingManifest.json en vereist toestemming van de beheerder. Deze stap staat altijd los van het toevoegen van servers aan het manifest.
4. Integreren in code: manifest laden en hulpprogramma's registreren bij uw orchestrator.
5. Hulpprogramma's aanroepen: agent roept hulpprogramma's aan tijdens de uitvoering om bewerkingen uit te voeren.

Vereisten

Voordat u MCP-servers configureert, moet u ervoor zorgen dat u het volgende hebt:

• Agent 365 CLI geïnstalleerd en geconfigureerd
• .NET 8.0 SDK of hoger - Downloaden
• Globale beheerdersbevoegdheden in uw Microsoft 365-tenant

Agentidentiteit instellen

Als u agentische verificatie gebruikt, voltooit u het registratieproces van de agent om uw agent-id te maken voordat u MCP-servers configureert. Dit proces maakt de Entra-agent-id en agentgebruiker, waarmee uw agent MCP-hulpprogramma's kan verifiëren en openen.

OBO-verificatie-instelling

Als u On-Behalf-Of (OBO)-verificatie gebruikt in plaats van agentische verificatie, kan uw agent toegang krijgen tot MCP-tools door gedelegeerde gebruikersrechten te gebruiken zonder agentgebruikersidentiteit. In de OBO-stroom ruilt de agent het gedelegeerde token van een gebruiker in om acties uit te voeren namens de gebruiker.

Zie voor meer informatie over hoe de OBO-stroom werkt Verificatiestromen. Zie voor een volledig implementatievoorbeeld het OBO-autorisatievoorbeeld in de SDK voor Microsoft 365-agenten.

Service-principal instellen

Voer dit eenmalige installatiescript uit om de service-principal voor Agent 365 Tools in uw tenant te maken.

1. Download het script New-Agent365ToolsServicePrincipalProdPublic.ps1.

2. Open PowerShell als beheerder en ga naar de scriptmap.

3. Voer het script uit.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Meld u desgevraagd aan met uw Azure-referenties.

Na voltooiing is uw tenant gereed voor agentontwikkeling en MCP-serverconfiguratie.

MCP-servers configureren

Gebruik de Agent 365 CLI om MCP-servers voor uw agent te detecteren, toe te voegen en te beheren. Zie de MCP-servercatalogus voor een volledige lijst met beschikbare MCP-servers en hun mogelijkheden.

Beschikbare servers detecteren

Geef alle MCP-servers weer die u kunt configureren:

a365 develop list-available

MCP-servers toevoegen

Een of meer MCP-servers toevoegen aan de configuratie van uw agent:

a365 develop add-mcp-servers mcp_MailTools

Geconfigureerde servers weergeven

Momenteel geconfigureerde MCP-servers weergeven:

a365 develop list-configured

MCP-servers verwijderen

Een MCP-server verwijderen uit uw configuratie:

a365 develop remove-mcp-servers mcp_MailTools

Voor de volledige CLI-referentie raadpleegt u a365-ontwikkelopdracht.

Mock-toolingserver gebruiken om te testen

Voor testen en ontwikkeling, gebruik de Agent 365 CLI een mock-toolingserver in plaats van verbinding te maken met echte MCP-servers. De mock-toolingserver simuleert interacties met MCP-servers, zodat u uw agent lokaal kunt testen zonder externe afhankelijkheden zoals verificatie.

De mockserver biedt de volgende voordelen voor lokale ontwikkeling en testen:

• Offline ontwikkeling: test uw agent zonder internetverbinding of externe afhankelijkheden.
• Consistent testen: ontvang voorspelbare respons voor het testen van randgevallen.
• Foutopsporing: bekijk alle verzoeken en respons in realtime
• Snelle iteratie: geen wachten op externe API-aanroepen of het opzetten van complexe testomgevingen.

Start de mock-toolingserver met behulp van de opdracht a365 develop start-mock-tooling-server.

Leer hoe u de mock-toolingserver installeert en configureert.

Inzicht in het hulpprogrammamanifest

Wanneer u deze uitvoert a365 develop add-mcp-servers, genereert de CLI een ToolingManifest.json bestand met configuratie voor alle MCP-servers. De agentruntime gebruikt dit manifest om te begrijpen welke servers beschikbaar zijn en hoe u ermee kunt verifiëren.

Manifeststructuur

Voorbeeld:ToolingManifest.json

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

Manifestparameters

Elke MCP-serververmelding bevat:

Hulpprogramma's integreren in uw agent

Nadat u het hulpprogrammamanifest hebt gegenereerd, integreert u de geconfigureerde MCP-servers in uw agentcode. In deze sectie worden de optionele inspectiestap en de vereiste integratiestappen beschreven.

Hulpprogrammaservers weergeven (optioneel)

Gebruik de configuratieservice van de hulpprogrammaserver om te detecteren welke hulpprogrammaservers beschikbaar zijn voor uw agent vanuit het hulpprogrammamanifest. Met deze methode kunt u:

• Voer een query uit op alle geconfigureerde MCP-servers vanuit het bestand ToolingManifest.json.
• Haal metagegevens en mogelijkheden van de server op.
• Controleer beschikbaarheid van de server vóór registratie.

De methode voor het weergeven van hulpprogrammaservers is beschikbaar in de belangrijkste hulpprogrammapakketten:

# 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);

Hulpprogramma's registreren bij uw orchestrator

Gebruik de frameworkspecifieke extensiemethode om alle MCP-servers te registreren bij uw indelingsframework:

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

Deze methoden:

• Alle hulpprogramma's van geconfigureerde MCP-servers registreren bij uw orchestrator
• Verificatie- en verbindingsdetails automatisch instellen
• Hulpprogramma's onmiddellijk beschikbaar maken om uw agent aan te roepen

Kies uw orchestrator-extensie

De module Agent 365 Tooling biedt speciale uitbreidingspakketten voor verschillende indelingsframeworks:

Zie de Voorbeelden van Agent 365 voor gedetailleerde implementaties.

Implementatievoorbeelden

In de volgende voorbeelden ziet u hoe u Agent 365 Tooling integreert met verschillende indelingskaders.

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

Zie de opslagplaats met Agent 365-voorbeelden voor volledige werkvoorbeelden.

Andere manieren om toegang te krijgen tot Agent 365 MCP-servers

Naast de Agent 365 SDK kunt u via andere ontwikkelervaringen toegang krijgen tot Agent 365 MCP-servers:

• Visual Studio Code: verbind direct met MCP-servers voor aangepaste ontwikkelwerkstromen.
• Microsoft Copilot Studio: integreer MCP-servers in gespreksstromen met behulp van een ervaring met weinig code.
• Azure AI Foundry: gebruik MCP-servers met volledige SDK-ondersteuning en geavanceerde indelingsmogelijkheden.

Zie voor een volledig overzicht van beschikbare MCP-servers en integratieopties op deze platforms Overzicht van Agent 365-hulpprogrammaservers.

Bring your own (BYO) MCP-server

De Bring Your Own (BYO) MCP-serverfunctie stelt u in staat uw eigen externe MCP-servers te registreren bij Microsoft Agent 365, zodat ze centraal kunnen worden beheerd, goedgekeurd en gecontroleerd in het Microsoft 365-beheercentrum. Deze servers worden via de Agent 365 tooling-gateway geleid, waardoor beheerders controle hebben over goedkeuring, toegang en beleid, terwijl beveiligingsteams het gebruik via telemetrie kunnen controleren. Als ontwikkelaar kunt u uw MCP-server registreren via de Agent 365 CLI; vervolgens kan uw beheerder de registratie beoordelen en goedkeuren, en de benodigde machtigingen verlenen. De goedgekeurde server kan vervolgens worden gebruikt in ondersteunde clienttoepassingen, waarbij voortdurende controle zorgt voor naleving en zichtbaarheid over alle integraties.

Zie voor volledige instructies Bring Your Own (BYO) MCP-server.

Uw agent testen

Nadat u MCP-hulpprogramma's in uw agent hebt geïntegreerd, test u de aanroepen van het hulpprogramma om ervoor te zorgen dat ze correct werken en verschillende scenario's afhandelen. Volg de testgids om uw omgeving in te stellen. Richt u daarna vooral op het gedeelte Aanroepen van testhulpprogramma's om te valideren dat uw MCP-tools werken zoals verwacht. Bekijk ook de mock-toolingserver om de MCP-serververbinding en tool-aanroepen te testen zonder dat u verificatie hoeft af te handelen.

Waarneembaarheid toevoegen

Voeg waarneembaarheid toe aan uw agent om de MCP-tool-aanroepen van uw agent te controleren en te traceren. Door waarneembaarheidsmogelijkheden toe te voegen, kunt u prestaties bijhouden, problemen oplossen en gebruikspatronen van tools begrijpen. Meer informatie over het implementeren van tracering en controle.

Probleemoplossing

Deze sectie vermeldt veelvoorkomende problemen bij het configureren en gebruiken van MCP-servers en -tools.

MCP-server- en toolingproblemen

Symptomen:

• Fouten bij het aanroepen van tools.
• "MCP Server niet gevonden"-fouten.
• Fouten met toestemming geweigerd bij het aanroepen van tools.

Hoofdoorzaak:

• MCP-server is niet geconfigureerd.
• Ontbrekende machtigingen.
• Service-principal is niet ingesteld.
• Verwarring tussen mock- en productieservers.

Oplossingen: probeer de volgende oplossingen om het probleem aan te pakken.

• Controleren of MCP-servers zijn geconfigureerd

  Geconfigureerde servers weergeven en ontbrekende toevoegen.

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

• Controleren of de service-principal bestaat

  Zorg dat de vereiste service-principal is gemaakt voor tooling.

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

• Gebruik mock-servers voor vroege ontwikkeling en testen

  Gebruik de mock-toolingserver voor vroege lokale ontwikkeling en testen als u de rest van uw agent wilt testen zonder productie-toolingcomponenten.

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

  Meer leren over de mock-toolingserver.

• Machtigingen controleren in het beheercentrum

  Controleer of uw agent over de benodigde MCP-machtigingen beschikt.

  • Controleren of de API-machtigingen van uw agentblauwdruk in de Azure Portal alle MCP-serverrechten tonen.

  Verificatie:

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