Operar o Pipeline de Reuniões do Teams

Use este guia depois de já ter habilitado o recurso em Reuniões do Teams.

Esta página cobre:

• fluxos de CLI para o operador
• manutenção rotineira de assinaturas
• triagem de falhas
• verificações antes de entrar no ar
• planilha de implantação

Comandos principais do operador

Validar o retrato da configuração

hermes teams-pipeline validate

Rode isto primeiro depois de qualquer mudança de configuração.

Inspecionar a saúde dos tokens

hermes teams-pipeline token-health
hermes teams-pipeline token-health --force-refresh

Use --force-refresh quando você suspeitar de estado de autenticação desatualizado.

Inspecionar assinaturas

hermes teams-pipeline subscriptions

Renovar assinaturas perto de expirar

hermes teams-pipeline maintain-subscriptions
hermes teams-pipeline maintain-subscriptions --dry-run

Automatizar a renovação de assinaturas (OBRIGATÓRIO em produção)

As assinaturas do Microsoft Graph expiram em no máximo 72 horas. Se nada as renova, as notificações de reunião param em silêncio depois de 3 dias e o pipeline parece "quebrado". Este é o modo de falha operacional número 1 de qualquer integração baseada no Graph.

Você PRECISA rodar o maintain-subscriptions em uma agenda. Escolha uma destas três opções:

Opção 1: cron do Hermes (recomendada se você já roda o gateway do Hermes)

O Hermes traz um agendador de cron embutido. O modo --no-agent roda um script como o job (em vez de usar um LLM), e --script precisa apontar para um arquivo dentro de ~/.hermes/scripts/. Primeiro crie o script:

mkdir -p ~/.hermes/scripts
cat > ~/.hermes/scripts/maintain-teams-subscriptions.sh <<'EOF'
#!/usr/bin/env bash
exec hermes teams-pipeline maintain-subscriptions
EOF
chmod +x ~/.hermes/scripts/maintain-teams-subscriptions.sh

Depois registre um job de cron somente-script que roda a cada 12 horas (dá 6x de folga contra a janela de expiração de 72h):

hermes cron create "0 */12 * * *" \
  --name "teams-pipeline-maintain-subscriptions" \
  --no-agent \
  --script maintain-teams-subscriptions.sh \
  --deliver local

Confirme que foi registrado e veja o próximo horário de execução:

hermes cron list
hermes cron status        # status do agendador

Opção 2: timer do systemd (recomendada para implantações de produção em Linux)

Crie /etc/systemd/system/hermes-teams-pipeline-maintain.service:

[Unit]
Description=Manutencao de assinaturas do pipeline Teams do Hermes
After=network-online.target

[Service]
Type=oneshot
User=hermes
EnvironmentFile=/etc/hermes/env
ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions

E /etc/systemd/system/hermes-teams-pipeline-maintain.timer:

[Unit]
Description=Roda a manutencao de assinaturas do pipeline Teams do Hermes a cada 12 horas

[Timer]
OnBootSec=5min
OnUnitActiveSec=12h
Persistent=true

[Install]
WantedBy=timers.target

Habilite:

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-teams-pipeline-maintain.timer
systemctl list-timers hermes-teams-pipeline-maintain.timer

Opção 3: crontab comum

0 */12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1

Garanta que o ambiente do cron tenha as credenciais MSGRAPH_*. Correção mais simples: dê source em ~/.hermes/.env no topo de um script wrapper que o crontab chama.

Verificar se a renovação está funcionando

Depois de montar a agenda, confira a atividade de renovação após a primeira execução agendada:

hermes teams-pipeline subscriptions   # deve mostrar o expirationDateTime avançado
hermes teams-pipeline maintain-subscriptions --dry-run   # deve mostrar "0 expiring soon" na maior parte do tempo

Se um dia o seu webhook do Graph misteriosamente "parar de funcionar" depois de exatamente ~72 horas, é a primeira coisa a checar: o job de renovação rodou mesmo?

Inspecionar jobs recentes

hermes teams-pipeline list
hermes teams-pipeline list --status failed
hermes teams-pipeline show <job-id>

Reexecutar um job armazenado

hermes teams-pipeline run <job-id>

Simular a busca de artefatos de reunião

hermes teams-pipeline fetch --meeting-id <id-da-reuniao>
hermes teams-pipeline fetch --join-web-url "<url-de-entrada>"
hermes teams-pipeline fetch --join-web-url "<url-de-entrada>" --organizer-user-id <id-de-usuario-entra>

Passe --organizer-user-id (o ID de usuário do Microsoft Entra do organizador) para resolver pelo caminho do Graph /users/{id}/onlineMeetings, com escopo de organizador. Isso é obrigatório para as URLs curtas /meet/ do Teams, que o Graph rejeita no endpoint /communications/onlineMeetings. Jobs disparados por webhook derivam o organizador automaticamente a partir do @odata.id da notificação.

Runbook de rotina

Depois da primeira configuração

Rode estes na ordem:

hermes teams-pipeline validate
hermes teams-pipeline token-health --force-refresh
hermes teams-pipeline subscriptions

Depois dispare ou espere um evento de reunião real e confirme:

hermes teams-pipeline list
hermes teams-pipeline show <job-id>

Verificações diárias ou periódicas

• rode hermes teams-pipeline maintain-subscriptions --dry-run
• inspecione hermes teams-pipeline list --status failed
• confirme que o destino de entrega no Teams ainda é o chat ou canal correto

Antes de mudar URLs de webhook ou destinos de entrega

• atualize a URL pública de notificação ou a configuração de destino do Teams
• rode hermes teams-pipeline validate
• renove ou recrie as assinaturas afetadas
• confirme que os novos eventos chegam ao destino esperado

Triagem de falhas

Nenhum job está sendo criado

Verifique:

• o msgraph_webhook está habilitado
• a URL pública de notificação aponta para /msgraph/webhook
• o client state na assinatura bate com MSGRAPH_WEBHOOK_CLIENT_STATE
• as assinaturas ainda existem no lado remoto e não estão expiradas

Os jobs ficam em retry ou falham antes da sumarização

Verifique:

• permissões e disponibilidade da transcrição
• permissões de gravação e disponibilidade do artefato
• disponibilidade do ffmpeg, se a alternativa por gravação estiver habilitada
• saúde do token do Graph

Os resumos são produzidos mas não chegam ao Teams

Verifique:

• platforms.teams.enabled: true
• delivery_mode
• incoming_webhook_url no modo webhook
• chat_id ou team_id mais channel_id no modo Graph
• a configuração de autenticação do Teams, se você usa postagem via Graph

Reexecuções duplicadas ou inesperadas

Verifique:

• se você reexecutou um job manualmente com hermes teams-pipeline run
• se o registro no destino já existe para aquela reunião
• se você habilitou de propósito um caminho de reenvio na sua configuração local

Checklist para entrar no ar

• as credenciais do Graph existem e estão corretas
• o msgraph_webhook está habilitado e alcançável pela internet pública
• a MSGRAPH_WEBHOOK_CLIENT_STATE está definida e bate com as assinaturas
• a assinatura de transcrição foi criada
• a assinatura de gravação foi criada, se a alternativa por STT for necessária
• o ffmpeg está instalado, se a alternativa por gravação estiver habilitada
• o destino de entrega de saída no Teams está configurado e verificado
• os destinos Notion e Linear estão configurados só se realmente forem necessários
• hermes teams-pipeline validate devolve um retrato OK
• hermes teams-pipeline token-health --force-refresh passa
• o maintain-subscriptions está agendado (cron do Hermes, timer do systemd ou crontab — veja Automatizar a renovação de assinaturas). Sem isso, as assinaturas do Graph expiram em silêncio em 72 horas.
• um evento de reunião real, de ponta a ponta, produziu um job armazenado
• pelo menos um resumo chegou ao destino de entrega pretendido

Guia de decisão do modo de entrega

Modo	Use quando	Compromisso
incoming_webhook	você só precisa de postagem simples no Teams	configuração mais simples, menos controle
graph	você precisa postar em canal ou chat pelo Graph	mais controle, mais configuração de autenticação e de destino

Planilha do operador

Preencha isto antes da implantação:

Item	Valor
URL pública de notificação
ID do tenant no Graph
ID do cliente no Graph
Client state do webhook
Assinatura do recurso de transcrição
Assinatura do recurso de gravação
Modo de entrega do Teams
ID do chat ou time/canal do Teams
ID do banco de dados no Notion
ID do time no Linear
Caminho de armazenamento sobrescrito, se houver
Responsável pelas verificações diárias

Planilha de revisão de mudanças

Use isto antes de mudar a implantação:

Pergunta	Resposta
Vamos mudar a URL pública do webhook?
Vamos rotacionar as credenciais do Graph?
Vamos mudar o modo de entrega do Teams?
Vamos migrar para um novo chat ou canal do Teams?
As assinaturas precisam ser recriadas ou renovadas?
Precisamos de uma nova verificação de ponta a ponta?

Documentos relacionados

• Configuração de Reuniões do Teams
• Configuração do bot do Microsoft Teams

---