Microsoft Teams

Conecte um bot do Microsoft Teams para iniciar e continuar sessões do Beeuni em chats e canais.

O Microsoft Teams é um canal: uma menção @ em um chat ou canal do Teams inicia uma sessão, e o agente responde ali mesmo com progresso em tempo real. Ele segue as mesmas regras de sessão, identidade e credenciais do Slack; esta página aborda o que é específico do Teams.

Todo projeto pode conectar o Teams. Não há nenhuma flag de recurso para ativar.

Conectar

Há duas formas, ambas na página Connectors → Channels do projeto:

• Um clique (gerenciado). Um administrador do tenant do Teams clica em Add to Teams, entra e consente. O Beeuni publica o app automaticamente no catálogo do Teams da sua organização — não há nada para criar ou colar. A linha então oferece Add to Teams (um link direto para o cliente do Teams) para que qualquer pessoa possa adicionar o bot a um chat ou canal. Quando o Beeuni lançar uma versão mais recente do app, consulte Atualizar o app.

• Traga seu próprio bot. Clique em Use your own Microsoft Teams app para abrir um assistente de três etapas: registre um Azure Bot, conecte-o ao Beeuni com o app id, client secret e tenant id, depois baixe o pacote de app gerado e faça upload dele no Teams. Use esta opção quando você gerenciar seu próprio registro de bot.

  A ordem é importante. O Beeuni cria o manifesto a partir do seu app id, portanto só pode gerar o pacote depois da etapa 2 — o assistente mostra o messaging endpoint para você colar no Azure antes de solicitar qualquer outra informação.

A CLI segue o dashboard:

beeuni channels connect --platform teams      # prints the admin-consent URL
beeuni channels status --platform teams        # tenant, catalog, publish state, app version
beeuni channels disconnect --platform teams

Atualizar o app

O Beeuni adiciona permissões ao app do Teams ao longo do tempo. A versão 1.1.0 do app adicionou ChannelMessage.Read.Group, de que o agente precisa para ler uma thread de canal. A versão 1.3.0 adicionou ChatMessage.Read.Chat, para que uma resposta em um chat em grupo continue uma sessão sem menção. Uma equipe que ainda esteja na versão 1.0.0 recusa toda leitura de thread, e a recusa recebida pelo agente informa quem deve corrigir isso.

Duas pessoas atualizam o app, nesta ordem:

1. Um administrador do Teams publica a atualização. Quando o catálogo da sua organização tem uma versão mais antiga, a página Channels mostra Update the Beeuni app in Teams, e o botão da linha do Teams exibe Publish app update. O administrador clica nele e entra com a conta da Microsoft. beeuni channels status --platform teams exibe as duas versões, e beeuni channels connect --platform teams exibe o link de entrada.
2. Um proprietário da equipe atualiza o app em cada equipe onde o Teams o oferece. No Teams, abra a equipe e selecione ⋯ → Manage team → Apps, escolha Update no app do Beeuni e aceite. O Teams instala uma atualização por conta própria, a menos que ela adicione uma permissão ou uma ação de mensagem; nesses casos, é necessário que um proprietário da equipe faça a atualização.

O Beeuni registra a versão do app a cada publicação. Uma instalação publicada antes de o Beeuni registrar as versões mostra o aviso até a próxima publicação.

Chats, canais e menções

• Chat pessoal: toda mensagem chega ao bot.
• Canal de equipe / chat em grupo: uma nova publicação precisa de uma menção @. Depois disso, uma resposta em uma conversa que o bot já controla continua a sessão sem menção, como acontece em uma thread do Slack. Isso requer as permissões ChannelMessage.Read.Group (canais) e ChatMessage.Read.Chat (chats em grupo) do app, às quais o administrador do tenant dá consentimento quando o app é adicionado. Se o app foi adicionado antes de essas permissões serem solicitadas, um proprietário da equipe deve atualizá-lo: consulte Atualizar o app.

Cada conversa de chat ou canal é uma sessão própria. A primeira mensagem a cria; as mensagens seguintes continuam nela, mesmo depois que o sandbox para e é retomado. Um tenant conectado a mais de um projeto mostra um seletor de projeto na primeira mensagem sem roteamento e memoriza a escolha. Em um canal, apenas uma mensagem que menciona o bot recebe o seletor, e um comando sobre o projeto, como /models, pergunta primeiro qual projeto usar.

Em um canal, cada nova publicação inicia sua própria sessão. Um chat pessoal ou em grupo é uma única conversa durante toda a sua existência, portanto mantém uma sessão até que você envie /new. Envie uma mensagem depois dele (/new summarize today's deploys) para iniciar a nova sessão com essa mensagem. A sessão anterior permanece no Beeuni, com todo o histórico, e a confirmação contém um link para ela.

Nomes das conversas

O Teams envia IDs, como 19:…@thread.tacv2;messageid=…. A página Channels e beeuni channels bindings mostram os nomes que as pessoas veem no Teams:

Uma mensagem de canal contém o ID da equipe, mas não seu nome, então o Beeuni lê e armazena no Teams os nomes da equipe e do canal. Uma publicação no canal General de uma equipe recebe um nome na próxima vez que a página Channels a listar. Uma publicação em outro canal recebe um nome na próxima mensagem. Até lá, ela aparece como Channel thread.

Quem pode entrar em uma sessão

Cada conversa tem uma política de entrada, definida com /policy no Teams ou na página Channels, onde N channels na linha do Teams lista todas as conversas:

• open (padrão) — qualquer membro do projeto vinculado pode entrar em uma sessão iniciada aqui.
• approval — o proprietário da sessão recebe um cartão Aprovar / Negar para cada pessoa nova.
• owner — somente a pessoa que iniciou a sessão.

Nas políticas approval e owner, a sessão também não fica visível para todo o projeto no Beeuni: apenas para o proprietário, as pessoas aprovadas e os administradores da conta que supervisionam as sessões. Uma decisão em um cartão de análise ou aprovação retoma o agente sob qualquer política.

Vinculação de identidade

O remetente vincula sua conta do Beeuni uma vez com /login; depois disso, o agente é executado como essa pessoa, com suas próprias credenciais, secrets e apps conectados. Um remetente não vinculado, ou sem acesso ao projeto, recebe um cartão para conectar ou solicitar acesso em vez de uma sessão.

O link de entrada aparece somente onde você pode vê-lo sozinho: no seu chat individual com o bot ou, em um canal ou chat em grupo, em uma resposta marcada como Only you can see this message. O link conecta a pessoa para quem foi emitido à pessoa que o abre, portanto nunca aparece onde outras pessoas possam vê-lo. Se o Teams recusar essa resposta privada, o bot envia o link para seu chat privado com ele e informa isso na conversa. O Teams só permite isso quando você adicionou o app para si mesmo; caso contrário, o cartão solicita que você abra um chat privado com o bot e envie /login nele. Uma mensagem enviada por você no canal enquanto não estava vinculado é executada quando você se conecta, se fizer isso dentro de 10 minutos. Ao concluir a conexão no navegador, seu chat privado com o bot confirma a qual conta do Beeuni você está vinculado.

Um link de entrada funciona uma vez e expira após 10 minutos. Uma conta do Teams conectada a uma conta do Beeuni não pode ser conectada a outra: envie /logout primeiro. Se sua organização exigir autenticação de dois fatores, o Beeuni solicitará seu segundo fator antes de conectá-lo, e o chat será executado usando o fator com o qual você se conectou. Um link criado sem ele solicitará que você se conecte novamente.

Quando alguém sem acesso solicita, todos os proprietários e administradores de contas recebem a solicitação no Beeuni. Quem vinculou o Teams também a recebe no chat privado com o bot, com um botão Review in Beeuni.

Respostas privadas

Em um canal ou chat em grupo, o que o bot diz a uma pessoa fica visível apenas para ela, marcado como Only you can see this message, assim como as mensagens efêmeras do Slack:

• as respostas aos seus comandos;
• o cartão para vincular sua conta ou solicitar acesso;
• o motivo pelo qual sua mensagem não foi executada: a política de entrada ou um agente que você não pode usar;
• em approval, o cartão de Aprovar / Negar do proprietário e a decisão para a pessoa que solicitou.

O cartão Working on it…, que todos veem, aparece somente quando sua mensagem pode ser executada. O Teams exclui uma resposta privada após 24 horas. Se o Teams recusar uma resposta privada, o bot publicará o cartão para toda a conversa. O link de login é a exceção: nesse caso, ele será enviado ao seu chat privado com o bot, nunca à conversa.

Funções e permissões

Um chat não tem uma credencial própria do Beeuni, portanto cada ação é executada usando a conta vinculada do Beeuni da pessoa que a realizou, com a função dessa conta no projeto. Proprietários e administradores de contas são considerados gerentes de projeto.

Uma pessoa excluída do escopo de um agente não pode iniciar uma sessão nele pelo Teams, assim como no Beeuni.

Comandos

Digite estes comandos em um chat com o bot (em um canal, mencione @ primeiro):

Em qualquer mensagem, ⋯ → Open in Beeuni abre a sessão à qual aquela conversa pertence. Quando você adiciona o aplicativo para si mesmo, seu chat privado com o bot começa com a mesma visão geral de /home.

Modelos e chaves

/models lista todos os modelos que você pode executar aqui, como o seletor da Web: modelos do Beeuni e modelos acessados por meio de uma chave de API de provedor ou de uma assinatura do ChatGPT. Cada um informa como é pago. Uma lista longa é um menu suspenso pesquisável. Toque em um modelo ou digite /model <id>; /model default volta ao padrão do projeto.

As chaves consideradas dependem do chat:

• Um chat pessoal com o bot — suas próprias chaves e assinatura do ChatGPT, além das chaves compartilhadas com o projeto. As sessões são privadas para você.
• Um chat em grupo ou canal — somente as chaves compartilhadas com todo o projeto. O chat é compartilhado, e uma chave pessoal ali permitiria que todos nele gastassem a assinatura de uma pessoa. Escolha esse tipo de modelo em um chat pessoal.

Um modelo executado com chaves usa todas as chaves que você pode usar para o provedor, alternando entre elas quando há limites de taxa. A escolha se aplica à próxima mensagem; o chat mantém sua sessão. Alterar o modelo de uma sessão em execução exige uma conta vinculada e, sob a política owner ou approval, somente o proprietário da sessão pode alterá-lo. Um chat pessoal cuja sessão foi iniciada antes de as sessões se tornarem privadas ainda compartilha essa sessão com o projeto: /model informa isso, e /new inicia uma sessão privada. Consulte Provider keys and member access.

Enquanto o agente trabalha

O agente responde em um único cartão: mostra as etapas enquanto trabalha e, depois, a resposta. Uma resposta longa é cortada em uma linha, marcada como cortada e vinculada à sessão completa no Beeuni. Outra mensagem aguarda a execução atual e depois recebe seu próprio cartão. Uma etapa silenciosa não encerra uma execução; somente a conclusão do runtime o faz.

Interrompendo uma execução

Enquanto o agente trabalha, o cartão ativo exibe um botão Stop. /stop faz a mesma coisa depois que o cartão sai da área visível. Qualquer uma das opções encerra a execução no runtime, não apenas no cartão — uma execução deixada aberta absorve a próxima mensagem da conversa em vez de respondê-la.

A pessoa que enviou a mensagem à qual está sendo respondida pode interrompê-la, assim como qualquer pessoa aprovada nessa sessão, enquanto ainda puder usar o projeto. Um espectador no canal não pode, nem alguém aprovado em uma sessão anterior do chat.

Arquivos

O agente envia arquivos com teams send --file. As imagens aparecem em linha em chats pessoais, em grupo e em canais. Uma imagem grande demais resulta em um cartão de consentimento do OneDrive em um chat pessoal ou em arquivos da equipe em um canal; um chat em grupo não pode receber uma transferência grande demais. Outros arquivos chegam como um cartão de consentimento em um chat pessoal ou como um link do SharePoint quando compartilhados com uma equipe. Arquivos recebidos e imagens coladas, incluindo imagens incorporadas no corpo de uma mensagem de canal, ficam disponíveis para o agente baixar e usar.

• Uma imagem colada em um canal ou chat em grupo só é baixada quando o agente pode ler essa thread ou esse chat, de acordo com as regras em Reading a channel. Caso contrário, teams download responde 403.
• Um download é interrompido em 50 MB e responde 413.
• teams history e teams thread listam as imagens em linha de uma publicação (images, cada uma sendo uma URL para teams download) e os nomes dos arquivos compartilhados do SharePoint (files). O agente não pode baixar um arquivo do SharePoint.

Cole uma captura de tela e faça uma pergunta sobre ela; a interação será executada em um modelo capaz de ler imagens, mesmo quando o modelo próprio da conversa aceitar apenas texto — a escolha de modelo da sessão permanece inalterada. Um modelo que a sessão não possa mais executar — uma chave revogada ou uma assinatura do ChatGPT que o chat não possa usar — é substituído para essa mensagem da mesma forma, em vez de fazer a mensagem falhar.

Perguntas e formulários

O agente pergunta com controles, não com texto livre. Uma pergunta com até seis opções recebe um botão por opção. Várias perguntas, uma pergunta de seleção múltipla ou uma lista mais longa recebem um formulário com um campo para sua própria resposta. Datas, horários, números e opções de ligado/desligado usam campos correspondentes. Sua resposta chega ao agente como sua próxima mensagem, identificada com a pergunta a que responde. Você sempre pode digitar uma resposta em vez disso.

Aprovações

Quando um agente precisa de uma decisão humana antes de prosseguir — uma etapa arriscada, uma alteração para a qual deseja aprovação — ele envia um item para análise. Se a sessão foi iniciada nesta conversa, a decisão aparece aqui em um cartão: o título, um resumo, um nível de risco e Aprovar, Solicitar alterações e Rejeitar, além de um link para o Beeuni.

O cartão inclui um campo opcional para comentários. O que você escrever será armazenado com a decisão e encaminhado ao agente junto com ela, então Solicitar alterações não exige uma segunda rodada para perguntar o que você quis dizer. O campo é opcional por definição — uma aprovação simples não deve exigir que você digite algo.

Qualquer pessoa na conversa vê o cartão, mas para tomar uma decisão é preciso ter uma conta Beeuni vinculada com acesso ao projeto.

Publicar por conta própria

Além de responder onde foi solicitado, o agente pode publicar em qualquer chat ou canal em que o bot já esteja para este projeto — um resumo noturno, um alerta, uma transferência de trabalho. Ele não consegue acessar uma conversa à qual nunca foi adicionado.

Quando uma sessão não inicia

O Beeuni informa o que está errado em vez de pedir que você tente novamente, porque a maioria das falhas ao iniciar não se resolve com uma nova tentativa: um modelo de sandbox que não existe mais, uma conta não vinculada, um projeto ao qual você não tem acesso ou um workspace sem créditos. Cada mensagem indica a correção e o comando correspondente.

Se o agente definido para a conversa tiver sido excluído ou renomeado, a falha aparece como um seletor: escolha um agente ativo e envie sua mensagem novamente. A lista mostra apenas os agentes aos quais você tem acesso.

Ler um canal

Em um canal, o bot recebe apenas as mensagens que o mencionam, então a discussão sobre a qual foi consultado não está na sessão. Quando precisa desse contexto, o agente lê a conversa na qual foi mencionado ou as publicações recentes do canal por meio da permissão ChannelMessage.Read.Group solicitada pelo app quando ele é adicionado a uma equipe. Uma equipe que adicionou o app antes dessa solicitação de permissão precisa atualizá-lo: consulte Atualizar o app. Em um chat pessoal, todas as mensagens já chegam à sessão, então não há nada anterior para ler.

Todos os projetos conectados ao mesmo tenant do Microsoft 365 usam o mesmo app, então o Beeuni mantém cada leitura dentro das conversas do próprio projeto. Em um canal, cada nova publicação é uma conversa independente:

Uma leitura recusada responde a 403 com o motivo conversation_not_in_project e uma mensagem que identifica o canal ou a conversa. Para ler um canal do primeiro tipo em um tenant com vários projetos, mencione o bot nele e escolha este projeto.

get_channel e list_channels funcionam em canais padrão. Um canal privado ou compartilhado só aparece quando o agente pode lê-lo pelas regras acima. get_team, list_members, get_user e list_teams leem o diretório do tenant e não têm restrições.

Limites

Os bots do Teams não podem adicionar reações às mensagens nem pesquisar mensagens — esses recursos do Slack não têm equivalente no Teams. O agente só pode ler um canal em uma equipe à qual o app foi adicionado, e apenas pelas regras descritas em Leitura de um canal.