Condividi tramite

Aggiungere e gestire strumenti

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

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.

Illustra il flusso di richiesta e risposta

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:

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. In questo modo viene creato l'ID app dell'agente e l'utente dell'agente che consente all'agente di autenticare e accedere agli strumenti MCP.

Impostare l'entità servizio

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

Importante

Si tratta di un'operazione UNA TANTUM per tenant che richiede privilegi di amministratore globale.

  1. Scarica lo script New-Agent365ToolsServicePrincipalProdPublic.ps1

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

  3. Eseguire 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.

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:

Parametri Descrizioni
mcpServerName Nome visualizzato del server MCP
mcpServerUniqueName Identificatore univoco per l'istanza del server MCP
ambito Ambito OAuth obbligatorio per accedere alle funzionalità del server MCP (ad esempio McpServers.Mail.All per le operazioni di posta elettronica). Questo valore viene recuperato dal catalogo del server MCP quando esegui il comando add-mcp-servers.
gruppo di destinatari URI di Microsoft Entra ID che identifica la risorsa API di destinazione. Questo valore viene recuperato anche dal catalogo del server MCP.

Nota

I valori scope e audience vengono popolati automaticamente dall'interfaccia della riga di comando di Agent 365 quando aggiungi un server MCP. Questi valori provengono dal catalogo dei server MCP e definiscono le autorizzazioni obbligatorie per accedere a ogni server MCP.

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)

Mancia

Questo passaggio è facoltativo. Usa il servizio di configurazione del server degli strumenti per controllare i server degli strumenti disponibili dal manifesto degli strumenti prima di aggiungerli all'agente di orchestrazione.

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

Parametri:

Parametro Tipo Descrizione Valore previsto Obbligatorio/facoltativo
agentic_app_id str Identificatore univoco dell'istanza dell'applicazione agente Stringa ID applicazione agente valida Richiesto
auth_token str Token di connessione per l'autenticazione con il gateway server MCP Token di connessione OAuth valido Richiesto

Pacchetto: microsoft-agents-a365-tooling

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:

  • microsoft-agents-a365-tooling: funzionalità di base degli strumenti
  • microsoft-agents-a365-tooling-extensions-agentframework: integrazione di Agent Framework
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: integrazione di Fonderia Azure AI
  • microsoft-agents-a365-tooling-extensions-openai: integrazione di OpenAI
  • microsoft-agents-a365-tooling-extensions-semantickernel: integrazione del kernel semantico

Nota

L'autenticazione viene configurata automaticamente dall'interfaccia della riga di comando di Agent 365 quando esegui a365 develop add-mcp-servers. I valori dei gruppi di destinatari e degli ambiti OAuth vengono recuperati dal catalogo dei server MCP e inclusi in ToolingManifest.json. I metodi di estensione usano automaticamente questi valori per configurare l'autenticazione. Non è necessaria alcuna configurazione manuale.

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.

Python con OpenAI

Questo esempio illustra come integrare gli strumenti MCP con OpenAI in un'applicazione Python.

1. Aggiungi istruzioni di importazione

Aggiungi le importazioni necessarie per accedere al modulo Strumenti e alle estensioni OpenAI:

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

2. Inizializza i servizi di strumenti

Crea istanze dei servizi di registrazione degli strumenti e della configurazione:

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

3. Registra gli strumenti MCP con l'agente OpenAI

Usa il metodo add_tool_servers_to_agent per registrare tutti gli strumenti MCP configurati con l'agente OpenAI. Questo metodo gestisce scenari di autenticazione con agenti e senza agenti:

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

Parametri del metodo

La tabella seguente descrive i parametri da utilizzare con add_tool_servers_to_agent.

Parametri Descrizioni
agent Istanza dell'agente OpenAI con cui registrare gli strumenti.
agentic_app_id Identificatore univoco per l'agente (ID app dell'agente).
auth Contesto di autorizzazione per l'utente.
context Contesto del turno di conversazione corrente dall'SDK Agents. Fornisce l'identità dell'utente, i metadati della conversazione e il contesto di autenticazione per la registrazione sicura degli strumenti.
auth_token (Facoltativo) Token di connessione per scenari di autenticazione senza agenti.

4. Chiama durante l'inizializzazione

Assicurati di chiamare il metodo di installazione durante l'inizializzazione prima di eseguire l'agente:

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

Il metodo add_tool_servers_to_agent automaticamente:

  • Carica tutti i server MCP dal ToolingManifest.json
  • Registra gli strumenti con l'agente OpenAI
  • Configura l'autenticazione in base alla configurazione del manifesto
  • Rende disponibili gli strumenti che l'agente può richiamare

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

Testare e monitorare

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 Chiamate agli strumenti di test per verificare che gli strumenti MCP funzionino come previsto.

Aggiungere osservabilità

Aggiungi osservabilità all'agente per monitorare e tracciare le chiamate agli strumenti MCP dell'agente, aggiungere funzionalità di osservabilità per tenere traccia delle prestazioni, eseguire il debug dei problemi e comprendere i modelli di utilizzo degli strumenti. Altre informazioni sull'implementazione della traccia e del monitoraggio

  • Last updated on