# Microsoft Teams Connetti un bot di Microsoft Teams per avviare e continuare sessioni Beeuni nelle chat e nei canali. Canonical page: https://beeuni.ai/docs/it/connect/teams Microsoft Teams è un canale: una menzione `@` in una chat o in un canale Teams avvia una [sessione](/docs/it/work/sessions) e l'agente risponde direttamente, mostrando i progressi in tempo reale. Segue le stesse regole di sessione, identità e credenziali di [Slack](/docs/it/connect/slack); questa pagina tratta ciò che è specifico di Teams. Ogni progetto può collegarsi a Teams. Non è necessario attivare alcun flag di funzionalità. ## Connessione Due modalità, entrambe dalla pagina **Connettori → Canali** del progetto: - **Un clic (gestita).** Un **amministratore del tenant** di Teams fa clic su **Aggiungi a Teams**, accede e concede il consenso. Beeuni pubblica automaticamente l'app nel catalogo Teams della tua organizzazione: non devi creare né incollare nulla. La riga offre quindi **Aggiungi a Teams** (un deep link nel client Teams), così chiunque può aggiungere il bot a una chat o a un canale. Quando Beeuni rilascia una versione più recente dell'app, consulta [Aggiornare l'app](#update-the-app). - **Usa il tuo bot.** Fai clic su **Usa la tua app Microsoft Teams** per aprire una procedura guidata in tre passaggi: registra un Azure Bot, collegalo a Beeuni con il relativo id app, segreto client e id tenant, quindi scarica il pacchetto dell'app generato e caricalo in Teams. Usa questa modalità quando gestisci tu la registrazione del bot. L'ordine è importante. Beeuni crea il manifesto a partire dall'id app **tuo**, quindi può generare il pacchetto solo dopo il passaggio 2: la procedura guidata mostra l'endpoint di messaggistica da incollare in Azure prima di chiederti qualsiasi altra informazione. La CLI rispecchia il 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 ``` ## Aggiornare l'app Nel tempo Beeuni aggiunge autorizzazioni alla sua app Teams. La versione dell'app 1.1.0 ha aggiunto `ChannelMessage.Read.Group`, necessaria all'agente per leggere una discussione in un canale. La versione 1.3.0 ha aggiunto `ChatMessage.Read.Chat`, così una risposta in una chat di gruppo continua una sessione senza menzione. Un team che usa ancora la versione 1.0.0 rifiuta ogni lettura di discussione, e il rifiuto ricevuto dall'agente indica chi deve risolvere il problema. L'aggiornamento dell'app richiede due persone, in quest'ordine: 1. **Un amministratore di Teams pubblica l'aggiornamento.** Quando il catalogo dell'organizzazione contiene una versione precedente, la pagina Canali mostra **Aggiorna l'app Beeuni in Teams** e il pulsante nella riga Teams riporta **Pubblica aggiornamento app**. L'amministratore fa clic e accede con Microsoft. `beeuni channels status --platform teams` stampa entrambe le versioni e `beeuni channels connect --platform teams` stampa il link di accesso. 2. **Il proprietario di un team aggiorna l'app in ogni team in cui Teams lo richiede.** In Teams, apri il team, quindi **⋯ → Gestisci team → App**, seleziona **Aggiorna** nell'app Beeuni e accetta. Teams installa autonomamente un aggiornamento, a meno che non aggiunga un'autorizzazione o un'azione messaggio; in questi casi è necessario l'intervento del proprietario del team. Beeuni registra la versione dell'app a ogni pubblicazione. Un'installazione pubblicata prima che Beeuni iniziasse a registrare le versioni mostra l'avviso fino alla pubblicazione successiva. ## Chat, canali e menzioni - **Chat personale:** ogni messaggio raggiunge il bot. - **Canale del team / chat di gruppo:** un nuovo post richiede una menzione `@`. In seguito, una risposta in una conversazione già gestita dal bot continua la sessione **senza** menzione, come in un thread Slack. Sono necessarie le autorizzazioni dell'app `ChannelMessage.Read.Group` (canali) e `ChatMessage.Read.Chat` (chat di gruppo), alle quali l'amministratore del tenant concede il consenso quando aggiunge l'app. Se l'app è stata aggiunta prima che queste autorizzazioni fossero richieste, il proprietario di un team deve aggiornarla: consulta [Aggiornare l'app](#update-the-app). Ogni conversazione in chat o in un canale è una sessione distinta. Il primo messaggio la crea; i messaggi successivi la continuano, anche dopo l'arresto e la ripresa della sandbox. Un tenant collegato a più di un progetto mostra un **selettore di progetto** sul primo messaggio non instradato e ricorda la scelta. In un canale, solo un messaggio che menziona il bot mostra il selettore; un comando relativo al progetto, come `/models`, chiede prima quale progetto usare. In un canale, ogni nuovo post avvia una sessione propria. Una chat personale o di gruppo è un'unica conversazione per tutta la sua durata, quindi mantiene una sessione finché non invii `/new`. Inserisci un messaggio dopo di esso (`/new summarize today's deploys`) per avviare la nuova sessione con quel messaggio. La sessione precedente rimane in Beeuni, con la cronologia completa, e la conferma contiene un link alla sessione. ## Nomi delle conversazioni Teams invia id, come `19:…@thread.tacv2;messageid=…`. La pagina Canali e `beeuni channels bindings` mostrano i nomi che le persone leggono in Teams: | Conversazione | Nome | Sotto il nome | |---|---|---| | Un post in un canale | `Team › Channel` | Il titolo della sessione, che distingue due post nello stesso canale | | Una chat di gruppo | Il titolo della chat | Chat di gruppo | | Una chat personale | La persona | Chat personale | Un messaggio in un canale contiene l'id del team, ma non il suo nome; Beeuni quindi legge da Teams i nomi del team e del canale e li memorizza. Un post nel canale Generale di un team riceve il nome la volta successiva in cui la pagina Canali lo elenca. Un post in un altro canale riceve il nome con il messaggio successivo. Fino ad allora viene visualizzato come **Thread del canale**. ## Chi può partecipare a una sessione Ogni conversazione ha una policy di partecipazione, impostata con `/policy` in Teams o nella pagina Canali, dove **N canali** nella riga Teams elenca ogni conversazione: - **aperta** (predefinita): qualsiasi membro del progetto collegato può partecipare a una sessione avviata qui. - **approvazione**: il proprietario della sessione riceve una scheda Approva / Rifiuta per ogni nuova persona. - **proprietario**: solo la persona che ha avviato la sessione. Con le policy **approvazione** e **proprietario**, la sessione non è visibile all'intero progetto neanche in Beeuni: è visibile solo al proprietario, alle persone approvate e agli amministratori dell'account che supervisionano le sessioni. Una decisione presa su una scheda di revisione o approvazione riprende l'agente con qualsiasi policy. ## Collegamento dell'identità Il mittente collega una volta il proprio account Beeuni con `/login`; l'agente opera quindi a suo nome, con le sue credenziali, i suoi segreti e le sue app collegate. Un mittente non collegato, o senza accesso al progetto, riceve una scheda per collegarsi o richiedere l'accesso invece di una sessione. Il link di accesso compare solo dove puoi vederlo soltanto tu: nella chat individuale con il bot oppure, in un canale o in una chat di gruppo, in una risposta contrassegnata **Solo tu puoi vedere questo messaggio**. Il link collega alla persona per cui è stato emesso chiunque lo apra, quindi non compare mai in un luogo visibile agli altri. Se Teams rifiuta quella risposta privata, il bot invia il link alla tua chat privata con il bot e lo comunica nella conversazione. Teams lo consente solo quando hai aggiunto l'app per te stesso; altrimenti la scheda ti chiede di aprire una chat privata con il bot e di inviare lì `/login`. Un messaggio che hai inviato nel canale mentre non eri collegato viene eseguito una volta completato il collegamento, se lo fai entro 10 minuti. Al termine del collegamento nel browser, la tua chat privata con il bot conferma a quale account Beeuni sei collegato. Un link di accesso funziona una sola volta e scade dopo 10 minuti. Un account Teams collegato a un account Beeuni non può essere collegato a un altro: invia prima `/logout`. Se la tua organizzazione richiede l'autenticazione a due fattori, Beeuni richiede il secondo fattore prima di collegarti e la chat viene eseguita usando il fattore con cui ti sei collegato. Un link creato senza di esso ti chiede di collegarti nuovamente. Quando alguém sem acesso faz uma solicitação, todos os proprietários e administradores da conta recebem uma 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 só fica visível para ela, com a indicação **Only you can see this message**, assim como as mensagens efêmeras do Slack: - as respostas aos seus comandos; - o cartão para conectar 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 Aprovar / Negar do proprietário e a decisão enviada a quem fez a solicitação. O cartão **Working on it…** que todos veem só aparece 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 publica o cartão para toda a conversa. A exceção é o link de entrada: nesse caso, ele vai para seu chat privado com o bot, nunca para a conversa. ## Funções e permissões Um chat não possui credenciais próprias do Beeuni, então cada ação é executada com a conta do Beeuni vinculada da pessoa que a realizou, usando a função dessa conta no projeto. Proprietários e administradores da conta são considerados gerentes de projeto. | Ação | Quem pode realizá-la | | --- | --- | | Enviar uma mensagem para o agente responder | Uma conta vinculada com acesso ao projeto, de acordo com a política de entrada da conversa | | Interromper uma execução | A pessoa que enviou a mensagem 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; com a política `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 da conta recebe uma notificação | Uma pessoa sem acesso a determinado agente não pode iniciar uma sessão com ele pelo Teams, assim como no Beeuni. ## Comandos Digite estes comandos em um chat com o bot (em um canal, mencione-o primeiro com `@`): | Comando | O que faz | | --- | --- | | `/help` | Lista os comandos | | `/login`, `/logout`, `/whoami` | Vincula, desvincula ou mostra sua conta Beeuni | | `/status` | O projeto, o agente e o modelo efetivos neste chat, além da execução em andamento | | `/stop` | Interrompe a execução em andamento neste chat | | `/new [message]` | Inicia uma nova sessão neste chat (chats pessoais e em grupo) | | `/models`, `/model ` | Escolhe o modelo para esta conversa — consulte [Modelos e chaves](#models-and-keys) | | `/agents`, `/agent ` | Escolhe o agente para esta conversa | | `/projects`, `/use ` | Lista os projetos conectados ou direciona este chat para outro (não disponível no bot próprio de um projeto) | | `/policy [open\|approval\|owner]` | Quem pode participar das sessões iniciadas aqui | | `/unbind` | Desconecta esta conversa do projeto; a próxima mensagem seleciona outro projeto | | `/home` | Os projetos da organização e o que experimentar | Em qualquer mensagem, **⋯ → Open in Beeuni** abre a sessão à qual a conversa pertence. Quando você adiciona o aplicativo para si, 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 Beeuni e modelos acessíveis por uma chave de API de provedor ou uma assinatura do ChatGPT. Cada um informa como é pago. Uma lista longa aparece em um menu suspenso pesquisável. Toque em um modelo ou digite `/model `; `/model default` volta ao padrão do projeto. As chaves disponíveis 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 chaves compartilhadas com todo o projeto. O chat é compartilhado, e uma chave pessoal permitiria que todos nele usassem a assinatura de uma pessoa. Em vez disso, escolha esse modelo em um chat pessoal. Um modelo que usa chaves utiliza todas as chaves disponíveis para o provedor, e elas são alternadas quando há limites de taxa. A escolha se aplica à próxima mensagem; o chat mantém a sessão. Para alterar o modelo de uma sessão em execução, é necessária uma conta vinculada e, com a política `owner` ou `approval`, somente o proprietário da sessão pode alterá-lo. Um chat pessoal cuja sessão começou antes de as sessões se tornarem privadas continua compartilhando essa sessão com o projeto: `/model` informa isso, e `/new` inicia uma sessão privada. Consulte [Chaves de provedor e acesso de membros](/docs/it/project/models#provider-keys-and-member-access). ## Enquanto o agente trabalha O agente responde em um único cartão: mostra as etapas enquanto trabalha e, em seguida, a resposta. Uma resposta longa é cortada em uma quebra de linha, sinalizada como truncada e inclui um link para a sessão completa no Beeuni. Outra mensagem aguarda a execução atual terminar e, depois, recebe seu próprio cartão. Uma etapa silenciosa não encerra uma execução; somente a conclusão do ambiente de execução faz isso. ## Interromper uma execução Enquanto o agente trabalha, o cartão dinâmico exibe um botão **Stop**. `/stop` faz a mesma coisa quando o cartão já saiu da tela. Ambos encerram a execução no ambiente de execução, não apenas no cartão — uma execução que permanece aberta absorve a próxima mensagem da conversa em vez de respondê-la. A pessoa que enviou a mensagem respondida pode interromper a execução, assim como qualquer pessoa aprovada nessa sessão, desde que ainda possa usar o projeto. Quem apenas acompanha o canal não pode, nem alguém aprovado em uma sessão anterior do chat. ## Arquivos O agente envia arquivos com `teams send --file`. Imagens aparecem em linha em chats pessoais, em grupo e em canais. Uma imagem grande demais é substituída por um cartão de consentimento do OneDrive em um chat pessoal ou por 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 ao 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 se o agente puder ler a conversa por tópico ou o chat, de acordo com as regras em [Ler um canal](#reading-a-channel). Caso contrário, `teams download` responde `403`. - O download é interrompido ao atingir 50 MB e responde `413`. - `teams history` e `teams thread` listam as imagens em linha de uma publicação (`images`, cada uma é um URL para `teams download`) e os nomes dos arquivos compartilhados pelo SharePoint (`files`). O agente não pode baixar arquivos do SharePoint. Cole uma captura de tela e pergunte sobre ela: a solicitação será executada em um modelo que consegue ler imagens, mesmo que o modelo da conversa aceite apenas texto — a escolha de modelo da sessão não é alterada. Um modelo que a sessão já não possa executar — porque uma chave foi revogada ou a conversa não pode usar uma assinatura ChatGPT — é substituído da mesma forma para essa mensagem, em vez de causar uma falha. ## Perguntas e formulários L'agente pone domande con controlli, non in prosa. Una domanda con fino a sei opzioni riceve un pulsante per ogni opzione. Più domande, una domanda a scelta multipla o un elenco più lungo ricevono un modulo con un campo per la propria risposta. Date, orari, numeri e scelte sì/no usano input corrispondenti. La risposta arriva all'agente come messaggio successivo, contrassegnato con la domanda a cui risponde. Puoi sempre scrivere una risposta manualmente. ## Approvazioni Quando un agente ha bisogno di una decisione umana prima di procedere — un passaggio rischioso o una modifica che vuole far approvare — crea un elemento di revisione. Se la sessione è stata avviata da questa conversazione, la decisione arriva qui sotto forma di scheda: il titolo, un riepilogo, un livello di rischio e **Approva**, **Richiedi modifiche** e **Nega**, oltre a un link a Beeuni. La scheda contiene un campo facoltativo per i commenti. Qualsiasi cosa tu scriva viene salvata insieme alla decisione e trasmessa all'agente, così **Richiedi modifiche** non richiede un secondo scambio per chiedere cosa intendessi. È facoltativo per scelta — un semplice **Approva** non dovrebbe richiedere di scrivere nulla. Chiunque partecipi alla conversazione vede la scheda, ma per agire è necessario un account Beeuni collegato con accesso al progetto. ## Pubblicazione autonoma Oltre a rispondere dove è stato interpellato, l'agente può pubblicare in qualsiasi chat o canale in cui il bot sia già presente per questo progetto — un riepilogo notturno, un avviso, un passaggio di consegne. Non può raggiungere una conversazione a cui non è mai stato aggiunto. ## Quando una sessione non si avvia Beeuni indica cosa non va invece di chiederti di riprovare, perché la maggior parte dei fallimenti di avvio non si risolve riprovando: un modello di sandbox che non esiste più, un account non collegato, un progetto a cui non puoi accedere o un'area di lavoro senza crediti. Ogni messaggio indica la correzione e il comando da applicare. Se l'agente impostato per la conversazione è stato eliminato o rinominato, il fallimento arriva sotto forma di selettore: scegli un agente attivo, quindi invia di nuovo il tuo messaggio. L'elenco offre solo gli agenti a cui hai accesso. ## Lettura di un canale In un canale il bot riceve solo i messaggi che lo menzionano, quindi la discussione a cui si fa riferimento non è inclusa nella sessione. Quando ha bisogno di questo contesto, l'agente legge il thread in cui è stato menzionato o i post recenti del canale tramite l'autorizzazione `ChannelMessage.Read.Group` richiesta dall'app quando viene aggiunta a un team. Un team che ha aggiunto l'app prima che fosse richiesta questa autorizzazione deve aggiornarla: vedi [Aggiorna l'app](#update-the-app). In una chat personale ogni messaggio raggiunge già la sessione, quindi non c'è nulla di precedente da leggere. Ogni progetto connesso allo stesso tenant Microsoft 365 usa la stessa app, quindi Beeuni mantiene ogni lettura all'interno delle conversazioni del progetto. In un canale, ogni nuovo post è una conversazione distinta: | Lettura | Consentita quando | | --- | --- | | Un thread (`teams thread`) | Il thread è una conversazione di questo progetto, oppure non appartiene ad alcun progetto e il canale è leggibile | | I post recenti di un canale (`teams history`) | Questo progetto ha una conversazione nel canale. I post che avviano la conversazione di un altro progetto vengono esclusi | | Un canale in cui nessun progetto ha una conversazione | Nessun altro progetto è connesso al tenant | Una lettura rifiutata risponde a `403` con il motivo `conversation_not_in_project` e un messaggio che indica il canale o il thread. Per leggere un canale del primo tipo in un tenant con più progetti, menziona il bot al suo interno e seleziona questo progetto. `get_channel` e `list_channels` forniscono risposte per i canali standard. Un canale privato o condiviso appare solo quando l'agente può leggerlo secondo le regole sopra indicate. `get_team`, `list_members`, `get_user` e `list_teams` leggono la directory del tenant e non sono soggetti a limitazioni. ## Limiti I bot di Teams non possono aggiungere reazioni ai messaggi né cercare messaggi — queste funzionalità di Slack non hanno un equivalente in Teams. L'agente può leggere un canale solo in un team a cui è stata aggiunta l'app e solo secondo le regole in [Lettura di un canale](#reading-a-channel).