# Microsoft Teams

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

Canonical page: https://beeuni.ai/docs/pt/connect/teams

O Microsoft Teams é um canal: uma menção `@` em um chat ou canal do Teams inicia uma [sessão](/docs/pt/work/sessions), e o agente responde ali mesmo com progresso em tempo real. Ele segue as mesmas regras de sessão, identidade e credenciais do [Slack](/docs/pt/connect/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.

<a id="connect"></a>

## 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](#update-the-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:

```bash
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
```

<a id="update-the-app"></a>

## 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.

<a id="chats-channels-and-mentions"></a>

## 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](#update-the-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.

<a id="conversation-names"></a>

## 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:

| Conversa | Nome | Abaixo do nome |
|---|---|---|
| Uma publicação de canal | `Team › Channel` | O título da sessão, que diferencia duas publicações no mesmo canal |
| Um chat em grupo | O título do chat | Chat em grupo |
| Um chat pessoal | A pessoa | Chat pessoal |

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**.

<a id="who-may-join-a-session"></a>

## 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.

<a id="identity-linking"></a>

## 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**.

<a id="private-replies"></a>

## 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.

<a id="roles-and-permissions"></a>

## 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.

| Ação | Quem pode realizá-la |
| --- | --- |
| Enviar uma mensagem respondida pelo agente | Uma conta vinculada com acesso ao projeto, dentro da política de entrada da conversa |
| Interromper uma execução | A pessoa que enviou a mensagem à qual está sendo respondida ou qualquer pessoa aprovada nessa sessão que ainda possa usar o projeto |
| `/new` em um chat em grupo | Um membro vinculado do projeto; sob `approval` ou `owner`, alguém aprovado na sessão atual |
| Alterar o projeto, o agente, o modelo ou a política | Um gerente de projeto; em um chat pessoal com o bot, qualquer membro do projeto |
| Aprovar ou negar uma revisão | Um gerente de projeto |
| Aprovar ou negar uma chamada de conector | Um gerente de projeto ou a pessoa que iniciou a sessão |
| Aprovar alguém em uma sessão `approval` | O proprietário da sessão |
| Solicitar acesso | Qualquer pessoa vinculada; cada proprietário e administrador de conta é notificado uma vez |

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

<a id="commands"></a>

## Comandos

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

| Comando | O que ele faz |
| --- | --- |
| `/help` | Lista os comandos |
| `/login`, `/logout`, `/whoami` | Vincula, desvincula ou mostra sua conta do Beeuni |
| `/status` | Mostra o projeto, o agente e o modelo efetivos aqui, além da execução em andamento |
| `/stop` | Interrompe a execução em andamento aqui |
| `/new [message]` | Inicia uma nova sessão neste chat (chats pessoais e em grupo) |
| `/models`, `/model <ref>` | Escolhe o modelo para esta conversa — consulte [Models and keys](#models-and-keys) |
| `/agents`, `/agent <name>` | Escolhe o agente para esta conversa |
| `/projects`, `/use <name>` | Lista os projetos conectados ou direciona este para outro (não disponível no próprio bot de um projeto) |
| `/policy [open\|approval\|owner]` | Mostra quem pode entrar nas sessões iniciadas aqui |
| `/unbind` | Desconecta esta conversa do projeto; a próxima mensagem escolherá um novamente |
| `/home` | Mostra os projetos da organização e o que experimentar |

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`.

<a id="models-and-keys"></a>

## 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](/docs/pt/project/models#provider-keys-and-member-access).

<a id="while-the-agent-works"></a>

## 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.

<a id="stopping-a-run"></a>

## 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.

<a id="files"></a>

## 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](#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.

<a id="questions-and-forms"></a>

## 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.

<a id="approvals"></a>

## 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.

<a id="posting-on-its-own"></a>

## 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.

<a id="when-a-session-will-not-start"></a>

## 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.

<a id="reading-a-channel"></a>

## 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](#update-the-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:

| Leitura | Permitida quando |
| --- | --- |
| Uma conversa (`teams thread`) | A conversa pertence a este projeto ou a nenhum projeto e o canal pode ser lido |
| Publicações recentes de um canal (`teams history`) | Este projeto tem uma conversa no canal. Publicações que iniciam uma conversa de outro projeto ficam de fora |
| Um canal no qual nenhum projeto tem uma conversa | Nenhum outro projeto está conectado ao tenant |

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.

<a id="limits"></a>

## 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](#reading-a-channel).