Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Yuanbao

Conecte o Hermes ao Yuanbao, a plataforma de mensagens corporativas da Tencent. O adaptador usa um gateway WebSocket para entrega de mensagens em tempo real e funciona tanto em conversas diretas (C2C) quanto em grupos.

informação

O Yuanbao é uma plataforma de mensagens corporativas usada principalmente dentro da Tencent e em ambientes empresariais. Ela usa WebSocket para comunicação em tempo real, autenticação baseada em HMAC, e aceita mídia rica, incluindo imagens, arquivos e mensagens de voz.

Pré-requisitos​

  • Uma conta no Yuanbao com permissão para criar bots
  • APP_ID e APP_SECRET do Yuanbao (fornecidos pelo administrador da plataforma)
  • Pacotes Python: websockets e httpx
  • Para suporte a mídia: aiofiles

Instale as dependências necessárias:

pip install websockets httpx aiofiles

Configuração​

1. Crie um bot no Yuanbao​

  1. Baixe o app do Yuanbao em https://yuanbao.tencent.com/
  2. No app, vá em PAI → My Bot e crie um bot novo
  3. Depois de criado, copie o APP_ID e o APP_SECRET

2. Rode o assistente de configuração​

O jeito mais fácil de configurar o Yuanbao é pelo assistente interativo:

hermes gateway setup

Escolha Yuanbao quando for perguntado. O assistente vai:

  1. Pedir o seu APP_ID
  2. Pedir o seu APP_SECRET
  3. Salvar a configuração automaticamente
dica

A URL do WebSocket e o domínio da API já vêm com padrões razoáveis embutidos. Você só precisa informar APP_ID e APP_SECRET para começar.

3. Configure as variáveis de ambiente​

Depois da configuração inicial, confira estas variáveis no ~/.hermes/.env:

# Obrigatórias
YUANBAO_APP_ID=seu-app-id
YUANBAO_APP_SECRET=seu-app-secret
YUANBAO_WS_URL=wss://api.yuanbao.example.com/ws
YUANBAO_API_DOMAIN=https://api.yuanbao.example.com

# Opcional: ID da conta do bot (normalmente obtido automaticamente do sign-token)
# YUANBAO_BOT_ID=seu-bot-id

# Opcional: ambiente de roteamento interno (ex.: test/staging/production)
# YUANBAO_ROUTE_ENV=production

# Opcional: canal principal para cron e notificações (formato: direct:<conta> ou group:<group_code>)
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"

# Opcional: restringir acesso (legado, veja Controle de acesso abaixo para políticas mais finas)
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. Suba o gateway​

hermes gateway

O adaptador conecta no gateway WebSocket do Yuanbao, se autentica com assinaturas HMAC e começa a processar mensagens.

Recursos​

  • Gateway WebSocket — comunicação bidirecional em tempo real
  • Autenticação HMAC — assinatura segura de requisições com APP_ID/APP_SECRET
  • Mensagens C2C — conversas diretas entre usuário e bot
  • Mensagens em grupo — conversas em grupos
  • Suporte a mídia — imagens, arquivos e mensagens de voz via COS (Cloud Object Storage)
  • Formatação Markdown — as mensagens são fatiadas automaticamente para respeitar os limites de tamanho do Yuanbao
  • Deduplicação de mensagens — evita processar a mesma mensagem duas vezes
  • Heartbeat/keep-alive — mantém a conexão WebSocket estável
  • Indicador de digitação — mostra "digitando…" enquanto o agente processa
  • Reconexão automática — lida com quedas do WebSocket usando backoff exponencial
  • Consultas de informações de grupo — busca detalhes do grupo e listas de membros
  • Suporte a figurinhas e emoji — envia figurinhas TIMFaceElem e emoji nas conversas
  • Suporte a histórico de conversa encaminhado do WeChat — quando alguém encaminha um pacote de histórico do WeChat para o Yuanbao, o adaptador decodifica os registros encaminhados (apelidos dos remetentes, texto e entradas multimídia, inclusive encaminhamentos aninhados) e os injeta na conversa, para o agente ler a thread encaminhada inteira
  • Auto-sethome — o primeiro usuário a escrever para o bot vira automaticamente o dono do canal principal
  • Aviso de resposta demorada — manda uma mensagem de espera quando o agente demora mais que o esperado

Opções de configuração​

Formatos de ID de conversa​

O Yuanbao usa identificadores com prefixo, conforme o tipo de conversa:

Tipo de conversaFormatoExemplo
Mensagem direta (C2C)direct:<account>direct:user123
Mensagem de grupogroup:<group_code>group:grp456

Envio de mídia​

O adaptador do Yuanbao cuida sozinho do envio de mídia via COS (Tencent Cloud Object Storage):

  • Imagens: aceita JPEG, PNG, GIF, WebP
  • Arquivos: aceita todos os tipos comuns de documento
  • Voz: aceita WAV, MP3, OGG

As URLs de mídia são validadas e baixadas automaticamente antes do envio, para prevenir ataques de SSRF.

Canal principal​

Use o comando /sethome em qualquer conversa do Yuanbao (DM ou grupo) para designá-la como canal principal. As tarefas agendadas (cron) entregam os resultados nesse canal.

Auto-sethome

Se não houver canal principal configurado, o primeiro usuário a escrever para o bot vira automaticamente o dono do canal principal. Se o canal principal atual for um grupo, a primeira DM o substitui por um canal direto.

Você também pode definir isso na mão no ~/.hermes/.env:

YUANBAO_HOME_CHANNEL=direct:user_account_id
# ou, para um grupo:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

Exemplo: definir o canal principal​

  1. Inicie uma conversa com o bot no Yuanbao
  2. Envie o comando: /sethome
  3. O bot responde: "Home channel set to [chat_name] with ID [chat_id]. Cron jobs will deliver to this location."
  4. Os próximos cron jobs e notificações vão para esse canal

Exemplo: entrega de cron job​

Crie um cron job:

/cron "0 9 * * *" Verifique o status do servidor

A saída agendada é entregue no seu canal principal do Yuanbao todo dia às 9h.

Dicas de uso​

Começar uma conversa​

Mande qualquer mensagem para o bot no Yuanbao:

olá

O bot responde na mesma thread da conversa.

Comandos disponíveis​

Todos os comandos padrão do Hermes funcionam no Yuanbao:

ComandoDescrição
/newComeça uma conversa nova
/model [provider:model]Mostra ou troca o modelo
/sethomeDefine esta conversa como canal principal
/statusMostra informações da sessão
/helpMostra os comandos disponíveis

Enviar arquivos​

Para mandar um arquivo para o bot, basta anexá-lo direto na conversa do Yuanbao. O bot baixa e processa o anexo automaticamente.

Você também pode mandar uma mensagem junto com o anexo:

Analise este documento, por favor

Receber arquivos​

Quando você pede ao bot que crie ou exporte um arquivo, ele envia o arquivo direto na sua conversa do Yuanbao.

Resolução de problemas​

O bot está online, mas não responde às mensagens​

Causa: a autenticação falhou durante o handshake do WebSocket.

Correção:

  1. Confira se APP_ID e APP_SECRET estão corretos
  2. Verifique se a URL do WebSocket está acessível
  3. Garanta que a conta do bot tem as permissões adequadas
  4. Revise os logs do gateway: tail -f ~/.hermes/logs/gateway.log

Erro "Connection refused"​

Causa: a URL do WebSocket está inacessível ou errada.

Correção:

  1. Confira o formato da URL do WebSocket (deve começar com wss://)
  2. Verifique a conectividade de rede com o domínio da API do Yuanbao
  3. Confirme que o firewall permite conexões WebSocket
  4. Teste a URL com: curl -I https://[YUANBAO_API_DOMAIN]

O envio de mídia falha​

Causa: as credenciais do COS são inválidas ou o servidor de mídia está inacessível.

Correção:

  1. Confira se o API_DOMAIN está correto
  2. Verifique se as permissões de upload de mídia estão habilitadas para o seu bot
  3. Garanta que o arquivo de mídia está acessível e não está corrompido
  4. Confira a configuração do bucket COS com o administrador da plataforma

As mensagens não chegam ao canal principal​

Causa: o formato do ID do canal principal está errado, ou o cron job não disparou.

Correção:

  1. Confira se YUANBAO_HOME_CHANNEL está no formato correto
  2. Teste com o comando /sethome para detectar o formato correto automaticamente
  3. Confira o agendamento do cron job com /status
  4. Verifique se o bot tem permissão de envio na conversa de destino

Desconexões frequentes​

Causa: a conexão WebSocket está instável ou a rede não é confiável.

Correção:

  1. Procure padrões de erro nos logs do gateway
  2. Aumente o tempo limite do heartbeat nas configurações de conexão
  3. Garanta uma conexão de rede estável com a API do Yuanbao
  4. Considere habilitar log detalhado: hermes gateway run -vv

Controle de acesso​

O Yuanbao aceita controle de acesso fino, tanto para DM quanto para conversas em grupo:

# Política de DM: open (padrão) | allowlist | disabled
YUANBAO_DM_POLICY=open
# IDs de usuário separados por vírgula que podem mandar DM ao bot (só usado quando DM_POLICY=allowlist)
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2

# Política de grupo: open (padrão) | allowlist | disabled
YUANBAO_GROUP_POLICY=open
# Códigos de grupo separados por vírgula que são permitidos (só usado quando GROUP_POLICY=allowlist)
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2

Isso também pode ser definido no config.yaml:

platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

Configuração avançada​

Fatiamento de mensagens​

O Yuanbao tem um tamanho máximo de mensagem. O Hermes fatia respostas grandes automaticamente, com uma divisão consciente de Markdown (respeita blocos de código, tabelas e limites de parágrafo).

Parâmetros de conexão​

Os parâmetros de conexão a seguir estão embutidos no adaptador, com padrões razoáveis:

ParâmetroValor padrãoDescrição
Tempo limite de conexão do WebSocket15 segundosTempo de espera pelo handshake WS
Intervalo de heartbeat30 segundosFrequência de ping para manter a conexão viva
Máximo de tentativas de reconexão100Número máximo de tentativas de reconexão
Backoff de reconexão1s → 60s (exponencial)Tempo de espera entre tentativas de reconexão
Intervalo de heartbeat de resposta2 segundosFrequência de envio do status RUNNING
Tempo limite de envio30 segundosTempo limite para mensagens WS de saída
observação

Hoje esses valores não são configuráveis por variáveis de ambiente. Eles estão ajustados para implantações típicas do Yuanbao.

Log detalhado​

Habilite o log de depuração para investigar problemas de conexão:

hermes gateway run -vv

Integração com outros recursos​

Cron jobs​

Agende tarefas que rodam no Yuanbao:

/cron "0 */4 * * *" Relate a saúde do sistema

Os resultados são entregues no seu canal principal.

Tarefas em segundo plano​

Rode operações longas sem travar a conversa:

/background Analise todos os arquivos do arquivamento

Mensagens entre plataformas​

Envie uma mensagem da CLI para o Yuanbao:

hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"