Testar agentes usando Túneis do Desenvolvedor

Ao usar Túneis do Desenvolvedor, você pode testar seu agente do Agent 365 com aplicativos do Microsoft 365 (como Teams, Outlook ou Word) enquanto seu agente executa localmente em seu computador de desenvolvimento. Essa abordagem conecta o desenvolvimento local e os testes em ambientes reais do Microsoft 365, permitindo validar o comportamento do agente antes de implantá-lo na nuvem.

Pré-requisitos

Antes de usar os Túneis do Desenvolvedor, certifique-se de instalar a Ferramenta de linha de comando de Túneis do Desenvolvedor.

• Windows: winget install Microsoft.devtunnel
• macOS/Linux: baixe em aka.ms/devtunnels/download

Configurar o Túnel do Desenvolvedor

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

Crie e inicie um túnel

1. Entre no Túnel do Desenvolvedor:

   devtunnel user login
   

2. Crie um túnel persistente:

   devtunnel create --allow-anonymous
   

   Este comando retorna uma ID de túnel. Salve este identificador para uso futuro.

3. Configure a porta do túnel:

   Configure a porta que seu servidor do agente usa (normalmente 3978):

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

4. Inicie o túnel:

   devtunnel host <tunnel-id>
   

   O comando exibe a URL do seu túnel (por exemplo, https://abc123xyz.devtunnels.ms:3978). Copie esta URL para a próxima etapa.

Configurar o ponto de extremidade de mensagens do agente

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

Consulte Definir o ponto de extremidade do sistema de mensagens do agente

Teste com o Microsoft 365

Com o Túnel do Desenvolvedor ativo e o ponto de extremidade registrado, teste o agente em aplicativos do Microsoft 365.

Teste no Microsoft Teams

1. Inicie seu agente local usando as instruções em Instale as dependências e inicie o servidor do aplicativo do agente.

2. Verifique a conectividade do túnel:

   devtunnel list
   

   Verifique se seu túnel mostra conexões de host ativas. A coluna "Conexões de Host" deve mostrar um número maior que 0.

3. Interaja com seu agente no Teams:

   • Abra o Microsoft Teams (Web ou área de trabalho)
   • Na barra de pesquisa do Teams, pesquise seu agente por nome ou email
   • Iniciar uma conversa com o agente
   • Envie uma mensagem e observe a resposta
   • Verifique seu console local para solicitações recebidas e atividade do agente

Teste as notificações por email

Se seu agente estiver configurado para notificações por email:

1. Envie um email para o endereço de email do seu agente
2. Coloque o agente em cópia em um thread de email
3. Monitore o console local para obter o webhook da notificação
4. Verifique se seu agente processa e responde ao email

Testar a integração do Word

Para agentes que respondem aos comentários do Word:

1. Abra um documento no Word onde seu agente tenha acesso.
2. Adicione um comentário mencionando seu agente.
3. Verifique o console local para obter a notificação.
4. Verifique se a resposta do seu agente aparece no Word.

Monitorar a atividade do túnel

Os Túneis do Desenvolvedor oferecem inspeção de tráfego para ajudar a depurar problemas de conexão e entender o fluxo da solicitação:

devtunnel show <tunnel-id>

Este comando exibe:

• Conexões ativas e detalhes das sessões.
• Informações de requisição e resposta.
• Estatísticas de volume de tráfego.
• Erros e avisos da conexão.

Você também pode monitorar a atividade do túnel em tempo real observando a saída do comando devtunnel host.

Manter conexões do túnel

Os Túneis do Desenvolvedor exigem que o processo devtunnel host permaneça em execução. Se a inatividade, problemas de rede ou o computador entrar em modo de suspensão fizerem a conexão cair, você precisará reiniciar o processo do túnel.

Verifique o status do túnel

Verifique se seu túnel está ativo:

devtunnel list

A saída exibe:

• ID do túnel: seu identificador do túnel
• Conexões do Host: número de conexões ativas (deve ser uma ou mais quando devtunnel host estiver em execução)
• Portas: portas configuradas
• Expiração: tempo de expiração do túnel

Se Conexões do Host mostrar 0, o túnel existe, mas não está hospedado no momento.

Reiniciar um túnel desconectado

Se a conexão do túnel for interrompida, reinicie-a usando a mesma ID do túnel:

devtunnel host <tunnel-id>

A URL do túnel permanece a mesma, então você não precisa atualizar a configuração do ponto de extremidade de mensagens do agente.

Mantenha os túneis ativos durante o desenvolvimento

Para manter as conexões estáveis:

• Mantenha a janela do terminal aberta - Não feche o terminal que está executando devtunnel host.
• Evite que o computador entre em modo de suspensão - configure seu sistema para permanecer ativo durante as sessões de teste.
• Observe erros de conexão - Monitore a saída do terminal devtunnel host para obter mensagens de desconexão.
• Reinicie após alterações na rede - Se você mudar de rede ou reconectar-se à VPN, reinicie o túnel.

Limpar

Ao finalizar os testes com os Túneis do Desenvolvedor:

Interrompa o túnel

Pressione Ctrl+C no terminal em funcionamento devtunnel host a fim de interromper o túnel.

Este comando remove a URL do Túnel do Desenvolvedor do ponto de extremidade do sistema de mensagens do seu agente. Quando você implantar em produção, defina a URL do ponto de extremidade hospedado na nuvem.

Limitações

Considere estas limitações ao testar com Túneis do Desenvolvedor:

• Apenas para desenvolvimento: use os Túneis do Desenvolvedor para desenvolvimento e testes, não para produção.
• Desempenho: espere uma latência mais alta em comparação com agentes hospedados na nuvem devido ao roteamento de rede.
• Estabilidade da conexão: as conexões do túnel podem ocasionalmente cair e exigir reinicialização manual.
• Considerações de segurança: a marca --allow-anonymous é conveniente para testes, mas não a use com dados confidenciais.
• Gerenciamento da sessão: você pode precisar reautenticar periodicamente dependendo da duração da sessão.

Próximas etapas

Após testes bem-sucedidos no Túnel do Desenvolvedor:

• Implante seu agente na nuvem: Implantar no Azure, Definir o ponto de extremidade do sistema de mensagens do agente na AWS, ou Definir o ponto de extremidade do sistema de mensagens do agente do GCP.
• Configurar pontos de extremidade do sistema de mensagens de agente: ponto de extremidade do sistema de mensagens do agente.
• Siga o ciclo de vida de desenvolvimento completo: Ciclo de Vida de Desenvolvimento do Agent 365.

Solução de Problemas

Se você estiver enfrentando problemas durante os testes por meio do túnel do desenvolvedor, comece por aqui para soluções comuns de túnel, conectividade e ponto de extremidade. Para uma solução de problemas mais abrangente do Agent 365 (configuração, autenticação e mensagens), consulte Solução de Problemas.

Falha na conexão do túnel

Sintomas: o Túnel do Desenvolvedor não inicia ou se desconecta imediatamente.

Soluções:

• Verifique se você está conectado: devtunnel user login
• Verifique se outro processo está usando a mesma porta
• Certifique-se de que seu firewall permita conexões do Túnel do Desenvolvedor
• Exclua e recrie o túnel: devtunnel delete <tunnel-id> depois crie um novo

Mensagens não são entregues ao agente local

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

Soluções:

• Confirme que seu agente está em execução localmente
• Certifique-se de que o túnel está ativo: devtunnel list deve exibir "Conectado"
• Verifique a configuração do ponto de extremidade em a365.config.json e verifique se a URL do Túnel de Desenvolvimento está definida como o ponto de extremidade de mensagens
• Verifique os logs do Túnel do Desenvolvedor no terminal onde está sendo executado o devtunnel host para obter erros de conexão
• Certifique-se de que sua porta local corresponde à porta do túnel (ambas devem ser 3978 por padrão)

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

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

Soluções:

• Verifique se a autenticação de agente está configurada (a autenticação de token de portador não funciona com o Túnel do Desenvolvedor para a integração com o Microsoft 365).
• Verifique as credenciais de blueprint do agente em a365.generated.config.json.
• Confirme que seu agente tem as permissões necessárias para as operações que você está testando.
• Certifique-se de que seus tokens de autenticação não expiraram.

URL do túnel alterada ou expirada

Sintomas: a URL do túnel que estava funcionando anteriormente deixa de ser encaminhada para o agente.

Soluções:

• Verifique o status do túnel usando devtunnel list.
• Reinicie o túnel usando devtunnel host <tunnel-id>.
• Atualize o ponto de extremidade do sistema de mensagem se a URL tiver sido alterada usando a365 setup blueprint --endpoint-only.