Implementar agentes no Microsoft Teams

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

Este artigo fornece orientações para implementar eficazmente os agentes do Copilot Studio no Teams. O Utilizador aprende a gerir sessões persistentes, a implementar estratégias de depuração e a garantir um desempenho fiável ao longo dos ciclos de vida prolongados das conversas.

Principais considerações abordadas:

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

Siga estas práticas para criar agentes robustos que funcionem de forma consistente no ambiente do Teams, fornecendo comentários claros aos utilizadores sobre alterações de estado e comportamento do sistema.

Porque é que a implementação do Teams é diferente

As conversas do Teams mantêm-se ao longo dos dias sem reposição automática. Ao contrário das sessões de Webchat, o evento ConversationStart só é ativado na primeira vez que um agente é adicionado. Reinstalar a aplicação não volta a acionar este evento.

A persistência do Teams cria vários riscos:

• Contexto obsoleto: O histórico de conversações mantém-se, a menos que seja limpo.
• Expiração do token: Os conectores podem expirar durante sessões longas.
• Limites de contexto: as mensagens acumuladas podem exceder os limites do modelo.
• Atualização de cache: Os utilizadores podem continuar a interagir com lógica desatualizada.

Uma gestão proativa do estado e uma orientação clara para o utilizador são essenciais.

Gerir o ciclo de vida da sessão

Gerir o ciclo de vida da sessão com processamento da inatividade.

Implementar reposições de inatividade

Crie um novo tópico e selecione o acionador O utilizador está inativo há algum tempo para iniciar um fluxo de reposição após um período de inatividade do utilizador. Saiba mais em Acionador de inatividade sobre padrões específicos do Teams, incluindo variáveis de proteção e o modelo de conversação persistente.

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

Esta abordagem previne o excesso de contexto e garante um comportamento previsível quando um utilizador regressa.

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

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

Como ConversationStart dispara apenas uma vez, na primeira vez que um agente é adicionado, o tópico Saudação torna-se o seu ponto de inicialização principal. Pedir ao utilizador para dizer "olá" garante que a lógica de arranque é executada corretamente.

Oferecer um comando de reposição de gestão personalizada

Adicione uma mensagem a informar os utilizadores de que podem escrever um comando específico: "Se algo parecer errado, experimente escrever /debug clearstate para atualizar o meu estado."

Este comando força uma reposição completa da conversa:

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

Utilize este comando quando:

• O bot parece "bloqueado" com informações desatualizadas
• A autenticação do conector expirou
• Após atualizações da 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 dos agentes implementados no Teams, utilize o acionador OnKnowledgeRequested.

Utilize o OnKnowledgeRequested para revelar as consultas reescritas

O Copilot Studio reescreve as perguntas dos utilizadores antes de realizar a obtenção. Se ativar o acionador OnKnowledgeRequested, pode:

• Diagnosticar erros de correspondência de intenção
• Compreender como as consultas são reescritas
• Aumentar a confiança dos utilizadores 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: {}

Esta consulta proporciona acesso só de leitura à consulta de pesquisa refinada (reescrita de consulta) que o orquestrador gerou a partir da pergunta do utilizador.

Benefícios:

• Ajuda a depurar erros de correspondência de intenção.
• Mostra aos utilizadores o que o agente consulta.
• Promove a confiança nas ações do agente.
• Auxilia os criadores durante os testes.

Controlo de versões e fiabilidade das atualizações

Gerir as versões dos agentes e garantir que os utilizadores interagem com a lógica mais recente é especialmente importante num ambiente persistente como o Teams.

Mostrar a versão do bot numa saudação ou tópico dedicado

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

Contoso Helpdesk Bot – Version 1.3 (Nov 2025)

Atualize este valor a cada publicação para ajudar os utilizadores e as equipas de suporte a verificar qual a compilação ativa. A atualização dos metadados da versão também atualiza o conteúdo em cache. Alterar o nome ou a descrição do agente pede ao Teams que o carregue como uma nova atualização.

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

A definiçã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 utilizador enviar uma mensagem. Esta definição também ajuda a invalidar versões em cache. No entanto, forçar uma atualização interrompe qualquer conversa em curso.

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

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

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

Dado que ConversationStart só é acionado uma vez, na primeira vez que um agente é adicionado:

• Coloque a lógica de inicialização na Saudação.
• Adicione instruções claras na descrição da aplicação do Teams.
• Lembre os utilizadores: "Após um tempo limite, escreva 'olá' para iniciar uma nova conversa."

Otimizar acionadores e contingências

Os utilizadores do Teams interagem de forma natural e imprevisível. Certifique-se de que o seu bot:

• Processa várias variações de saudações.
• Inclui a gestão de despedidas.
• Fornece várias expressões de exemplo.
• Oferece respostas de contingência amigáveis e úteis.
• Utiliza palavras-chave para guiar os utilizadores para tópicos relevantes.
• Utiliza o OnKnowledgeRequested para ajudar a diagnosticar intenções em falta.
• Redireciona para tópicos relevantes com base em palavras-chave.
• Pede aos utilizadores que reformulem se o bot estiver realmente bloqueado.

Valide o comportamento de autenticação do conector

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

• Como se comporta o cartão de início de sessão inicial.
• O que acontece quando o token expira e como é automaticamente renovado.
• Como funcionam os fluxos de invalidação forçada e de reconsentimento.

Testar em condições reais

Como o Teams retém o estado entre sessões, os seus testes devem refletir a experiência real do utilizador:

1. Implemente através de Mostrar só para mim.
2. Teste cenários de execução prolongada (regressando após várias horas).
3. Publique atualizações e confirme que o agente passa para a versão mais recente.
4. Valide a composição dos Cartões Adaptativos em computadores e dispositivos móveis.
5. Teste ações em contextos conversacionais variados.

Lista de verificação de implementação

Principais conclusões

• Faça a gestão do ciclo de vida da sessão configurando os acionadores de inatividade e utilizando opções de limpeza de estado quando apropriado.
• Melhore a transparência ao revelar a atividade do sistema através de reescritas de consultas e mensagens relacionadas com o estado.
• Considere comportamentos específicos do Teams, como processar saudações manuais e gerir memória persistente.
• Mantenha a fiabilidade do agente implementando práticas de controlo de versões e impondo atualizações quando necessário.
• Suporte a autonomia do utilizador, disponibilizando comandos de resolução de problemas de self‑service e opções de recuperação guiada.

Informações relacionadas

• Ligar e configurar um agente para o Teams e o Microsoft 365
• Conceitos principais - Publicar e implementar o seu agente