Microsoft Teams — Chat Empresarial

Pense em conectar o Hermes Agent ao Microsoft Teams como dar um crachá de empresa ao seu assistente de IA — uma vez que ele entra no time, pode participar de reuniões, responder perguntas em canais e ajudar em conversas diretas, tudo sem sair do aplicativo que seus colegas já usam todos os dias.

Por que o Teams é diferente do Slack

Se você já usou o Socket Mode do Slack antes, saiba que o Teams funciona um pouco diferente. Em vez de manter uma conexão aberta, o Teams chama o webhook público do seu bot sempre que alguém envia uma mensagem. Isso significa que sua instância do Hermes precisa de uma URL HTTPS pública — nada de localhost. Para testes, você pode usar um túnel; para produção, aponte para o domínio do seu servidor real.

Como o bot se comporta

Aqui está a regra básica:

Onde você fala com ele	O que acontece
Chat pessoal (DM)	O bot responde a todas as mensagens — sem precisar de @mention
Chat em grupo	O bot só responde quando você usa @mention
Canal	O bot só responde quando você usa @mention

O Teams envia as menções como tags <at>NomeDoBot</at>, mas o Hermes as remove automaticamente antes de processar — então você não precisa se preocupar com isso.

Passo 1: Instale a CLI do Teams

Primeiro, instale a ferramenta de linha de comando da Microsoft que automatiza o registro do bot — sem precisar do portal Azure:

npm install -g @microsoft/teams.cli@preview
teams login

Para verificar seu login e encontrar seu AAD object ID (você vai precisar dele depois para restringir o acesso), execute:

teams status --verbose

Passo 2: Exponha a porta do webhook

O Teams não consegue entregar mensagens para localhost. Para desenvolvimento local, use um túnel para obter uma URL HTTPS pública. A porta padrão é 3978 (mude com TEAMS_PORT se precisar).

Aqui estão três opções fáceis:

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https
devtunnel host hermes-bot

# ngrok
ngrok http 3978

# cloudflared
cloudflared tunnel --url http://localhost:3978

Copie a URL https:// da saída — você vai precisar dela no próximo passo. Deixe o túnel rodando enquanto desenvolve.

Passo 3: Crie o bot

Agora registre seu bot no Teams:

teams app create \
  --name "Hermes" \
  --endpoint "https://<sua-url-do-tunel>/api/messages"

A CLI vai exibir seu CLIENT_ID, CLIENT_SECRET e TENANT_ID, além de um link de instalação. Salve o client secret imediatamente — ele não será mostrado novamente.

Passo 4: Configure as variáveis de ambiente

Adicione estas linhas ao seu arquivo ~/.hermes/.env:

# Obrigatório
TEAMS_CLIENT_ID=<seu-client-id>
TEAMS_CLIENT_SECRET=<seu-client-secret>
TEAMS_TENANT_ID=<seu-tenant-id>

# Restringir acesso a usuários específicos (recomendado)
# Use os AAD object IDs de `teams status --verbose`
TEAMS_ALLOWED_USERS=<seu-aad-object-id>

Passo 5: Inicie o gateway

Se você usa Docker, execute a partir do diretório que contém o docker-compose.yml (geralmente o repositório clonado do hermes-agent, não o ~):

cd /caminho/para/hermes-agent
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up

Para instalações a partir do código-fonte, certifique-se de incluir o extra do Teams primeiro:

uv sync --extra teams
# ou, para instalações editáveis:
uv pip install -e ".[teams]"

Concluindo

Conectar o Hermes ao Teams é uma dança de quatro passos: instale a CLI, exponha uma URL pública, crie o bot e configure suas variáveis de ambiente. Depois que estiver rodando, seu assistente de IA se torna um membro completo do time — respondendo em DMs automaticamente e entrando em conversas de grupo quando chamado.

Dica prática: Comece com TEAMS_ALLOWED_USERS definido apenas com o seu próprio AAD object ID. Assim, você pode testar com segurança sem se preocupar com colegas aleatórios acionando seu bot — e depois expanda o acesso quando tiver certeza de que tudo funciona.

---