Lägga till och hantera verktyg

Verktygsmodulen hjälper utvecklare att upptäcka, konfigurera och integrera Model Context Protocol (MCP)-servrar i arbetsflöden för AI-agenter. MCP-servrar exponerar externa funktioner som verktyg som AI-agenter kan anropa. För en översikt över tillgängliga verktygsservrar, se Agent 365 verktygsservrar.

Översikt

Agent 365 Tooling-integrationen följer detta arbetsflöde:

1. Konfigurera MCP-servrar – Använd Agent 365 CLI för att upptäcka och lägga till MCP-servrar
2. Generera manifest - CLI skapar ToolingManifest.json i din projektmapp med serverkonfigurationer.
3. Tillämpa behörigheter på blueprint – En global administratör ger OAuth2-behörigheter till agentens blueprint genom att köra a365 setup all (första installationen) eller a365 setup permissions mcp (om blueprinten redan finns). Hur som helst läser kommandot ToolingManifest.json och kräver administratörens samtycke. Detta steg är alltid separat från att lägga till servrar i manifestet.
4. Integrera i din kod – ladda manifestet och registrera verktyg med din orkestrering.
5. Anropa verktyg – Agenten anropar verktyg under körning för att utföra operationer.

Krav

Innan du konfigurerar MCP-servrar ska du se till att du har:

• Agent 365 CLI installerad och konfigurerad
• .NET 8.0 SDK eller högre – Ladda ner
• Globala administratörsrättigheter i din Microsoft 365-tenant

Ställ in agentidentitet

Om du använder agentautentisering, slutför agentregistreringsprocessen för att skapa din agentidentitet innan du konfigurerar MCP-servrar. Denna process skapar Entra agent-ID och agentanvändaren som gör det möjligt för din agent att autentisera och få tillgång till MCP-verktyg.

OBO-autentiseringsinställningar

Om du använder On-Behalf-Of (OBO)-autentisering istället för agentisk autentisering kan din agent komma åt MCP-verktyg genom att använda delegerade användarbehörigheter utan agentidentitet. I OBO-flödet byter agenten ut en användares delegerad token för att utföra åtgärder för användarens räkning.

För mer information om hur OBO-flödet fungerar, se Autentiseringsflöden. För ett fullständigt implementeringsexempel, se OBO-auktorisationsexemplet i SDK för Microsoft 365-agenter.

Konfigurera huvudkonto för tjänsten

Kör detta engångs-installationsskript för att skapa tjänsteprincipen för Agent 365 Tools i din hyresgäst.

1. Ladda ner skriptet New-Agent365ToolsServicePrincipalProdPublic.ps1.

2. Öppna PowerShell som administratör och gå till skriptkatalogen.

3. Kör skriptet.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Logga in med autentiseringsuppgifterna för Azure när du blir ombedd.

När du är klar är din tenant redo för agentutveckling och konfiguration av MCP-servrar.

Konfigurera MCP-servrar

Använd Agent 365 CLI för att upptäcka, lägga till och hantera MCP-servrar för din agent. För en komplett lista över tillgängliga MCP-servrar och deras funktioner, se MCP-serverkatalogen.

Upptäck tillgängliga servrar

Visa alla MCP-servrar som du kan konfigurera:

a365 develop list-available

Lägg till MCP-servrar

Lägg till en eller flera MCP-servrar i din agentkonfiguration:

a365 develop add-mcp-servers mcp_MailTools

Lista konfigurerade servrar

Visa aktuella konfigurerade MCP-servrar:

a365 develop list-configured

Ta bort MCP-servrar

Ta bort en MCP-server från din konfiguration:

a365 develop remove-mcp-servers mcp_MailTools

För hela CLI-referensen, se a365 develop-kommandot.

Använd en mock tooling-server för testning

Vid testning och utveckling, använd Agent 365 CLI mock-server istället för att ansluta till riktiga MCP-servrar. Mock-servern simulerar MCP-serverinteraktioner, så du kan testa din agent lokalt utan externa beroenden som autentisering.

Den simulerade servern erbjuder följande fördelar för lokal utveckling och testning:

• Offlineutveckling: Testa din agent utan internetanslutning eller externa beroenden.
• Konsekvent testning: Få förutsägbara svar för att testa gränsfall.
• Felsökning: Visa alla förfrågningar och svar i realtid
• Snabb iteration: Du behöver inte vänta på externa API-anrop eller konfigurera komplexa testmiljöer.

Starta mock-verktygsservern med hjälp av a365 develop start-mock-tooling-serverkommandot.

Lär dig att ställa in och konfigurera mock-verktygsservern.

Förstå verktygsmanifestet

När du kör a365 develop add-mcp-servers genererar CLI:n en ToolingManifest.json-fil som innehåller konfiguration för alla MCP-servrar. Agentens körtid använder manifestet för att förstå vilka servrar som är tillgängliga och hur den autentiserar sig mot dem.

Manifest-struktur

Exempel ToolingManifest.json:

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

Parametrar för manifest

Varje MCP-serverpost innehåller:

Integrera verktyg i din agent

Efter att ha genererat verktygsmanifestet, integrera de konfigurerade MCP-servrarna i din agentkod. Detta avsnitt täcker det valfria inspektionssteget och de nödvändiga integrationsstegen.

Lista verktygsservrar (valfritt)

Använd verktygsserverkonfigurationstjänsten för att upptäcka vilka verktygsservrar som är tillgängliga för din agent från verktygsmanifestet. Med den här metoden kan du göra följande:

• Fråga alla konfigurerade MCP-servrar från ToolingManifest.json-filen.
• Hämta servermetadata och kapabiliteter.
• Kontrollera servertillgängligheten innan registrering.

Metoden för att lista verktygsservrar finns i kärnverktygspaketen:

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

Registrera verktyg hos din orkestratör

Använd den ramverksspecifika tilläggsmetoden för att registrera alla MCP-servrar med ditt orkestreringsramverk:

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

Dessa metoder:

• Registrera alla verktyg från konfigurerade MCP-servrar hos din orkestrator
• Autentiserings- och anslutningsuppgifter ställs in automatiskt
• Gör verktyg omedelbart tillgängliga för din agent att anropa

Välj din orkestratörförlängning

Agent 365 Tooling-modulen tillhandahåller dedikerade tilläggspaket för olika orkestreringsramverk:

För utförliga implementeringsexempel, se Agent 365-exempel.

Implementeringsexempel

Följande exempel visar hur man integrerar Agent 365 Tooling med olika orkestreringsramverk.

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

För fullständiga fungerande exempel, se Agent 365 Samples repository.

Andra sätt att komma åt Agent 365 MCP-servrar

Utöver Agent 365 SDK kan du nå Agent 365 MCP-servrar via andra utvecklingsupplevelser:

• Visual Studio Code – Koppla direkt till MCP-servrar för anpassade utvecklingsarbetsflöden.
• Microsoft Copilot Studio – Integrera MCP-servrar i konversationsflöden med hjälp av en low-code-upplevelse.
• Azure AI Foundry - Använd MCP-servrar med fullt SDK-stöd och avancerade orkestreringsfunktioner.

För en fullständig översikt över tillgängliga MCP-servrar och integrationsalternativ på dessa plattformar, se översikt över Agent 365-verktygsservrar.

Ta med din egen (BYO) MCP-server

Funktionen Bring Your Own (BYO) MCP-server gör det möjligt att registrera egna externa MCP-servrar hos Microsoft Agent 365, så att de kan styras, godkännas och övervakas centralt i Administrationscenter för Microsoft 365. Servrarna dirigeras genom Agent 365-verktygs-gatewayen, vilket ger administratörer kontroll över godkännande, åtkomst och policies, samtidigt som säkerhetsteam kan övervaka användningen via telemetri. Som utvecklare kan du registrera din MCP-server genom Agent 365 CLI, och därefter låta din administratör granska och godkänna registreringen samt bevilja behörigheter. Den godkända servern kan därefter användas i stödda klientverktyg, med kontinuerlig övervakning som säkerställer efterlevnad och transparens över alla integrationer.

För fullständiga instruktioner, se Bring your own (BYO) MCP-server.

Testa din agent

Efter att du har integrerat MCP-verktyg i din agent, testa verktygsanropen för att säkerställa att de fungerar korrekt och hanterar olika scenarier. Följ testguiden för att konfigurera din miljö. Fokusera sedan främst på avsnittet Testverktygsanrop för att validera att dina MCP-verktyg fungerar som förväntat. Kolla också in mock-verktygsservern för att testa MCP-serveranslutning och verktygsanrop utan att hantera autentisering.

Lägg till överskådlighet

Lägg till observability för din agent för att övervaka och spåra MCP-verktygsanrop. Genom att lägga till observerbarhetsfunktioner kan du spåra prestanda, felsöka problem och förstå verktygsanvändningsmönster. Läs mer om hur du implementerar spårning och övervakning.

Felsökning

Detta avsnitt listar vanliga problem när du konfigurerar och använder MCP-servrar och verktyg.

MCP-server- och verktygsproblem

Symtom:

• Misslyckade verktygsanrop.
• "MCP-server hittades inte"-fel.
• Behörighet nekade fel vid anrop av verktyg.

Grundorsak:

• MCP-servern är inte konfigurerad.
• Behörigheter saknas.
• Huvudkonto för tjänsten har inte ställts in.
• Förvirring mellan mock- och produktionsservrar.

Lösningar: Prova följande lösningar för att åtgärda problemet.

• Verifiera att MCP-servrar är konfigurerade

  Lista konfigurerade servrar och lägg till eventuella saknade.

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

• Kontrollera att serviceprincipal finns

  Säkerställ att den nödvändiga serviceprincipalen är skapad för verktygshantering.

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

• Vid tidig utveckling och testning, använd mockservrar

  Använd mock-verktygsservern för tidig lokal utveckling och testning om du vill testa resten av din agent utan produktionsverktygskomponenter.

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

  Lär dig om mock tooling-servern.

• Verifiera behörigheter i administrationscentret

  Bekräfta att agenten har de MCP-behörigheter som krävs.

  • Validera att din agents blueprint-API-behörigheter i Azure-portalen omfattar samtliga MCP-serverbehörigheter.

  Verifiering:

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