Aggiungere e gestire strumenti

Il modulo Strumenti consente agli sviluppatori di individuare, configurare e integrare server MCP (Model Context Protocol) nei flussi di lavoro dell'agente IA. 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. Genera il manifesto: l'interfaccia della riga di comando crea ToolingManifest.json nella cartella del progetto con le configurazioni del server.
3. Applica le autorizzazioni al progetto: un amministratore globale concede le autorizzazioni OAuth2 al progetto dell'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. Esegui l'integrazione nel codice: carica il manifesto e registra gli strumenti con l'orchestratore.
5. Richiama gli strumenti: l'agente 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
• SDK .NET 8.0 o versione successiva: Download
• Privilegi di amministratore globale nel tenant di 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'Entra agent ID e l'utente dell'agente che consente all'agente di autenticare e accedere agli strumenti MCP.

Configurazione autenticazione OBO

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

Per ulteriori informazioni su come funziona il flusso OBO, consulta Flussi di autenticazione. Per un esempio completo di implementazione, vedi l'esempio di autorizzazione OBO nell'SDK per agenti Microsoft 365.

Impostare l'entità servizio

Esegui questo script di installazione una tantum per creare l'entità servizio per gli strumenti di Agent 365 nel tenant.

1. Scarica lo script New-Agent365ToolsServicePrincipalProdPublic.ps1.

2. Apri PowerShell come amministratore e passa alla directory degli script.

3. Esegui lo script.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Accedi con le tue credenziali di Azure quando viene 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 possono essere configurati:

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 informazioni di riferimento complete dell'interfaccia della riga di comando, vedi comando per lo sviluppo a365.

Usare il server di strumenti simulato per i test

Per test e sviluppo, usa il server di strumenti simulato dell'interfaccia della riga di comando di Agent 365 invece di collegarti ai server MCP reali. Il server simulato simula le interazioni con il 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 i test in locale:

• Sviluppo offline: puoi testare il tuo agente senza la connettività Internet o dipendenze esterne.
• Test coerenti: ricevi risposte prevedibili per i test di casi limite.
• Debug: puoi visualizzare tutte le richieste e le risposte in tempo reale
• Iterazione veloce: nessun bisogno di attendere chiamate di API esterne o di configurare ambienti di test complessi.

Avvia il server di strumenti simulato utilizzando il comando a365 develop start-mock-tooling-server.

Informazioni su come impostare e configurare il server di strumenti simulato.

Comprendere il manifesto degli strumenti

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.

Elencare i server degli strumenti (facoltativo)

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:

• Eseguire query su tutti i server MCP configurati dal file ToolingManifest.json.
• Recuperare metadati e funzionalità del server.
• Verificare la disponibilità del 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:

• Registrano tutti gli strumenti dai server MCP configurati con l'agente di orchestrazione
• Configurano automaticamente i dettagli di autenticazione e connessione
• Rendono immediatamente disponibili gli strumenti che l'agente può richiamare

Scegliere l'estensione dell'agente di orchestrazione

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

Gli esempi seguenti illustrano come integrare gli strumenti di Agent 365 con framework di orchestrazione diversi.

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 di Agent 365

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

• Visual Studio Code - Collegati direttamente ai server MCP per flussi di lavoro di sviluppo personalizzati.
• Microsoft Copilot Studio - Integra i server MCP nei flussi conversazionali utilizzando un'esperienza con poco codice.
• Azure AI Foundry - Utilizza server MCP con il supporto completo per l'SDK e le funzionalità di orchestrazione avanzate.

Per una panoramica completa dei server MCP disponibili e delle opzioni di integrazione su queste piattaforme, fai riferimento a Panoramica dei server MCP di Agent 365.

Server MCP Bring your own (BYO)

La funzione server MCP Bring Your Own (BYO) ti permette di registrare i tuoi server MCP esterni con Microsoft Agent 365, così da poterli gestire centralmente, approvare e monitorare nell'interfaccia di amministrazione di Microsoft 365. Inoltra questi server attraverso il gateway di strumenti di Agent 365, consentendo agli amministratori di controllare l'approvazione, l'accesso e i criteri, mentre permette ai team di sicurezza di monitorare l'utilizzo tramite telemetria. Come sviluppatore, puoi registrare il tuo server MCP usando l'interfaccia della riga di comando di Agent 365, quindi chiedere all'amministratore di controllare e approvare la registrazione e concedere le autorizzazioni. Il server approvato può quindi essere utilizzato negli strumenti client supportati, e il monitoraggio continuo garantisce conformità e visibilità attraverso tutte le integrazioni.

Per istruzioni complete, consulta Server MCP Bring your own (BYO).

Test dell'agente

Dopo aver integrato gli strumenti MCP nell'agente, testa le chiamate agli strumenti per verificare che funzionino correttamente e gestiscano scenari diversi. Segui la guida ai test per configurare l'ambiente. Quindi, concentrati principalmente sulla sezione Test delle invocazioni degli strumenti per verificare che i tuoi strumenti MCP funzionino come previsto. Dai un'occhiata al server di strumenti simulato per testare la connessione al server MCP e le chiamate degli strumenti senza gestire l'autenticazione.

Aggiungere osservabilità

Aggiungi osservabilità al tuo agente per monitorare e tracciare le chiamate degli strumenti MCP del tuo agente. Aggiungendo funzionalità di osservabilità, puoi monitorare le prestazioni, eseguire il debug dei problemi e comprendere i modelli di utilizzo degli strumenti. Altre informazioni sull'implementazione della traccia e del monitoraggio.

Risoluzione dei problemi

Questa sezione elenca i problemi comuni durante la configurazione e l'utilizzo dei server e degli strumenti MCP.

Problemi relativi al server MCP e agli strumenti

Sintomi:

• Errori nelle chiamate degli strumenti.
• Errori "server MCP non trovato".
• Errori di permessi negati quando si utilizzano gli strumenti.

Causa radice:

• Il server MCP non è configurato.
• Autorizzazioni mancanti.
• L'entità servizio non è configurata.
• Confusione tra server simulato e server di produzione.

Soluzioni: Prova le seguenti soluzioni per risolvere 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 che l'entità servizio esista

  Assicurati che l'entità servizio richiesta sia creata per gli strumenti.

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

  Usa il server di strumenti simulato per lo sviluppo e il test locale iniziale se vuoi verificare il resto del tuo agente senza componenti 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 strumenti simulato.

• Verifica le autorizzazioni nell’interfaccia di amministrazione

  Verifica che l'agente disponga delle autorizzazioni MCP necessarie.

  • Verifica che le autorizzazioni API del progetto del tuo agente nel portale di Azure includano tutte le autorizzazioni del server MCP.

  Verifica:

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