Hermes Agent para Zendesk: como conectá-lo com segurança (2026)

Por que olhei o Hermes no Zendesk

Meu trabalho na eesel é construir integrações, e o Zendesk é o helpdesk em que mais tempo passei. Não é por acaso: o marketplace do Zendesk foi um dos primeiros canais de crescimento da eesel, e há anos colocamos IA em filas reais do Zendesk. A lição que sempre volta é que o modelo é a parte fácil. O difícil é decidir no que a IA pode mexer e depois provar que ela está pronta antes que algum cliente descubra que não está.

O Hermes Agent é o agente de código aberto e auto-hospedado da Nous Research, com 252,613 estrelas no GitHub sob licença MIT. Cobri a pergunta geral em Hermes Agent for customer support e a versão do Freshdesk em Hermes Agent for Freshdesk. O Zendesk ganha um post próprio porque a resposta dele é moldada por um prazo que os outros helpdesks não têm.

O Hermes não traz nada específico do Zendesk. Seu catálogo curado de 68 servidores MCP não tem entrada do Zendesk, e não encontrei ninguém no Hacker News, Reddit ou X descrevendo uma configuração de Hermes com Zendesk. Tudo abaixo eu montei a partir da documentação dos dois fornecedores e do código da comunidade, que de qualquer forma é como você teria de construir.

O prazo do Zendesk que molda qualquer configuração

A maioria dos tutoriais de Hermes com helpdesks começa com "cole sua chave de API no .env." No Zendesk, esse conselho agora tem data de validade. O guia de migração para OAuth do Zendesk abre com isto: "Zendesk API tokens will be permanently deactivated on April 30, 2027."

As três fases, todas desse guia:

• 28 de julho de 2026. Qualquer token sem uso por 30 dias é desligado automaticamente, e contas criadas depois dessa data não podem usar tokens.
• 27 de outubro de 2026. Nenhuma conta pode criar um novo token de API, nem pela interface nem pela API.
• 30 de abril de 2027. Todos os tokens restantes param de funcionar.

A regra dos 30 dias é a traiçoeira para um agente: um cron do Hermes que você pausa durante as festas pode voltar a um token morto. E os motivos do Zendesk para aposentar os tokens são exatamente os riscos de entregar um a um agente: "No expiry", "No scope restrictions", e a referência de autenticação acrescenta que um token "can be used to impersonate anyone in the account, including admins."

O OAuth resolve isso, mas muda bastante o encanamento. Tokens de acesso duram 30 minutos por padrão e 48 horas no máximo, então um cabeçalho Authorization estático no config.yaml do Hermes não vai sobreviver. Algo precisa renovar o token. O Hermes consegue fazer OAuth sozinho com auth: oauth, mas só para servidores MCP remotos, e o Zendesk ainda não opera um para onde você possa apontá-lo. Na prática, a renovação acontece dentro do servidor MCP do Zendesk que você escolher, e escolher bem esse servidor é a maior parte do trabalho; meu guia de autenticação da API do Zendesk cobre os tipos de token com mais detalhes.

Quatro formas de conectar o Hermes ao Zendesk

Aqui estão todos os caminhos que encontrei, e quem guarda suas credenciais do Zendesk em cada um:

E o que você talvez esteja esperando: o Zendesk MCP Server. O Zendesk anunciou no Relate em 19 de maio de 2026, com uma nota de rodapé dizendo "Early access this summer." Não encontrei nenhum aviso de disponibilidade geral nas notas de versão de setembro de 2026 do Zendesk nem na lista de acesso antecipado. Não o confunda com o cliente MCP que chegou à disponibilidade geral em 10 de agosto de 2026, que permite que a IA do próprio Zendesk chame outros servidores e não ajuda o Hermes em nada.

Hoje eu escolheria o servidor da reminia. Ele foi reescrito para OAuth antes do prazo dos tokens e renova os tokens sozinho. O README dele também defende um ponto com o qual concordo: cada operador autoriza "with their own Zendesk login," então o Zendesk aplica exatamente as permissões que aplica na interface. A Swifteq é a mais fácil se você não quer hospedar nada, com 500 chamadas MCP gratuitas por mês por conta e depois 49 EUR por mês a partir de 1 de outubro de 2026, mas seus dados de tickets passam então por um terceiro. A rota por webhook é menos uma quarta opção e mais um gatilho: ela avisa ao Hermes que chegou um ticket, e o Hermes ainda precisa de um dos outros para agir.

Como configurar com segurança

Esta é a ordem que eu seguiria. Os passos parecem detalhistas, mas cada um existe por causa de um padrão específico do Zendesk ou do Hermes que pega você se for ignorado.

1. Dê ao Hermes o seu próprio usuário de agente leve

Este passo importa mais que os outros. A ferramenta create_ticket_comment da reminia aceita um parâmetro public, e no código-fonte dela esse parâmetro vem como True por padrão. Se o modelo esquecer de passar public: false, o "rascunho" vai ao cliente como resposta e é enviado por e-mail. O filtro de ferramentas do Hermes pode esconder uma ferramenta, mas não consegue fixar um argumento, então o filtro sozinho não vai te salvar.

O sistema de papéis do Zendesk consegue. Segundo a documentação de agentes leves do Zendesk: "Ticket comments by light agents are private, including the first comment of any tickets they create." Então, se o Hermes se autentica como agente leve, o Zendesk transforma todo comentário em nota interna, não importa o que o modelo envie.

Crie um usuário com um nome como "Hermes (draft only)", dê a ele o papel de agente leve e deixe-o ver todos os tickets (ou só os grupos para os quais deve redigir). Os assentos de agente leve estão incluídos na maioria dos planos Suite: até 50 no Growth, 100 no Professional, 1,000 no Enterprise e um complemento no Team. Duas ressalvas. O Zendesk proíbe usar a API para dar aos agentes leves mais do que eles recebem na interface, o que esta configuração não faz. E como um assento normalmente é o login de uma pessoa, eu confirmaria com seu representante do Zendesk que um usuário bot nele é aceitável; se não for, reserve orçamento para um assento completo e se apoie mais no passo 3. Os papéis e permissões do Zendesk cobrem o restante da configuração de papéis.

2. Registre um cliente OAuth com escopos restritos

No Admin Center, vá a Apps and integrations > APIs > OAuth clients e crie um cliente público, já que o servidor da reminia usa PKCE em vez de um segredo armazenado. Defina Allowed scopes, que o Zendesk descreve como um teto: "no token issued by this client can exceed these scopes." Para um bot de rascunhos, tickets:read tickets:write users:read hc:read basta. Se você pular os escopos, o Zendesk usa por padrão read write completo.

Depois entre como o agente leve do Hermes e execute uv run zendesk-auth uma vez. Esse é o único passo no navegador. Depois disso o servidor renova os tokens sozinho, rotaciona o refresh token a cada vez e mantém o arquivo com permissões 0600. Um segundo motivo para preferir esse fluxo, direto do README da reminia: tokens de client credentials "are attributed to the Zendesk user who created the OAuth client," geralmente um administrador, então toda nota pareceria escrita pelo seu admin. Meu passo a passo do app OAuth do Zendesk tem capturas do formulário do cliente.

3. Adicione o servidor e filtre suas ferramentas

O Hermes guarda servidores MCP em mcp_servers no ~/.hermes/config.yaml, e tools.include cria uma lista de permissão de ferramentas por servidor (documentação MCP do Hermes). Aqui está a minha montagem a partir do README da reminia e da sintaxe do Hermes. Não é um exemplo oficial de nenhum dos dois projetos:

mcp_servers:
  zendesk:
    command: "uv"
    args: ["--directory", "/opt/zendesk-mcp-server", "run", "zendesk"]
    env:
      ZENDESK_SUBDOMAIN: "yourcompany"
      ZENDESK_CLIENT_ID: "${ZENDESK_CLIENT_ID}"
      ZENDESK_OAUTH_SCOPES: "tickets:read tickets:write users:read hc:read"
    tools:
      include:
        - get_ticket
        - get_ticket_comments
        - get_tickets
        - create_ticket_comment

Deixar de fora update_ticket e create_ticket significa que o Hermes não pode mudar o status nem reatribuir, e também não pode abrir tickets novos, nada do que um bot de rascunhos precisa. O Hermes também tem uma chave trust por servidor. Em um servidor untrusted, "every write-capable tool call... requires user approval" (referência de configuração MCP), mas o padrão é full. Se alguém acompanha o Hermes no Slack, untrusted dá uma segunda checagem em cada nota.

4. Escolha um gatilho: chat, cron ou webhook

O Hermes precisa saber quando olhar um ticket:

• Sob demanda. Um agente cola o número de um ticket no Slack e pede um rascunho. Uma pessoa continua no processo o tempo todo.
• Consulta por cron. O agendador do Hermes bate a cada 60 segundos, e um script de pré-checagem pode imprimir {"wakeAgent": false} para que o modelo só rode quando houver algo novo (documentação de cron).
• Webhook. Um gatilho do Zendesk dispara um webhook para uma rota como https://your-server:8644/webhooks/zendesk.

O webhook é o mais rápido e também o mais trabalhoso, porque cada lado assina as requisições de um jeito. O Zendesk envia X-Zendesk-Webhook-Signature, um HMAC em base64 do timestamp mais o corpo (documentação do Zendesk). O Hermes rejeita qualquer requisição sem "a recognized signature header," e a lista dele é a do GitHub, a do GitLab, Standard Webhooks ou o próprio X-Webhook-Signature-V2 em hexadecimal (documentação de webhooks). Nenhum deles combina com o formato do Zendesk.

Existe uma ponte, embora eu não a tenha rodado de ponta a ponta, então encare-a como a minha leitura das duas documentações. Os webhooks do Zendesk suportam autenticação por chave de API, que envia um nome de cabeçalho e um valor que você escolhe. O esquema GitLab do Hermes é uma simples comparação de segredo em X-Gitlab-Token. Defina o cabeçalho de chave de API do webhook do Zendesk como X-Gitlab-Token com o segredo da sua rota como valor, e o Hermes deve aceitar. É mais fraco que um HMAC (sem proteção contra repetição), então mantenha a rota atrás de HTTPS.

Mais dois detalhes. As execuções por webhook começam com um conjunto de ferramentas padrão restrito, então a rota precisa de uma concessão manual toolsets: ["mcp-zendesk"] antes de poder ler tickets. E o Zendesk dá a cada webhook um timeout de 12 segundos e repete timeouts até cinco vezes (documentação de webhooks), então um host lento do Hermes pode ver o mesmo ticket mais de uma vez. A configuração coalesce no nível da rota do Hermes, que agrupa eventos repetidos do mesmo ticket em uma única execução, ajuda aqui.

5. Teste com tickets antigos antes de confiar nele

É aqui que eu gastaria mais tempo, e também onde o Hermes menos ajuda. Ele não tem modo de reprodução para rodar os tickets do mês passado e pontuar os rascunhos contra o que sua equipe realmente enviou.

Você pode construir um: puxe tickets resolvidos pela API de exportação incremental, rode o Hermes sobre eles em um perfil sandbox e compare. Exportações incrementais são limitadas a 10 requisições por minuto (limites de taxa), então vale puxar o conjunto de dados uma vez e guardá-lo em cache. Para saber como é "bom o bastante", veja meu guia sobre como treinar a IA com uma base de conhecimento.

Antes de entrar no ar, passe por isto. É a lista que eu gostaria de ver marcada antes de um bot tocar numa fila real:

Quanto o Hermes no Zendesk realmente custa

A licença é gratuita. Tudo ao redor dela, não.

O assento do bot. Um assento de agente leve se o seu plano incluir um; caso contrário, um assento de agente completo. A página de preços do Zendesk lista Support Team a $19, Suite Team a $55 e Suite Professional a $115 por agente por mês com cobrança anual. Meu detalhamento dos preços do Zendesk cobre os outros níveis.

Folga de API. O Hermes divide o limite de taxa da sua conta com todas as outras integrações. Um rascunho útil são cerca de quatro chamadas: o ticket, seus comentários, tickets parecidos e depois a nota.

Os limites vêm da página de limites de taxa do Zendesk. Em volumes de rascunho você não os atinge, embora o endpoint Update Ticket tenha seu próprio teto de 100 requisições por minuto por conta, e uma integração movimentada com a API do Zendesk em outro lugar pode comer a parte do Hermes.

Tokens do modelo e um servidor. Traga sua própria chave de provedor ou use uma assinatura do Nous Portal, mais um VPS pequeno para rodar o gateway e o servidor MCP.

A construção. É o item que as pessoas pulam. Um gerente de suporte de uma empresa de rastreamento de ônibus, com cerca de 200 tickets de Zendesk por mês, descreveu o objetivo para nós em uma chamada de vendas assim:

"create an application that will be able to handle 60% of the incoming zendesk tickets and know when to pull a real person in for better analysis and resolution."

Essa frase é um produto inteiro. Há o tratamento e a lógica de escalonamento, e depois a parte do "know when", que é a mais difícil. Com o Hermes, você a constrói e paga em horas de engenharia além de tokens e assentos. Meu detalhamento de construir ou comprar coloca números nisso.

Onde o Hermes no Zendesk deixa de funcionar

Tudo acima assume o formato de rascunhos. Quando você aponta o Hermes diretamente para os clientes do Zendesk, esbarra nas mesmas paredes que encontrei na análise geral de suporte:

• A memória é por perfil, não por solicitante. A memória integrada são MEMORY.md (2,200 caracteres) e USER.md (1,375), carregados em cada sessão que o perfil executa (documentação de memória). O que ele salvar do ticket de um cliente fica no prompt do próximo.
• Sem destino de entrega no Zendesk. As opções deliver de uma execução por webhook são plataformas de chat, e-mail ou um log. Devolver a resposta ao ticket sempre passa por uma chamada de ferramenta.
• Sem ensaio. Coberto acima, e é a lacuna que eu mais pesaria.
• O bot nativo já existe. Os agentes de IA do Zendesk estão incluídos em todo plano Suite, com 5 resoluções automatizadas por agente por mês no Team e 10 no Professional, depois $1.50 com compromisso ou $2.00 pay-as-you-go. Se você quer um bot voltado ao cliente dentro do Zendesk, o Hermes estaria reconstruindo o que o helpdesk já vende.

A descrição mais honesta da construção de rascunhos que encontrei veio de alguém fazendo isso em outro helpdesk:

"My current set up…Hermes agent logs into front with write only API token and reads whole context of customer thread. Then tries to look in our software for answers. (Unreliable right now). Then writes draft. This has been way harder than I expected. Been a side project for a while. Really focused on it right now. Goal - save CSR 80% of email writing time."

Nolan Gore (@TheNolanGore), X

Repare no formato: ler e consultar, depois redigir, com uma pessoa enviando. É a configuração que eu defenderia no Zendesk também. O "way harder than I expected" está na recuperação de informação e no nível de qualidade, não na conexão.

Hermes vs Zendesk AI vs eesel no Zendesk

Para o cenário mais amplo, meu levantamento best AI for Zendesk e a lista Zendesk AI alternatives aprofundam mais, enquanto Hermes Agent alternatives cobre agentes gerais. Se você está avaliando outras configurações centradas em modelo, Claude for Zendesk e ChatGPT for Zendesk levantam as mesmas dúvidas de conexão.

Você deve rodar o Hermes na sua fila do Zendesk?

Depois de ler as duas documentações e o código da comunidade, é aqui que eu chego.

Sim, se você tem um engenheiro que goste disso, o trabalho é redigir notas internas para agentes que as revisam, e você aceita ser dono de um cliente OAuth e de um conjunto de avaliação. O servidor da reminia, um assento de agente leve e uma lista include de quatro ferramentas é uma configuração que você consegue defender. O Hermes também serve bem como chatbot de suporte interno que sua própria equipe consulta no Slack.

Não, se você quer IA respondendo a clientes, ou precisa de um registro de cada ação da IA que um gerente de suporte consiga ler sem SSH. Mesma resposta se ninguém consegue manter um arquivo YAML durante a migração dos tokens. A análise de segurança do Zendesk que você faria em qualquer fornecedor vira uma que você faz no seu próprio servidor.

A conexão é um fim de semana de trabalho. O que sobra depois é o problema da alucinação da IA, mais o ensaio e as barreiras ao redor, e esse é o trabalho de verdade de colocar IA numa fila.

eesel para Zendesk

Se você olhou o Hermes porque quer IA trabalhando seus tickets do Zendesk, a eesel é a colega feita exatamente para isso. Você conecta o Zendesk por um link de aprovação, logado como agente, então não há token de API para migrar, e ela aprende com sua central de ajuda, macros e tickets antigos (documentação da eesel).

Veja como ela cobre as lacunas acima:

• Ensaio primeiro. A skill Simulation reproduz tickets antigos do Zendesk e pontua a diferença antes de responder a alguém.
• Você escolhe o nível de escrita. Deixar uma nota interna, segurar um rascunho para aprovação no painel ou enviar. Ela também pode etiquetar, atribuir a uma pessoa ou equipe e fechar, o que cobre também a triagem de tickets do Zendesk.
• Gatilhos do Zendesk integrados. Roda em toda mensagem do cliente, só na primeira, quando um ticket é fechado ou quando um colega digita @eesel em uma nota.
• Preço simples. Um ticket é 1 crédito, não importa o tamanho da conversa. Os planos começam em $299 por mês por 500 créditos, e o plano gratuito inclui 100 créditos.

E se metade do apelo do Hermes era o terminal, a eesel também tem isso. A CLI da eesel controla a mesma colega que você vê no painel, então o que for configurado em um aparece no outro. eesel integrations connect zendesk inicia a conexão (uma pessoa ainda a aprova no navegador), eesel integrations download start zendesk copia sua central de ajuda, macros e tickets, e eesel automations lista e liga o que o agente faz por gatilho. eesel integrations zendesk actions mostra cada ação com sua configuração de aprovação, então você vê de um terminal se ela pode enviar ou só redigir. Todo comando imprime JSON, o que significa que o Claude Code, o Cursor ou o Codex podem executar toda a configuração do Zendesk para você. Há mais no meu post CLI for customer support.

Fique com o Hermes para os trabalhos em que ele é ótimo. Para a fila do Zendesk, experimente a eesel primeiro com seus tickets reais.