Hulpmiddelen toevoegen en beheren

Belangrijk

U moet deelnemen aan het preview-programma Frontier om vroegtijdige toegang te krijgen tot Microsoft Agent 365. Frontier verbindt u rechtstreeks met de nieuwste AI-innovaties van Microsoft. Op Frontier-previews zijn de bestaande preview-voorwaarden van uw klantovereenkomsten van toepassing. Omdat deze functies nog in ontwikkeling zijn, kunnen de beschikbaarheid en mogelijkheden hiervan na verloop van tijd veranderen.

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 een werkstroom van vier stappen:

1. MCP-servers configureren - Agent 365 CLI gebruiken om MCP-servers te detecteren en toe te voegen
2. Manifest genereren - CLI maakt ToolingManifest.json met serverconfiguraties
3. Integreren in code - Manifest laden en hulpprogramma's registreren bij uw orchestrator
4. 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. Hiermee maakt u de agentische app-id en agentische gebruiker, waarmee uw agent MCP-hulpprogramma's kan verifiëren en openen.

Service-principal instellen

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

Belangrijk

Dit is een EENMALIGE bewerking per tenant, waarvoor globale beheerdersbevoegdheden zijn vereist.

1. Download het script New-Agent365ToolsServicePrincipalProdPublic.ps1

2. Open PowerShell als beheerder en navigeer naar de scriptmap

3. Het script uitvoeren:

   .\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 kunnen worden geconfigureerd:

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 een volledige CLI-referentie raadpleegt u a365-ontwikkelopdracht.

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:

Parameters	Omschrijvingen
mcpServerName	De weergavenaam van de MCP-server
mcpServerUniqueName	De unieke id voor het MCP-serverexemplaar
bereik	Het OAuth-bereik dat is vereist voor toegang tot de mogelijkheden van de MCP-server (bijvoorbeeld McpServers.Mail.All voor e-mailbewerkingen). Deze waarde wordt opgehaald uit de MCP-servercatalogus wanneer u de opdracht add-mcp-servers uitvoert.
doelgroep	De Microsoft Entra ID-URI die de doel-API-resource identificeert. Deze waarde wordt ook opgehaald uit de MCP-servercatalogus.

Notitie

De waarden scope en audience worden automatisch ingevuld door de Agent 365 CLI wanneer u een MCP-server toevoegt. Deze waarden zijn afkomstig uit de MCP-servercatalogus en definiëren de machtigingen die nodig zijn voor toegang tot elke MCP-server.

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)

Tip

Deze stap is optioneel. Gebruik de configuratieservice van de hulpprogrammaserver, om beschikbare hulpprogrammaservers te controleren vanuit het hulpprogrammamanifest, voordat u deze toevoegt aan uw orchestrator.

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 de ToolingManifest.json
• Metagegevens en mogelijkheden van de server ophalen
• De beschikbaarheid van de server controleren vóór registratie

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

Python

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

Parameters:

Parameter	Type	Omschrijving	Verwachte waarde	Vereist/Optioneel
agentic_app_id	str	De unieke id voor het agenttoepassingsexemplaar	Geldige tekenreeks voor agenttoepassings-id	Vereist
auth_token	str	Bearer-token voor verificatie met de MCP-servergateway	Geldig OAuth Bearer-token	Vereist

Pakket: microsoft-agents-a365-tools

JavaScript

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

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

Parameters:

Parameter	Type	Omschrijving	Verwachte waarde	Vereist/Optioneel
agentInstanceId	tekenreeks	De unieke id voor het agentexemplaar	Geldige tekenreeks voor agentexemplaar-id	Vereist
authToken	tekenreeks	Bearer-token voor verificatie met de MCP-servergateway	Geldig OAuth Bearer-token	Vereist

Pakket: Microsoft.Agents.A365.Tools

.NET

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

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

Parameters:

Parameter	Type	Omschrijving	Verwachte waarde	Vereist/Optioneel
agentInstanceId	tekenreeks	De unieke id voor het agentexemplaar	Geldige tekenreeks voor agentexemplaar-id	Vereist
authToken	tekenreeks	Bearer-token voor verificatie met de MCP-servergateway	Geldig OAuth Bearer-token	Vereist

Pakket: Microsoft.Agents.A365.Tools

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:

Python

• microsoft-agents-a365-tools: Kernfunctionaliteit voor hulpprogramma's
• microsoft-agents-a365-tools-extensies-agentframework: Agent Framework-integratie
• microsoft-agents-a365-tools-extensies-azureaifoundry: Azure AI Foundry-integratie
• microsoft-agents-a365-tools-extensies-openai: OpenAI-integratie
• microsoft-agents-a365-tools-extensies-semantickernel: Semantic Kernel-integratie

JavaScript

• @microsoft/agents-a365-tools: Kernfunctionaliteit voor hulpprogramma's
• @microsoft/agents-a365-tooling-extensions-claude: Claude integration
• @microsoft/agents-a365-tools-extensies-openai: OpenAI-integratie
• @microsoft/agents-a365-tools-extensies-langchain: LangChain-integratie

.NET

• Microsoft.Agents.A365.Tools: Kernfunctionaliteit voor hulpprogramma's
• Microsoft.Agents.A365.Tools.Extensies.AgentFramework: Agent Framework-integratie
• Microsoft.Agents.A365.Tools.Extensies.AzureAIFoundry: Azure AI Foundry-integratie
• Microsoft.Agents.A365.Tools.Extensies.SemanticKernel: Semantic Kernel-integratie

Notitie

Verificatie wordt automatisch geconfigureerd door de Agent 365 CLI wanneer u a365 develop add-mcp-servers uitvoert. De OAuth-bereiken en doelgroepwaarden worden opgehaald uit de MCP-servercatalogus en opgenomen in de ToolingManifest.json. De extensiemethoden gebruiken deze waarden automatisch om verificatie in te stellen. Er is geen handmatige configuratie vereist.

Zie de Voorbeelden van Agent 365 voor gedetailleerde implementaties.

Implementatievoorbeelden

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

Python

Python met OpenAI

In dit voorbeeld ziet u hoe u MCP-hulpprogramma's integreert met OpenAI in een Python-toepassing.

1. Importinstructies toevoegen

Voeg de vereiste importbewerkingen toe voor toegang tot de Tooling-module en OpenAI-extensies:

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

2. Hulpprogramma's initialiseren

Maak exemplaren van de configuratie- en hulpprogrammaregistratieservices:

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

3. MCP-hulpprogramma's registreren bij OpenAI-agent

Gebruik de add_tool_servers_to_agent methode om alle geconfigureerde MCP-hulpprogramma's te registreren bij uw OpenAI-agent. Deze methode verwerkt zowel agentische als niet-agentische verificatiescenario's:

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

Methodeparameters

In de volgende tabel wordt beschreven welke parameters u moet gebruiken met add_tool_servers_to_agent.

Parameters	Omschrijvingen
agent	Het OpenAI-agentexemplaar om hulpprogramma's bij te registreren.
agentic_app_id	De unieke id voor de agent (agentische app-id).
auth	De autorisatiecontext voor de gebruiker.
context	De context van de huidige gesprekswisseling uit de SDK voor agenten. Biedt gebruikersidentiteit, gespreksmetagegevens en verificatiecontext voor veilige registratie van hulpprogramma's.
auth_token	(Optioneel) Bearer-token voor scenario's met niet-agentische verificatie.

4. Bellen tijdens initialisatie

Zorg ervoor dat u de installatiemethode aanroept tijdens de initialisatie voordat u de agent uitvoert:

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

De add_tool_servers_to_agent methode wordt automatisch gebruikt:

• Laadt alle MCP-servers uit de ToolingManifest.json
• Registreert hun hulpprogramma's met de OpenAI-agent
• Hiermee stelt u verificatie in op basis van de manifestconfiguratie
• De hulpprogramma's beschikbaar maken die uw agent kan aanroepen

JavaScript

JavaScript met LangChain

In dit voorbeeld ziet u hoe u MCP-hulpprogramma's integreert met LangChain in een JavaScript-/TypeScript-toepassing.

1. Importinstructies toevoegen

Voeg de vereiste importbewerkingen toe voor toegang tot de Tooling-module en LangChain-extensies:

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

2. Hulpprogramma's initialiseren

Maak een exemplaar van de registratieservice voor hulpprogramma's:

const toolService = new McpToolRegistrationService();

3. MCP-hulpprogramma's registreren bij LangChain-agent

Gebruik de addToolServersToAgent methode om alle geconfigureerde MCP-hulpprogramma's te registreren bij uw LangChain-agent. Deze methode verwerkt zowel agentische als niet-agentische verificatiescenario's:

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

Methodeparameters

In de volgende tabel wordt beschreven welke parameters u moet gebruiken met de methode addToolServersToAgent.

Parameters	Omschrijvingen
agent	Het LangChain ReactAgent-exemplaar waarmee u hulpprogramma's registreert.
agentUserId	De unieke id voor de agentgebruiker. Kan een lege tekenreeks ('') zijn als deze geen agentische verificatie gebruikt.
authorization	De autorisatiecontext voor de gebruiker.
turnContext	De context van de huidige gesprekswisseling uit de SDK voor agenten. Biedt gebruikersidentiteit, gespreksmetagegevens en verificatiecontext voor veilige registratie van hulpprogramma's.
authToken	(Optioneel) Bearer-token voor scenario's met niet-agentische verificatie.

4. Bellen tijdens initialisatie

Roep de methode addToolServersToAgent aan tijdens de initialisatie om MCP-hulpprogramma's bij uw agent te registreren.

De addToolServersToAgent methode wordt automatisch gebruikt:

• Laadt alle MCP-servers uit de ToolingManifest.json
• Registreert hun hulpprogramma's met de LangChain-agent
• Hiermee stelt u verificatie in op basis van de manifestconfiguratie
• De hulpprogramma's beschikbaar maken die uw agent kan aanroepen

.NET

.NET met semantische kernel

In dit voorbeeld ziet u hoe u MCP-hulpprogramma's integreert met semantische kernel in een .NET-toepassing.

1. Importinstructies toevoegen

Voeg de vereiste naamruimten toe voor toegang tot de module Tooling en Semantische Kernel-extensies:

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

2. Services registreren met afhankelijkheidsinjectie

Voeg de hulpprogramma's toe aan uw container voor afhankelijkheidsinjectie, zodat deze in uw klassen kunnen worden geïnjecteerd:

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

3. Declaratie van privéveld toevoegen

Declareer een privéveld om de naslaginformatie over de registratieservice voor hulpprogramma's te bewaren:

private readonly IMcpToolRegistrationService _toolsService;

4. MCP-hulpprogramma's registreren met Semantische kernel

Gebruik de AddToolServersToAgentAsync extensiemethode om alle geconfigureerde MCP-hulpprogramma's te registreren bij uw Semantic Kernel-exemplaar. Deze methode verwerkt zowel agentische als niet-agentische verificatiescenario's:

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

Notitie

Er zijn meerdere methode-overbelastingen beschikbaar. De vereenvoudigde versie maakt gebruik van de standaardverificatieconfiguratie, terwijl de expliciete versie aangepaste verificatieverwerkingspecificatie toestaat.

Methodeparameters

In de volgende tabel wordt beschreven welke parameters u moet gebruiken met AddToolServersToAgentAsync

Parameters	Omschrijvingen
kernel	Het semantische kernelexemplaar om hulpprogramma's bij te registreren. De kernel organiseert AI-services, invoegtoepassingen en functie-uitvoering.
userAuthorization	De autorisatiecontext voor de gebruiker
authHandlerName	Naam van verificatieverwerker voor gebruik met het UserAuthorization System
turnContext	De context van de huidige gesprekswisseling (één gebruikersbericht en reactiecyclus van agent) van de Agents SDK. Biedt gebruikersidentiteit, gespreksmetagegevens en verificatiecontext voor veilige registratie van hulpprogramma's.
authToken	(Optioneel) Bearer-token voor scenario's met niet-agentische verificatie

De AddToolServersToAgentAsync methode wordt automatisch gebruikt:

• Laadt alle MCP-servers uit de ToolingManifest.json
• Registreert hun hulpprogramma's met de semantische kernel
• Hiermee stelt u verificatie in op basis van de manifestconfiguratie
• De hulpprogramma's beschikbaar maken die uw agent kan aanroepen

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

Testen en monitoren

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 testhandleiding om uw omgeving in te stellen en richt u vervolgens voornamelijk op de sectie Testhulpprogramma-aanroepen om te controleren of uw MCP-hulpprogramma's werken zoals verwacht.

Waarneembaarheid toevoegen

Voeg waarneembaarheid toe aan uw agent om de MCP-hulpprogramma's van uw agent te bewaken en traceren, om waarneembaarheidsmogelijkheden toe te voegen om prestaties bij te houden, problemen op te sporen en gebruikspatronen van hulpprogramma's te begrijpen. Meer informatie over het implementeren van tracering en bewaking