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 un flusso di lavoro in quattro passaggi:

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 con configurazioni del server
3. Esegui l'integrazione nel codice: carica il manifesto e registra gli strumenti con l'agente di orchestrazione
4. Richiama 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
• 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'ID dell'app agentico e l'utente agentico che permettono al tuo agente di autenticarsi e accedere agli strumenti MCP.

Impostare l'entità servizio

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

1. Scarica il copioneNew-Agent365ToolsServicePrincipalProdPublic.ps1 .

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

3. Esegui lo script.

   .\New-Agent365ToolsServicePrincipalProdPublic.ps1
   

4. Accedi usando le tue credenziali Azure quando ti 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 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 informazioni di riferimento complete dell'interfaccia della riga di comando, vedi comando per lo sviluppo a365.

Usa il server di mock tooling per i test

Per test e sviluppo, usa il server mock di strumenti CLI Agent 365 invece di collegarti ai veri server MCP. 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 configurare e configurare il server di strumenti mock.

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.

Server di strumenti elenco (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:

• Interroga tutti i server MCP configurati ToolingManifest.json dal file.
• 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'agente di orchestrazione

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

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.

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:

• Fallimenti delle chiamate degli strumenti.
• Errori "server MCP non trovato".
• Errori di permesso negato quando si chiamano gli strumenti.

Causa radice:

• Il server MCP non è configurato.
• Permessi mancanti.
• Il principale del servizio 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
  

• Controlla l'esistenza del principio 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 vuoi testare il resto del tuo agente senza componenti di 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.

  • Verifica che i permessi dell'API del tuo agente blueprint nel portale Azure mostrino tutti i permessi del server MCP.

  Verifica:

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