Aggiungere e gestire strumenti

Il modulo Tooling aiuta gli sviluppatori a scoprire, configurare e integrare server Model Context Protocol (MCP) nei flussi di lavoro degli agenti AI. I server MCP espongono funzionalità esterne come strumenti che gli agenti IA possono richiamare. Per una panoramica dei server di strumenti disponibili, vedi Server di strumenti di Agent 365.

Panoramica

L'integrazione degli strumenti di Agent 365 segue questo flusso di lavoro:

1. Configura i server MCP: usa l'interfaccia della riga di comando di Agent 365 per individuare e aggiungere server MCP
2. Generare manifest - CLI crea ToolingManifest.json nella cartella del progetto con le configurazioni del server.
3. Applicare le autorizzazioni al progetto : un amministratore globale concede le autorizzazioni OAuth2 al progetto agente eseguendo a365 setup all (prima configurazione) o a365 setup permissions mcp (se il progetto esiste già). In ogni caso, il comando legge ToolingManifest.json e richiede il consenso dell'amministratore. Questo passaggio è sempre separato dall'aggiunta di server al manifesto.
4. Eseguire l'integrazione nel codice : caricare il manifesto e registrare gli strumenti con l'agente di orchestrazione.
5. Richiamare gli strumenti : Agent chiama gli strumenti durante l'esecuzione per eseguire operazioni.

Prerequisiti

Prima di configurare i server MCP, assicurati di disporre di:

• Interfaccia della riga di comando di Agent 365 installata e configurata
• .NET 8.0 SDK o versione successiva: Download
• Privilegi di amministratore globale nel tenant Microsoft 365

Configurazione dell'identità dell'agente

Se stai utilizzando l'autenticazione dell'agente, completa il processo di registrazione dell'agente per creare l'identità dell'agente prima di configurare i server MCP. Questo processo crea l'ID dell'app agente e l'utente agente che consentono al tuo agente di autenticarsi e accedere agli strumenti MCP.

Configurazione dell'autenticazione OBO

Se usi l'autenticazione On-Behalf-Of (OBO) invece dell'autenticazione agentica, il tuo agente può accedere agli strumenti MCP utilizzando permessi utente delegati senza un'identità utente agente. Nel flusso OBO, l'agente scambia il token delegato da un utente per eseguire azioni a suo conto.

Per maggiori informazioni su come funziona il flusso OBO, vedi Flussi di autenticazione. Per un esempio di implementazione completo, vedere l'esempio di autorizzazione OBO nel Microsoft 365 Agents SDK.

Impostare il principale del servizio

Esegui questo script di configurazione monouso per creare il principale di servizio per Agent 365 Tools nel tuo tenant.

1. Scarica il New-Agent365ToolsServicePrincipalProdPublic.ps1 script.

2. Apri PowerShell come Amministratore e vai nella directory degli script.

3. Esegui lo script.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Accedere usando le credenziali di Azure quando richiesto.

Al termine, il tenant è pronto per lo sviluppo dell'agente e la configurazione del server MCP.

Configurare i server MCP

Usa l'interfaccia della riga di comando di Agent 365 per individuare, aggiungere e gestire i server MCP per l'agente. Per un elenco completo dei server MCP disponibili e delle relative funzionalità, vedi il catalogo dei server MCP.

Individuare i server disponibili

Elenca tutti i server MCP che puoi configurare:

a365 develop list-available

Aggiungere server MCP

Aggiungi uno o più server MCP alla configurazione dell'agente:

a365 develop add-mcp-servers mcp_MailTools

Elencare i server configurati

Visualizza i server MCP attualmente configurati:

a365 develop list-configured

Rimuovere i server MCP

Rimuovi un server MCP dalla configurazione:

a365 develop remove-mcp-servers mcp_MailTools

Per il riferimento completo alla CLI, vedi a365 develop command.

Usa il server di mock tooling per i test

Per i test e lo sviluppo, utilizza il server di simulazione CLI Agent 365 invece di collegarti ai server MCP effettivi. Il server mock simula le interazioni con i server MCP, così puoi testare il tuo agente localmente senza dipendenze esterne come l'autenticazione.

Il server simulato offre i seguenti vantaggi per lo sviluppo e il testing locale:

• Sviluppo offline: Testa il tuo agente senza connettività internet o dipendenze esterne.
• Test costanti: Ricevi risposte prevedibili per i casi limite.
• Debug: visualizza tutte le richieste e le risposte in tempo reale
• Iterazione veloce: Non c'è bisogno di aspettare chiamate API esterne o configurare ambienti di test complessi.

Avvia il server di mock tooling usando il a365 develop start-mock-tooling-server comando.

Impara a impostare e configurare il server di simulazione.

Comprendere il manifest degli strumenti di sviluppo

Quando esegui a365 develop add-mcp-servers, l'interfaccia della riga di comando genera un file ToolingManifest.json contenente la configurazione per tutti i server MCP. L'esecuzione dell'agente usa questo manifesto per comprendere quali server sono disponibili e come eseguire l'autenticazione con essi.

Struttura del manifesto

Esempio ToolingManifest.json:

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

Parametri del manifesto

Ogni voce del server MCP contiene:

Integrare gli strumenti nell'agente

Dopo aver generato il manifesto degli strumenti, integra i server MCP configurati nel codice dell'agente. Questa sezione illustra il passaggio facoltativo di ispezione e i passaggi di integrazione obbligatori.

Elenca i server degli strumenti (opzionale)

Usa il servizio di configurazione del server degli strumenti per individuare quali server di strumenti sono disponibili per l'agente dal manifesto degli strumenti. Questo metodo consente di:

• Verifica tutti i server MCP configurati dal file ToolingManifest.json.
• Recupera i metadati e le capacità del server.
• Verifica la disponibilità dei server prima della registrazione.

Il metodo per elencare i server degli strumenti è disponibile nei pacchetti di strumenti di base:

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

Registrare gli strumenti con l'orchestratore

Usa il metodo di estensione specifico del framework per registrare tutti i server MCP con il framework di orchestrazione:

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

Questi metodi:

• Registra tutti gli strumenti dai server MCP configurati con il tuo orchestratore
• Configurano automaticamente i dettagli di autenticazione e connessione
• Rendi immediatamente disponibili gli strumenti per consentire all'agente di richiamarli.

Scegliere l'estensione dell'orchestratore

Il modulo Strumenti di Agent 365 offre pacchetti di estensione dedicati per diversi framework di orchestrazione:

Per esempi di implementazione dettagliati, vedi Esempi di Agent 365.

Esempi di implementazione

I seguenti esempi mostrano come integrare gli Strumenti Agent 365 con diversi framework di orchestrazione.

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

Per esempi di lavoro completi, vedi il repository degli esempi di Agent 365.

Altri modi per accedere ai server MCP dell'Agent 365

Oltre all'SDK Agent 365, puoi accedere ai server MCP di Agent 365 tramite altre esperienze di sviluppo:

• Visual Studio Code: connettersi direttamente ai server MCP per i flussi di lavoro di sviluppo personalizzati.
• Microsoft Copilot Studio - Integrare i server MCP in flussi di conversazione usando un'esperienza a basso codice.
• Azure AI Foundry: usare server MCP con supporto SDK completo e funzionalità di orchestrazione avanzate.

Per una panoramica completa dei server MCP disponibili e delle opzioni di integrazione su queste piattaforme, vedi panoramica dei server di strumenti di Agent 365.

Test dell'agente

Dopo aver integrato gli strumenti MCP nel tuo agente, testa le invocazioni degli strumenti per assicurarti che funzionino correttamente e gestiscano diversi scenari. Segui la guida ai test per impostare il tuo ambiente. Poi, concentrati principalmente sulla sezione delle invocazioni degli strumenti di Test per verificare che i tuoi strumenti MCP funzionano come previsto. Inoltre, dai un'occhiata al mock tooling server per testare la connessione al server MCP e le invocazioni degli strumenti senza gestire l'autenticazione.

Aggiungere osservabilità

Aggiungi osservabilità al tuo agente per monitorare e tracciare le invocazioni dello strumento MCP del tuo agente. Aggiungendo capacità di osservabilità, puoi monitorare le prestazioni, debug problemi e comprendere i modelli di utilizzo degli strumenti. Scopri di più sull'implementazione del tracciamento e del monitoraggio.

Risoluzione dei problemi

Questa sezione elenca i problemi comuni quando si configurano e si utilizzano server e strumenti MCP.

Problemi con il server MCP e gli strumenti

Sintomi:

• Errori di chiamata dello strumento.
• Errori "server MCP non trovato".
• Errori di permessi negati quando si utilizzano gli strumenti.

Causa radice:

• Il server MCP non è configurato.
• Permessi mancanti.
• Il service principal non è stato impostato.
• Confusione tra server mock e server di produzione.

Soluzioni: Prova le seguenti soluzioni per affrontare il problema.

• Verifica che i server MCP siano configurati

  Elenca i server configurati e aggiungi quelli mancanti.

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

• Verifica se esiste un principale del servizio

  Assicurati che il principio di servizio richiesto sia creato per gli attrezzi.

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

• Per lo sviluppo e i test iniziali, usa server mock

  Usa il server di strumenti mock per lo sviluppo locale iniziale e i test, se desideri testare il resto del tuo agente senza i componenti degli strumenti di produzione.

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

  Scopri il server di mock tooling.

• Verifica i permessi nel centro amministrativo

  Conferma che il tuo agente abbia i permessi MCP necessari.

  • Verificare che le autorizzazioni dell'API del progetto agente nel portale di Azure visualizzino tutte le autorizzazioni del server MCP.

  Verifica:

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