Testar agentes através de Túneis de Desenvolvimento

Ao utilizar Túneis de Desenvolvimento, pode testar o seu agente do Agent 365 com aplicações do Microsoft 365 (como Teams, Outlook ou Word) enquanto o seu agente é executado localmente no seu computador de desenvolvimento. Esta abordagem faz a ponte entre o desenvolvimento local e os testes em ambientes reais, permitindo validar o comportamento do agente em ambientes Microsoft 365 antes de o implementar na cloud.

Pré-requisitos

Antes de usar Túneis de Desenvolvimento, certifique-se de que instala a ferramenta de linha de comandos dos Túneis de Desenvolvimento.

Configurar os Túneis de Desenvolvimento

Configure um Túnel de Desenvolvimento para expor o ponto final local do seu agente aos serviços do Microsoft 365.

Criar e iniciar um túnel

  1. Inicie sessão no Túnel de Desenvolvimento:

    devtunnel user login

  2. Crie um túnel persistente:

    devtunnel create --allow-anonymous

    Este comando devolve um ID de túnel. Guarde este identificador para uso futuro.

  3. Configure a porta do túnel:

    Atribua a porta que o servidor do agente utiliza (normalmente 3978):

    devtunnel port create <tunnel-id> -p <port-number>

  4. Inicie o túnel:

    devtunnel host <tunnel-id>

    O comando mostra o URL do túnel (por exemplo, https://abc123xyz.devtunnels.ms:3978). Copie este URL para o próximo passo.

Sugestão

Utilize devtunnel list para ver todos os seus túneis e devtunnel delete <tunnel-id> para remover túneis de que já não necessita.

Configurar o ponto final de mensagens do agente

Registe o URL do seu Túnel de Desenvolvimento (por exemplo, https://abc123xyz.devtunnels.ms:3978/api/messages) como ponto final de mensagens do agente, para que o Microsoft 365 saiba para onde encaminhar as mensagens. Não se esqueça do sufixo /api/messages no ponto final.

Consulte Definir o ponto final de mensagens do agente

Testar com o Microsoft 365

Com o Túnel de Desenvolvimento ativo e o ponto final registado, teste o seu agente nas aplicações do Microsoft 365.

Testar no Microsoft Teams

  1. Inicie o seu agente local seguindo as instruções indicadas em Instalar dependências e iniciar o servidor da aplicação do agente.

  2. Verifique a conectividade do túnel:

    devtunnel list

    Verifique se o túnel mostra ligações ativas de anfitrião. A coluna "Ligações de anfitrião" deve mostrar um número superior a 0.

  3. Interaja com o seu agente no Teams:

    • Abra o Microsoft Teams (Web ou computador)
    • Na barra de pesquisa do Teams, pesquise o seu agente por nome ou e-mail
    • Inicie uma conversação com o agente
    • Envie uma mensagem e observe a resposta
    • Verifique a sua consola local para pedidos recebidos e atividade do agente

Testar notificações por e-mail

Se o seu agente estiver configurado para notificações por e-mail:

  1. Envie um e-mail para o endereço de e-mail do seu agente
  2. Coloque o seu agente em CC numa thread de e-mail
  3. Monitorize a sua consola local para o webhook de notificações
  4. Verifique se o seu agente processa e responde ao e-mail

Testar a integração do Word

Para agentes que respondem a comentários do Word:

  1. Abra um documento Word ao qual o seu agente tenha acesso.
  2. Adicione um comentário a mencionar o seu agente.
  3. Verifique se há uma notificação na sua consola local.
  4. Verifique se a resposta do seu agente aparece no Word.

Monitorizar a atividade do túnel

Os Túneis de Desenvolvimento fornecem inspeção de tráfego para ajudar a depurar problemas de ligação e compreender o fluxo de pedidos:

devtunnel show <tunnel-id>

Este comando apresenta:

  • Ligações ativas e detalhes das sessões.
  • Informações sobre pedidos e respostas.
  • Estatísticas de volume de tráfego.
  • Erros e avisos de ligação.

Também pode monitorizar a atividade do túnel em tempo real, observando a saída do comando devtunnel host.

Manter as ligações do túnel

Os Túneis de Desenvolvimento requerem que o processo devtunnel host esteja sempre em execução. Se a inatividade, problemas de rede ou o computador entrar em modo de suspensão fizerem a ligação falhar, terá de a reiniciar.

Verificar o estado do túnel

Verifique se o seu túnel está ativo:

devtunnel list

A saída mostra:

  • ID do túnel: Identificador do seu túnel
  • Ligações do Host: Número de ligações ativas (deve ser uma ou mais quando devtunnel host está em execução)
  • Portas: Portas configuradas
  • Expiração: Tempo de expiração do túnel

Se Ligações de anfitrião mostrar 0, o túnel existe mas não está atualmente alojado.

Reiniciar um túnel desligado

Se a sua ligação ao túnel falhar, reinicie-a usando o mesmo ID do túnel:

devtunnel host <tunnel-id>

O URL do túnel permanece o mesmo, por isso não é preciso alterar a configuração do ponto final de mensagens do agente.

Manter os túneis ativos durante o desenvolvimento

Para manter ligações estáveis:

  • Mantenha a janela do terminal aberta. - Não feche o terminal que está a executar o devtunnel host.
  • Evite que o computador entre em modo de suspensão. - Configure o seu sistema para permanecer ativo durante as sessões de teste.
  • Esteja atento a erros de ligação - Monitorize a saída do terminal devtunnel host para mensagens de interrupção da ligação.
  • Reiniciar após alterações de rede - Se mudar de rede ou se voltar a ligar à VPN, reinicie o túnel.

Sugestão

Se o túnel se desligar frequentemente, verifique as definições de rede e as regras da firewall para garantir que não estão a bloquear a ligação.

Limpar

Quando terminar os testes com os Túneis de Desenvolvimento:

Parar o túnel

Prima Ctrl+C no terminal onde está a ser executado devtunnel host para parar o túnel.

Este comando remove o URL do Túnel de Desenvolvimento do ponto final de mensagens do seu agente. Ao implementar para produção, configure o URL do ponto final alojado na cloud.

Nota

O túnel permanece disponível para utilização futura até que o elimine explicitamente usando devtunnel delete <tunnel-id>.

Limitações

Considere estas limitações ao testar com Túneis de Desenvolvimento:

  • Apenas para desenvolvimento: Use Túneis de Desenvolvimento para desenvolvimento e testes, não para produção.
  • Desempenho: Espere uma latência mais elevada em comparação com agentes alojados na cloud devido ao encaminhamento da rede.
  • Estabilidade da ligação: As ligações do túnel podem ocasionalmente falhar e exigir reinício manual.
  • Considerações de segurança: O sinalizador --allow-anonymous é conveniente para testes, mas não o utilize com dados confidenciais.
  • Gestão de sessões: Pode ser necessário voltar a autenticar-se periodicamente, dependendo da duração da sessão.

Passos seguintes

Após testes bem-sucedidos com o Túnel de Desenvolvimento:

Resolução de Problemas

Se estiver a encontrar problemas ao testar através de Túneis de Desenvolvimento, consulte esta secção para obter correções comuns de túnel, conectividade e pontos finais. Para uma resolução de problemas mais abrangente no Agent 365 (configuração, autenticação e mensagens), consulte Resolução de Problemas.

Falha na ligação ao túnel

Sintomas: O Túnel de Desenvolvimento não inicia ou desliga-se imediatamente.

Soluções:

  • Verifique se iniciou sessão: devtunnel user login
  • Verifique se outro processo está a usar a mesma porta
  • Certifique-se de que a seu firewall permite ligações ao Túnel de Desenvolvimento
  • Elimine e volte a criar o túnel: devtunnel delete <tunnel-id> depois crie um novo

As mensagens não chegam ao agente local

Sintomas: O Microsoft 365 indica que a mensagem foi enviada, mas o seu agente local não a recebe.

Soluções:

  • Confirme que o seu agente está em execução localmente
  • Verifique se o túnel está ativo: devtunnel list deve mostrar "Ligado"
  • Verifique a configuração do ponto final em a365.config.json e verifique se o URL do Túnel de Desenvolvimento está definido como ponto final de mensagens
  • Reveja os registos do Túnel de Desenvolvimento no terminal que está a executar devtunnel host para identificar erros de ligação
  • Certifique-se de que a porta local corresponde à porta do túnel (ambas devem ser 3978 por predefinição)

Erros de autenticação através do Túnel de Desenvolvimento

Sintomas: erros 401 ou 403 ao testar através do Túnel de Desenvolvimento.

Soluções:

  • Verifique se a autenticação por meio de agentes está configurada (a autenticação por token de portador não funciona com os Túneis de Desenvolvimento para integração com Microsoft 365).
  • Verifique as credenciais do esquema do agente em a365.generated.config.json.
  • Confirme que o seu agente tem as permissões necessárias para as operações que está a testar.
  • Certifique-se de que os seus tokens de autenticação não expiraram.

URL do túnel alterado ou expirado

Sintomas: O URL do túnel que funcionava anteriormente já não faz o encaminhamento para o seu agente.

Soluções:

  • Verifique o estado do túnel usando devtunnel list.
  • Reinicie o túnel usando devtunnel host <tunnel-id>.
  • Atualize o ponto final de mensagens caso o URL tenha sido alterada usando a365 setup blueprint --endpoint-only.
  • Last updated on