Testar agentes usando Dev Tunnels

Usando Dev Tunnels, você pode testar o agente do Agente 365 com aplicativos Microsoft 365 (como Teams, Outlook ou Word) enquanto seu agente é executado localmente em seu computador de desenvolvimento. Essa abordagem conecta o desenvolvimento local e os testes do mundo real, para que você possa validar o comportamento do agente em ambientes reais Microsoft 365 antes de implantar na nuvem.

Pré-requisitos

Antes de usar Dev Tunnels, certifique-se de instalar a ferramenta de linha de comando Dev Tunnels.

• Windows: winget install Microsoft.devtunnel
• macOS/Linux: Baixar de aka.ms/devtunnels/download

Configurar o Dev Tunnel

Configure um Túnel Dev para expor o endpoint do agente local aos serviços do Microsoft 365.

Crie e inicie um túnel

1. Faça login no Dev Tunnel:

   devtunnel user login
   

2. Crie um túnel persistente:

   devtunnel create --allow-anonymous
   

   Esse comando retorna um ID de túnel. Salve esse identificador para uso futuro.

3. Configure a porta do túnel:

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

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

4. Comece 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 o próximo passo.

Configurar o endpoint de mensagens do agente

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

Consulte Definir o endpoint de mensagens do agente

Testar com Microsoft 365

Com o Túnel de Desenvolvimento ativo e o ponto de extremidade registrado, teste o agente nos aplicativos Microsoft 365.

Testar em Microsoft Teams

1. Inicie seu agente local usando as instruções em Dependências de Instalação e inicie o servidor de aplicações agente.

2. Verifique a conectividade do túnel:

   devtunnel list
   

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

3. Interaja com seu agente no Teams:

   • Abrir Microsoft Teams (Web ou desktop)
   • Na barra de busca do Teams, pesquise seu agente por nome ou e-mail
   • Comece uma conversa com o agente
   • Envie uma mensagem e observe a resposta
   • Verifique seu console local para solicitações recebidas e atividade de agentes

Notificações de e-mail de teste

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

1. Envie um e-mail para o endereço do seu corretor
2. Coloque seu agente em cópia em uma conversa de e-mails
3. Monitore seu console local para o webhook de notificação
4. Verifique se seu agente processa e responde ao e-mail

Testar a integração do Word

Para agentes que respondem a comentários Word:

1. Abra um documento Word em que o agente tenha acesso.
2. Adicione um comentário mencionando seu corretor.
3. Verifique sua consola local para a notificação.
4. Verifique se a resposta do agente aparece no Word.

Monitorar a atividade do túnel

O Dev Tunnels oferece inspeção de tráfego para ajudar a depurar problemas de conexão e entender o fluxo de requisições:

devtunnel show <tunnel-id>

Este comando exibe:

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

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

Manter as conexões do túnel

Dev Tunnels exigem que o processo devtunnel host continue em execução. Se a inatividade, problemas de rede ou seu computador entrar em modo de suspensão fizer a conexão cair, você precisa reiniciá-lo.

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 de 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 Host Connections mostrar 0, o túnel existe, mas não está atualmente hospedado.

Reiniciar um túnel desconectado

Se sua conexão do túnel cair, reinicie-a usando o mesmo 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 endpoint de mensagens do agente.

Mantenha os túneis ativos durante o desenvolvimento

Para manter conexões estáveis:

• Mantenha a janela do terminal aberta - Não feche o terminal em funcionamento devtunnel host.
• Evite o sono do computador - Configure seu sistema para ficar acordado durante as sessões de teste.
• Fique atento a erros de conexão - Monitore a saída do devtunnel host terminal para mensagens de desconexão.
• Reiniciar após mudanças na rede - Se você mudar de rede ou reconectar para VPN, reinicie o túnel.

Limpeza

Quando você terminar de testar com os Dev Tunnels:

Pare o túnel

Pressione Ctrl+C no terminal que está executando devtunnel host para parar o túnel.

Esse comando remove a URL do Dev Tunnel do endpoint de mensagens do seu agente. Quando você implementar em produção, configure a URL do endpoint na nuvem.

Limitações

Considere estas limitações ao testar com Dev Tunnels:

• Apenas desenvolvimento: Use os Túneis de Desenvolvimento para desenvolvimento e testes, não para produção.
• Desempenho: Espere uma latência maior em comparação com agentes hospedados na nuvem devido ao roteamento de rede.
• Estabilidade da conexão: Conexões de túnel podem ocasionalmente cair e exigir reinício manual.
• Considerações de segurança: A --allow-anonymous flag é conveniente para testes, mas não a use com dados sensíveis.
• Gerenciamento de sessões: Você pode precisar reautenticar periodicamente dependendo da duração da sessão.

Próximas etapas

Após testes bem-sucedidos no Dev Tunnel:

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

Solucionando problemas

Se você estiver enfrentando problemas durante os testes através dos Dev Tunnels, comece por aqui para soluções comuns de túnel, conectividade e endpoints. Para uma solução de problemas mais ampla do Agent 365 (configuração, autenticação e mensagens), veja Solução de Problemas.

Falha na conexão do túnel

Sintomas: O Túnel de Desenvolvimento não inicia ou desconecta imediatamente.

Soluções:

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

Mensagens não chegam ao agente local

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

Soluções:

• Confirme que seu agente está atuando localmente
• Verifique se o túnel está ativo: devtunnel list deve mostrar "Conectado"
• Verifique a configuração a365.config.json do ponto de extremidade e verifique se a URL do Túnel de Desenvolvimento está definida como o ponto de extremidade de mensagens
• Revise os logs do Dev Tunnel no terminal em execução devtunnel host para 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 Dev Tunnel

Sintomas: erros 401 ou 403 ao testar pelo Dev Tunnel.

Soluções:

• Verifique se a autenticação baseada em agente está configurada (a autenticação por token de portador não funciona com o Dev Tunnels na integração com o Microsoft 365).
• Verifique as credenciais de arquétipo 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 funcionava anteriormente não redireciona mais para o seu agente.

Soluções:

• Verifique o status do túnel usando devtunnel list.
• Reinicie o túnel usando devtunnel host <tunnel-id>.
• Atualize o endpoint de mensagens caso a URL tenha mudado usando a365 setup blueprint --endpoint-only --m365.