Esegui il debug dei plug-in MCP e API in locale

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

I plug-in consentono agli agenti dichiarativi in Microsoft 365 Copilot di chiamare server MCP (Model Context Protocol) o API REST per recuperare dati ed eseguire attività. Microsoft 365 Copilot deve raggiungere il server MCP o API tramite Internet. In genere, gli strumenti di debug ospitano sessioni di debug su localhost (127.0.0.1), accessibile solo dal computer che esegue lo strumento di debug. Utilizzando un proxy inverso, ad esempio i tunnel dev, è possibile esporre la sessione di debug a Internet per abilitare le chiamate di debug da Microsoft 365 Copilot.

In questo articolo viene illustrato come usare lo strumento per abilitare il debug locale per il server o l'API devtunnel MCP.

Nota

Gli strumenti di debug potrebbero già fornire una soluzione di proxy inverso. Per verificare, ti consigliamo di controllare la documentazione degli strumenti di sviluppo. Ad esempio, se hai creato una nuova API utilizzando Microsoft 365 Agents Toolkit, il toolkit gestisce automaticamente la configurazione del proxy inverso.

Prerequisiti

  • L'interfaccia devtunnel della riga di comando installata nel computer in cui si ospitano le sessioni di debug
  • Il numero di porta HTTP usato dallo strumento di debug

Creare un tunnel di sviluppo permanente

L'interfaccia devtunnel della riga di comando consente di creare un tunnel di sviluppo persistente, ovvero un tunnel che è possibile arrestare e avviare in base alle esigenze senza che l'URL ospitato venga modificato. L'uso di un tunnel con un URL persistente semplifica il debug dei plug-in perché non è necessario aggiornare i pacchetti dell'app agente dichiarativo con nuovi URL.

  1. Se non è già stato eseguito l'accesso all'interfaccia della riga di comando di devtunnel, usare devtunnel user login --help per visualizzare le opzioni disponibili. Accedere alla CLI prima di procedere.

  2. Crea il tunnel, consentendo l'accesso anonimo. L'accesso anonimo è necessario per consentire a Microsoft 365 Copilot di accedere al tunnel e non è correlato all'autenticazione richiesta dall'API.

    devtunnel create --allow-anonymous
    

    Suggerimento

    La creazione di un nuovo tunnel commuta il tunnel predefinito in quello appena creato. In questo modo è possibile omettere l'argomento tunnel-id nei comandi successivi. Se si creano più tunnel, potrebbe essere necessario usare l'argomento tunnel-id per assicurarsi di usare il tunnel previsto. Per altre informazioni, usare il devtunnel --help comando o vedere Informazioni di riferimento sulla riga di comando per i tunnel di sviluppo.

  3. Aggiungere il numero di porta HTTP usato dallo strumento di debug. Sostituiscila <port> con il numero di porta e imposta il --protocol parametro se https lo strumento di debug utilizza HTTPS sulla porta o http se non utilizza HTTPS.

    devtunnel port create --port-number <port> --protocol https
    
  4. Avvia il tunnel di sviluppo.

    devtunnel host
    
  5. Per la prima volta che esegui questo tunnel di sviluppo, copia l'URL con etichetta Connetti tramite browser. Aprire questo URL nel browser e selezionare Continua per abilitare il tunnel.

    Nota

    Dopo aver selezionato Continua, il browser visualizzerà un errore. Questo è previsto e può essere ignorato.

Una volta abilitato il tunnel, è possibile arrestarlo con CTRL + C. Puoi riavviare il tunnel con il devtunnel host host-id comando.

Uso di Dev Tunnel

Per usare il tunnel di sviluppo per il debug, trasferire localmente un pacchetto di app con l'URL del tunnel di sviluppo al posto dell'URL del server.

Imposta la url proprietà dell'oggetto spec del server MCP all'interno del manifesto del plug-in.

"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "<your-dev-tunnel-url>",
    }
  }
]

Se utilizzi Agents Toolkit in Visual Studio Code per gestire il tuo agente dichiarativo, puoi aggiungere una variabile d'ambiente al file /env/.env.dev.user denominato PLUGIN_SERVER_URL e utilizzarla al posto dell'URL del tunnel di sviluppo. Usare il passaggio Provisioning nel riquadro Ciclo di vita per trasferire localmente l'agente. Nel file /env/.env.dev.user , aggiungi:

OPENAPI_SERVER_URL=<your-dev-tunnel-url>

Nel manifesto del plug-in aggiornare la url proprietà:

"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "${{PLUGIN_SERVER_URL}}",
    }
  }
]

Se non usi Agents Toolkit, puoi generare un nuovo file ZIP del pacchetto dell'app e caricare l'agente.