Implantar agentes no Microsoft Teams

O Microsoft Teams apresenta desafios únicos de implantação para agentes do Copilot Studio devido ao seu ambiente de conversa persistente. Ao contrário das implantações baseadas na Web, onde as sessões são reiniciadas automaticamente, o Teams mantém as conversas indefinidamente, o que pode levar a contexto obsoleto, expiração de tokens e conteúdo em cache desatualizado.

Este artigo fornece orientações para implantar agentes do Copilot Studio no Teams de forma eficaz. Você aprende a gerenciar sessões persistentes, implementar estratégias de depuração e garantir desempenho confiável ao longo dos ciclos de vida prolongados das conversas.

Principais considerações abordadas:

• Gerenciamento do ciclo de vida da sessão e tratamento da inatividade
• Técnicas de depuração para conversas persistentes
• Controle de versões e estratégias de implantação de atualizações
• Padrões de implementação específicos do Teams

Siga essas práticas para criar agentes avançados que atuem de forma consistente no ambiente do Teams, fornecendo feedback claro aos usuários sobre alterações de estado e comportamento do sistema.

Por que a implantação no Teams é diferente

As conversas do Teams persistem por vários dias sem reinício automático. Ao contrário das sessões de Webchat, o evento ConversationStart é disparado apenas na primeira vez que um agente é adicionado. Reinstalar o aplicativo não dispara esse evento novamente.

A persistência das conversas no Teams gera diversos riscos:

• Contexto obsoleto: o histórico da conversa permanece até ser eliminado.
• Expiração do token: os conectores podem expirar durante sessões longas.
• Limites de contexto: as mensagens acumuladas podem exceder os limites do modelo.
• Cache de atualizações: os usuários podem continuar interagindo com lógica desatualizada.

Gerenciamento proativo do estado e orientação clara para o usuário são essenciais.

Gerenciar o ciclo de vida da sessão

Gerencie o ciclo de vida da sessão com o tratamento da inatividade.

Implementar redefinições de inatividade

Crie um novo tópico e selecione o gatilho O usuário está inativo por um tempo para iniciar um fluxo de redefinição após um período de inatividade do usuário. Saiba mais no gatilho de inatividade sobre padrões específicos do Teams, incluindo variáveis de proteção e o modelo de conversa persistente.

1. Adicione o gatilho de inatividade e defina um tempo limite (por exemplo, 15 minutos).
2. Adicione um ou mais nós de Limpar valores de variáveis para remover variáveis de sessão e histórico de conversa e evitar estouro de contexto.
3. Encerre a conversa e marque a sessão como resolvida.

Essa abordagem evita o excesso de contexto e garante um comportamento previsível quando o usuário retorna.

Forneça orientação após a reinicialização

Depois de limpar o estado, envie uma mensagem explicando o que aconteceu. Por exemplo: "Parece que nossa conversa ficou ociosa, então estou limpando o contexto anterior por segurança. Diga 'olá' para reiniciar."

Como ConversationStart só é acionado uma vez, na primeira vez que um agente é adicionado, o tópico Saudação se torna seu ponto principal de inicialização. Solicitar que o usuário diga "olá" garante que sua lógica de inicialização seja executada corretamente.

Oferecer um comando de redefinição de autoatendimento

Adicione uma mensagem informando aos usuários que eles podem digitar um comando específico: “Se algo parecer errado, tente digitar /debug clearstate para atualizar meu estado.”

Esse comando força uma reinicialização completa da conversa:

• Limpa o estado da conversa
• Remove informações do conector em cache
• Reautentique os conectores
• Carrega a versão mais recente do agente

Usa este comando quando:

• O bot parece estar usando informações desatualizadas
• A autenticação do conector expirou
• Após atualizações na lógica do bot
• Quando o comportamento parece inconsistente

Aumentar a transparência e melhorar a depuração

Para aumentar a transparência e melhorar a depuração de agentes implantados no Teams, use o disparador OnKnowledgeRequested.

Utilize OnKnowledgeRequested para revelar consultas reescritas

O Copilot Studio reescreve as perguntas dos usuários antes de realizar a recuperação. Se você ativar o gatilho OnKnowledgeRequested, você pode:

• Diagnosticar incompatibilidades de intenção
• Entender como as consultas são reescritas
• Aumentar a confiança dos usuários durante a depuração

Adicione uma mensagem que mostre tanto as consultas por palavra-chave quanto as consultas semânticas geradas. Por exemplo:

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  actions:
    - kind: SendActivity
      id: sendActivity_debug
      activity: |-    
        **Debug**: sending this lexical query "{System.KnowledgeSearchQuery}"
        **Debug**: sending this semantic query "{System.SearchQuery}"
inputType: {}
outputType: {}

Essa consulta fornece acesso de somente leitura à consulta de pesquisa refinada (reescrita de consulta) gerada pelo orquestrador a partir da consulta do usuário.

Benefícios:

• Ajuda a depurar incompatibilidades de intenção.
• Mostra aos usuários o que o agente consulta.
• Gera confiança nas ações do agente.
• Auxilia os criadores durante os testes.

Controle de versão e confiabilidade de atualizações

É especialmente importante gerenciar as versões dos agentes e garantir que os usuários interajam com a lógica mais recente em um ambiente persistente como o Teams.

Exibir a versão do bot na saudação ou em um tópico dedicado

Inclua um identificador de versão usando o tópico de Saudação ou um tópico dedicado de Versão:

Contoso Helpdesk Bot – Version 1.3 (Nov 2025)

Atualize esse valor a cada publicação para ajudar usuários e equipes de suporte a verificar qual compilação está ativa. Atualizar os metadados da versão também atualiza o conteúdo em cache. Alterar o nome ou a descrição do agente faz com que o Teams reconheça e carregue o agente como uma atualização.

Ative "Forçar a versão mais recente" ao publicar

A configuração Forçar a versão mais recente garante que o Teams carregue a lógica mais recente do agente na próxima vez que o usuário enviar uma mensagem. Essa configuração também ajuda a invalidar versões em cache. No entanto, forçar uma atualização interrompe qualquer conversa em andamento.

Considerações específicas de implementação do Teams

O Teams tem comportamentos exclusivos que exigem atenção especial.

Trate o tópico de Saudação como sua lógica de inicialização

Como ConversationStart só é acionado uma vez, a primeira vez que um agente é adicionado:

• Coloque a lógica de inicialização na Saudação.
• Adicione instruções claras na descrição do aplicativo do Teams.
• Lembre os usuários: “Após um período de inatividade, digite 'olá' para iniciar uma nova conversa.”

Otimize gatilhos e fallbacks

Os usuários do Teams interagem de forma natural e imprevisível. Certifique-se de que seu bot:

• Lida com diversas variações de saudação.
• Inclui tratamento de despedida.
• Fornece diversos exemplos de enunciados.
• Oferece respostas de fallback amigáveis e úteis.
• Usa palavras-chave para direcionar os usuários a tópicos relevantes.
• OnKnowledgeRequested é usado para ajudar a diagnosticar intenções perdidas.
• Redireciona para tópicos relevantes com base em palavras-chave.
• Solicita que os usuários reformulem a mensagem caso o bot esteja realmente travado.

Validar o comportamento de autenticação dos conectores

Ao usar conectores (ServiceNow, Outlook e outros), teste:

• Como o cartão inicial de entrada se comporta.
• O que acontece quando o token expira e como ele é renovado automaticamente.
• Como funcionam os fluxos de invalidação forçada e de novo consentimento.

Realize testes em condições reais

Como o Teams mantém o estado entre sessões, seus testes devem refletir a experiência real do usuário:

1. Implante usando Mostrar só para mim.
2. Teste cenários de longa duração (retornando após algumas horas).
3. Publique atualizações e confirme que o agente alterna para a nova versão.
4. Valide a renderização dos Cartões Adaptáveis tanto no desktop quanto no dispositivo móvel.
5. Teste ações em contextos conversacionais variados.

Lista de verificação de implantação

Principais conclusões

• Gerencie o ciclo de vida da sessão configurando gatilhos de inatividade e utilizando opções de limpeza de estado quando apropriado.
• Melhore a transparência ao exibir a atividade do sistema por meio de reescritas de consulta e mensagens relacionadas ao estado.
• Leve em conta comportamentos específicos do Teams, como lidar com saudações manuais e gerenciar memória persistente.
• Mantenha a confiabilidade dos agentes implementando práticas de controle de versão e aplicando atualizações quando necessário.
• Apoie a autonomia do usuário fornecendo comandos de solução de problemas de autoatendimento e opções de recuperação guiada.

Informações relacionadas

• Conectar e configurar um agente para o Teams e para o Microsoft 365
• Principais conceitos – Publicar e implantar o agente