Depurar plug-ins MCP e API localmente

Dica

Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.

Os plug-ins permitem que agentes declarativos no Microsoft 365 Copilot chamem servidores MCP (Model Context Protocol) ou APIs REST para recuperar dados e executar tarefas. Microsoft 365 Copilot deve alcançar o servidor MCP ou API pela Internet. Normalmente, as ferramentas de depuração hospedam sessões de depuração no localhost (127.0.0.1), que só é acessível a partir da máquina que executa a ferramenta de depuração. Usando um proxy reverso, como túnel do desenvolvedor, você pode expor sua sessão de depuração à Internet para habilitar chamadas de depuração do Microsoft 365 Copilot.

Este artigo mostra como usar a ferramenta para habilitar a devtunnel depuração local para seu servidor MCP ou API.

Observação

Suas ferramentas de depuração já podem fornecer uma solução de proxy reverso. Recomendamos que consulte a documentação das suas ferramentas de programador para confirmar. Por exemplo, se você criou uma nova API usando o Microsoft 365 Agents Toolkit, o kit de ferramentas lida com a configuração do proxy reverso para você.

Pré-requisitos

  • A devtunnel CLI instalada no computador onde você hospeda suas sessões de depuração
  • O número da porta HTTP usada pela ferramenta de depuração

Criar um túnel de desenvolvimento persistente

A devtunnel CLI permite que você crie um túnel de desenvolvimento persistente - um túnel que você pode parar e iniciar conforme necessário sem que a URL hospedada seja alterada. O uso de um túnel com uma URL persistente simplifica a depuração de plug-ins, já que você não precisa atualizar seus pacotes de aplicativos de agente declarativo com novas URLs.

  1. Se você ainda não estiver conectado à CLI devtunnel, use devtunnel user login --help para ver as opções disponíveis. Faça login na CLI antes de prosseguir.

  2. Crie o túnel, permitindo o acesso anónimo. O acesso anónimo é necessário para permitir que Microsoft 365 Copilot acedam ao seu túnel e não está relacionado com qualquer autenticação exigida pela sua API.

    devtunnel create --allow-anonymous
    

    Dica

    Criar um novo túnel muda o túnel padrão para o recém-criado. Isto permite-lhe omitir o tunnel-id argumento para comandos subsequentes. Se criar vários túneis, pode ter de utilizar o tunnel-id argumento para garantir que está a utilizar o túnel esperado. Para obter mais informações, use o devtunnel --help comando ou consulte Dev tunnels command-line reference.

  3. Adicione o número da porta HTTP usada pela ferramenta de depuração. Substitua <port> pelo número da porta e defina o --protocol parâmetro se https a ferramenta de depuração estiver usando HTTPS na porta ou http se não estiver usando HTTPS.

    devtunnel port create --port-number <port> --protocol https
    
  4. Inicie o túnel de desenvolvimento.

    devtunnel host
    
  5. Pela primeira vez executando este túnel de desenvolvimento, copie a URL rotulada Conectar via navegador. Abra este URL no seu navegador e selecione Continuar para ativar o túnel.

    Observação

    Depois de selecionar Continuar, seu navegador exibirá um erro. Isto é esperado e pode ser ignorado.

Assim que o túnel estiver ativado, pode parar o túnel com CTRL + C. Você pode reiniciar o túnel com o devtunnel host host-id comando.

Usando o túnel de desenvolvimento

Para usar seu túnel de desenvolvimento para depuração, faça o sideload de um pacote de aplicativo com a URL do túnel de desenvolvimento no lugar da URL do servidor.

Defina a propriedade do objeto de especificação do servidor MCP dentro do manifesto url do plug-in.

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

Se você estiver usando o Agents Toolkit no Visual Studio Code para gerenciar seu agente declarativo, poderá adicionar uma variável de ambiente ao arquivo /env/.env.dev.user chamada PLUGIN_SERVER_URL e usá-la no lugar da URL do túnel de desenvolvimento. Use a etapa Provisionar no painel Ciclo de vida para fazer sideload do agente. No seu ficheiro /env/.env.dev.user , adicione:

OPENAPI_SERVER_URL=<your-dev-tunnel-url>

No manifesto do plug-in, atualize a url propriedade:

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

Se não estiver a utilizar o Agents Toolkit, pode gerar um novo ficheiro ZIP do pacote de aplicações e carregar o seu agente.