Referência de Ferramentas Embutidas

Referência de Ferramentas Embutidas

Esta página documenta as ferramentas embutidas do Hermes, agrupadas por conjunto de ferramentas. A disponibilidade varia conforme a plataforma, as credenciais e os conjuntos habilitados.

Contagem rápida (registro atual): cerca de 86 ferramentas — 10 ferramentas de navegador (núcleo) + 2 ferramentas de navegador liberadas por CDP, 4 ferramentas de arquivo, 4 ferramentas do Home Assistant, 2 ferramentas de terminal (terminal, process), 12 ferramentas de interface do desktop (read_terminal, close_terminal, open_preview, close_preview, read_preview, drive_preview, annotate_preview, read_window_below, focus_pane, react_to_message, tour, tip — só em sessões do aplicativo de desktop), 2 ferramentas de web, 5 ferramentas do Feishu, 7 ferramentas do Spotify (registradas pelo plugin spotify que já vem no pacote), 5 ferramentas do Yuanbao, 12 ferramentas de kanban (registradas quando o despachante do kanban cria o agente), 3 ferramentas de projeto (sessões de desktop/interface gráfica), 2 ferramentas do Discord, 3 ferramentas de vídeo (video_generate, xai_video_edit, xai_video_extend) e um punhado de ferramentas avulsas (memory, clarify, delegate_task, execute_code, cronjob, session_search, skill_view/skill_manage/skills_list, text_to_speech, image_generate, vision_analyze, video_analyze, todo, computer_use, x_search).

Ferramentas MCP

Além das ferramentas embutidas, o Hermes pode carregar ferramentas dinamicamente de servidores MCP. As ferramentas MCP aparecem com o prefixo mcp__<servidor>__ (por exemplo, mcp__github__create_issue para o servidor MCP github). Veja Integração MCP para a configuração.

Conjunto browser

Ferramenta	Descrição	Ambiente necessário
browser_back	Volta para a página anterior no histórico do navegador. Exige que browser_navigate tenha sido chamado antes.	—
browser_click	Clica num elemento identificado pelo ID de referência do snapshot (por exemplo, '@e5'). Os IDs de referência aparecem entre colchetes na saída do snapshot. Exige que browser_navigate e browser_snapshot tenham sido chamados antes.	—
browser_console	Obtém a saída do console do navegador e os erros de JavaScript da página atual. Devolve as mensagens de console.log/warn/error/info e as exceções JS não capturadas. Use para detectar erros silenciosos de JavaScript, chamadas de API que falharam e avisos da aplicação. Exig…	—
browser_get_images	Obtém a lista de todas as imagens da página atual, com URLs e texto alternativo. Útil para encontrar imagens a analisar com a ferramenta de visão. Exige que browser_navigate tenha sido chamado antes.	—
browser_navigate	Navega até uma URL no navegador. Inicializa a sessão e carrega a página. Precisa ser chamado antes das outras ferramentas de navegador. Para buscas simples de informação, prefira web_search ou web_extract (mais rápidos e baratos). Use as ferramentas de navegador quando precisar…	—
browser_press	Pressiona uma tecla do teclado. Útil para enviar formulários (Enter), navegar (Tab) ou usar atalhos. Exige que browser_navigate tenha sido chamado antes.	—
browser_scroll	Rola a página numa direção. Use para revelar mais conteúdo que possa estar abaixo ou acima da janela de visualização atual. Exige que browser_navigate tenha sido chamado antes.	—
browser_snapshot	Obtém um snapshot em texto da árvore de acessibilidade da página atual. Devolve os elementos interativos com IDs de referência (como @e1, @e2) para browser_click e browser_type. full=false (padrão): visão compacta com os elementos interativos. full=true: visão comp…	—
browser_type	Digita texto num campo de entrada identificado pelo ID de referência. Limpa o campo primeiro e depois digita o novo texto. Exige que browser_navigate e browser_snapshot tenham sido chamados antes.	—
browser_vision	Tira uma captura de tela da página atual para você inspecioná-la visualmente. Use quando precisar entender a aparência da página — especialmente em CAPTCHAs, desafios de verificação visual, layouts complexos ou casos em que o snapshot de texto perde informação visual importante. Em modelos com visão nativa, a captura é anexada diretamente; caso contrário, recorre a um modelo auxiliar de visã…	—

Conjunto browser (ferramentas liberadas por CDP)

Estas duas ferramentas ficam no conjunto browser, mas só se registram quando um endpoint do Chrome DevTools Protocol está acessível no início da sessão — via /browser connect, a configuração browser.cdp_url, uma sessão do Browserbase ou o Camofox.

Ferramenta	Descrição	Ambiente necessário
browser_cdp	Envia um comando cru do Chrome DevTools Protocol. Válvula de escape para operações de navegador que as ferramentas browser_* de mais alto nível não cobrem. Veja https://chromedevtools.github.io/devtools-protocol/	endpoint CDP
browser_dialog	Responde a um diálogo nativo de JavaScript (alert / confirm / prompt / beforeunload). Chame browser_snapshot antes — os diálogos pendentes aparecem no campo pending_dialogs dele. Depois chame browser_dialog(action='accept'|'dismiss').	endpoint CDP

Conjunto clarify

Ferramenta	Descrição	Ambiente necessário
clarify	Faz uma pergunta ao usuário quando você precisa de esclarecimento, retorno ou uma decisão antes de seguir. Suporta três modos: 1. Múltipla escolha de seleção única — até 4 opções; o usuário escolhe uma ou digita a própria resposta numa 5ª opção, 'Outra'. 2. Múltipla escolha de seleção múltipla — multi_select=true mostra caixas de seleção e devolve uma lista das opções escolhidas. 3. Aberta — sem opções; o usuário digita uma resposta livre. As opções são ordenadas da melhor para a pior, então a primeira recebe o rótulo (Recommended) em toda superfície e é o destaque padrão; o rótulo é só apresentação e é removido da resposta que o agente lê. Na CLI clássica, a seleção múltipla usa caixas alternadas com Espaço; nas plataformas de mensagens sem interface nativa de caixas de seleção, o usuário responde com números separados por vírgula ou espaço (por exemplo, "1, 3") ou com o texto da opção.	—

Fazer várias perguntas de uma vez

A ferramenta clarify também aceita um array questions (de 2 a 5 perguntas independentes, cada uma com as próprias choices e multi_select), para que o agente junte várias necessidades de esclarecimento num único prompt em vez de perguntar em sequência. O resultado é um array responses na mesma ordem, com o id de cada pergunta (quando fornecido) devolvido junto.

Comportamento por superfície:

• Desktop mostra todas as perguntas num único cartão. As escolhas e as respostas digitadas ficam preparadas localmente, e um único botão Confirm and continue (habilitado assim que todas as perguntas têm resposta) envia o lote inteiro. As respostas preparadas continuam editáveis até essa confirmação. Pular cancela o lote todo.
• TUI e CLI mostram uma lista compacta de status (✓ respondida / ▸ ativa / · pendente), com as opções expandidas só na pergunta ativa. Enter fixa a resposta ativa e pula para a próxima pergunta sem resposta; Tab move entre as perguntas para responder em qualquer ordem; Esc cancela o lote.
• Plataformas de mensagens (Telegram, Discord, …) recorrem a perguntar uma de cada vez, pelo prompt de pergunta única já existente. Se o usuário parar de responder, as perguntas restantes não são enviadas.

Se o prompt expirar no meio do caminho, as respostas que o usuário já fixou são mantidas: o resultado da ferramenta traz essas respostas mais "timed_out": true, com as entradas sem resposta em branco, para que o agente diferencie uma omissão deliberada de um usuário ausente.

Conjunto code_execution

Ferramenta	Descrição	Ambiente necessário
execute_code	Roda um script Python que pode chamar as ferramentas do Hermes programaticamente. Use quando precisar de 3 ou mais chamadas de ferramenta com lógica de processamento entre elas, precisar filtrar ou reduzir saídas grandes de ferramenta antes que entrem no seu contexto, ou precisar de ramificação condicional (…	—

Conjunto cronjob

Ferramenta	Descrição	Ambiente necessário
cronjob	Gerenciador unificado de tarefas agendadas. Use action="create", "list", "update", "pause", "resume", "run" ou "remove" para gerenciar as tarefas. Suporta tarefas apoiadas em skills, com uma ou mais skills anexadas, e skills=[] na atualização remove as skills anexadas. As execuções de cron acontecem em sessões novas, sem o contexto da conversa atual.	—

Conjunto delegation

Ferramenta	Descrição	Ambiente necessário
delegate_task	Cria subagentes em contextos isolados; cada um recebe a própria conversa, sessão de terminal e conjunto de ferramentas, e só o resumo final volta para você. Forneça 'goal' para uma tarefa única ou 'tasks' para um lote em paralelo (limites e regras de aninhamento…	—

Conjunto feishu_doc

Restrito ao tratador de resposta inteligente de comentários em documentos do Feishu (gateway/platforms/feishu_comment.py). Não fica exposto no hermes-cli nem no adaptador comum de chat do Feishu.

Ferramenta	Descrição	Ambiente necessário
feishu_doc_read	Lê o conteúdo completo em texto de um documento do Feishu/Lark (Docx, Doc ou Sheet), a partir do file_type e do token dele.	Credenciais do app Feishu

Conjunto feishu_drive

Restrito ao tratador de comentários em documentos do Feishu. Conduz as operações de leitura e escrita de comentários em arquivos do drive.

Ferramenta	Descrição	Ambiente necessário
feishu_drive_add_comment	Adiciona um comentário de nível superior num documento ou arquivo do Feishu/Lark.	Credenciais do app Feishu
feishu_drive_list_comments	Lista os comentários de documento inteiro num arquivo do Feishu/Lark, do mais recente para o mais antigo.	Credenciais do app Feishu
feishu_drive_list_comment_replies	Lista as respostas de uma discussão específica de comentário do Feishu (de documento inteiro ou de trecho selecionado).	Credenciais do app Feishu
feishu_drive_reply_comment	Publica uma resposta numa discussão de comentário do Feishu, com menção @ opcional.	Credenciais do app Feishu

Conjunto file

Ferramenta	Descrição	Ambiente necessário
patch	Edições pontuais de buscar e substituir em arquivos. Use no lugar de sed/awk no terminal. Usa correspondência aproximada (9 estratégias), então pequenas diferenças de espaço em branco ou indentação não quebram a edição. Devolve um diff unificado. Roda verificações de sintaxe automaticamente depois de editar…	—
read_file	Lê um arquivo de texto com números de linha e paginação. Use no lugar de cat/head/tail no terminal. Formato de saída: 'LINE_NUM|CONTENT'. Sugere nomes de arquivo parecidos quando não encontra. Use offset e limit em arquivos grandes. Leituras acima de cerca de 100 mil caracteres são truncadas numa fronteira de linha e devolvem um next_offset. Notebooks Jupyter (.ipynb), documentos do Word (.docx) e planilhas do Excel (.xlsx) sã…	—
search_files	Busca no conteúdo dos arquivos ou encontra arquivos pelo nome. Use no lugar de grep/rg/find/ls no terminal. Apoiado no ripgrep, mais rápido que os equivalentes do shell. Busca de conteúdo (target='content'): busca por regex dentro dos arquivos. Modos de saída: correspondências completas com linh…	—
write_file	Escreve conteúdo num arquivo, substituindo por completo o conteúdo existente. Use no lugar de echo/cat com heredoc no terminal. Cria os diretórios pais automaticamente. SOBRESCREVE o arquivo inteiro — use 'patch' para edições pontuais. Roda verificações de sintaxe automáticas em .py/.json/.yaml/.toml e em outras linguagens com linter; só os NOVOS erros introduzidos pela escrita são mostrados.	—

Conjunto homeassistant

Ferramenta	Descrição	Ambiente necessário
ha_call_service	Chama um serviço do Home Assistant para controlar um dispositivo. Use ha_list_services para descobrir os serviços disponíveis e os parâmetros de cada domínio.	—
ha_get_state	Obtém o estado detalhado de uma única entidade do Home Assistant, incluindo todos os atributos (brilho, cor, temperatura definida, leituras de sensor etc.).	—
ha_list_entities	Lista as entidades do Home Assistant. Opcionalmente, filtra por domínio (light, switch, climate, sensor, binary_sensor, cover, fan etc.) ou por nome de área (sala, cozinha, quarto etc.).	—
ha_list_services	Lista os serviços (ações) disponíveis do Home Assistant para controle de dispositivos. Mostra quais ações podem ser executadas em cada tipo de dispositivo e quais parâmetros elas aceitam. Use para descobrir como controlar os dispositivos encontrados por ha_list_entities.	—

Conjunto computer_use

Ferramenta	Descrição	Ambiente necessário
computer_use	Controle do desktop em segundo plano pelo cua-driver — capturas de tela (SOM / visão / AX), clique / arrastar / rolar / digitar / tecla / esperar, list_apps, focus_app. NÃO rouba o cursor nem o foco de teclado do usuário. Funciona com qualquer modelo capaz de usar ferramentas. macOS, Windows e Linux.	cua-driver no $PATH (instale via hermes tools).

observação

As ferramentas do Honcho (honcho_profile, honcho_search, honcho_context, honcho_reasoning, honcho_conclude) não são mais embutidas. Elas estão disponíveis pelo plugin de provedor de memória Honcho, em plugins/memory/honcho/. Veja Provedores de Memória para instalação e uso.

Conjunto image_gen

Ferramenta	Descrição	Ambiente necessário
image_generate	Gera imagens a partir de prompts de texto (texto-para-imagem) ou edita/transforma uma imagem existente (imagem-para-imagem) pelo backend que o usuário configurou (FAL.ai, OpenAI, autenticação do OpenAI Codex, xAI, Krea). Passe image_url para editar uma imagem e reference_image_urls para referências de estilo; omita os dois para texto-para-imagem. O modelo é definido pelo usuário e o agente não pode escolhê-lo. Devolve uma única URL de imagem ou um caminho local.	FAL_KEY / OPENAI_API_KEY / OAuth do Codex / OAuth da xAI / KREA_API_KEY

Conjunto kanban

Registrado quando o agente (a) é criado pelo despachante do kanban (com a variável HERMES_KANBAN_TASK definida) ou (b) roda num perfil que habilita explicitamente o conjunto kanban. Os trabalhadores com escopo de tarefa usam as ferramentas de ciclo de vida da tarefa atribuída a eles; os perfis orquestradores ganham, além disso, ferramentas de roteamento de quadro, como kanban_list e kanban_unblock. Veja Kanban Multiagente para o fluxo completo.

Ferramenta	Descrição	Ambiente necessário
kanban_show	Mostra a tarefa de kanban ativa atribuída a este trabalhador (título, descrição, comentários, dependências).	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_list	Lista as tarefas do quadro com filtros. Só para orquestradores; fica escondida dos trabalhadores criados pelo despachante.	perfil com o conjunto kanban
kanban_complete	Marca a tarefa atual como concluída, com um payload estruturado de passagem de bastão (resultados, artefatos, próximos passos).	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_block	Bloqueia a tarefa atual numa pergunta para o usuário — o despachante pausa, mostra a pergunta e retoma assim que uma pessoa responde.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_request_review	Passa a implementação para quem revisa, com summary, metadata estruturado opcional e um perfil de revisor opcional. Move a mesma tarefa para review; não é um bloqueio e não afeta a contagem de laços de bloqueio.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_request_changes	Veredito de quem revisa numa execução de revisão ativamente assumida. Encerra a execução de revisão, reaplica o travamento pelos pais e devolve a tarefa a quem a implementou, sem gastar um bloqueio.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_heartbeat	Envia um sinal de progresso durante uma operação demorada, para que o despachante saiba que o trabalhador continua vivo.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_comment	Adiciona um comentário à discussão da tarefa sem mudar o estado dela — útil para expor achados intermediários.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_create	Abre tarefas filhas a partir da tarefa atual. Usada por orquestradores e por trabalhadores que geram desdobramentos.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_link	Liga tarefas com uma aresta de dependência pai → filho.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_unblock	Move uma tarefa bloqueada para ready quando todos os pais estão concluídos, ou para todo enquanto algum pai continua aberto. Só para orquestradores; fica escondida dos trabalhadores criados pelo despachante.	perfil com o conjunto kanban
kanban_attach	Anexa um arquivo a uma tarefa passando os bytes dele em linha (base64). Guardado como anexo real no diretório de anexos da tarefa, com limite de 25 MB.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_attach_url	Anexa um arquivo a uma tarefa por URL — o Hermes baixa o arquivo no servidor e o guarda como anexo real (com limite de 25 MB). Só URLs http/https.	HERMES_KANBAN_TASK ou o conjunto kanban
kanban_attachments	Lista os arquivos anexados a uma tarefa: id, nome do arquivo, content_type, tamanho, quem enviou e o caminho absoluto em disco.	HERMES_KANBAN_TASK ou o conjunto kanban

Conjunto project

Ferramentas para conduzir os Projetos do desktop — espaços de trabalho nomeados, com várias pastas. Registradas quando o conjunto project está habilitado (principalmente nas superfícies do aplicativo de desktop e do painel).

Ferramenta	Descrição	Ambiente necessário
project_create	Cria um Projeto de desktop (um espaço de trabalho nomeado) e move esta conversa para dentro dele. Passe path para ancorá-lo a um repositório ou pasta.	—
project_list	Lista os Projetos de desktop e indica qual está ativo.	—
project_switch	Move esta conversa para um Projeto existente (por nome, slug ou id); move o espaço de trabalho da sessão para a pasta principal do projeto.	—

Conjunto memory

Ferramenta	Descrição	Ambiente necessário
memory	Salva informação importante numa memória persistente que sobrevive entre sessões. A sua memória aparece no seu prompt de sistema no início da sessão — é assim que você lembra coisas sobre o usuário e sobre o seu ambiente entre conversas. QUANDO SAL…	—

Conjunto session_search

Ferramenta	Descrição	Ambiente necessário
session_search	Busca em sessões passadas guardadas no banco local de sessões, ou percorre uma delas. Recuperação apoiada em FTS5; devolve mensagens reais do banco (sem chamadas de LLM). Quatro formatos: descoberta (passe query), rolagem (passe session_id + around_message_id), leitura (passe só session_id) e navegação (sem argumentos).	—

Conjunto skills

Ferramenta	Descrição	Ambiente necessário
skill_manage	Gerencia skills (criar, atualizar, apagar). Skills são a sua memória procedural — abordagens reutilizáveis para tipos de tarefa recorrentes. As novas skills vão para ~/.hermes/skills/; as skills existentes podem ser modificadas onde quer que estejam. Ações: create (SKILL.m…	—
skill_view	As skills permitem carregar informação sobre tarefas e fluxos de trabalho específicos, além de scripts e modelos. Carrega o conteúdo completo de uma skill ou acessa os arquivos ligados a ela (referências, modelos, scripts). A primeira chamada devolve o conteúdo do SKILL.md mais um…	—
skills_list	Lista as skills disponíveis (nome + descrição). Use skill_view(name) para carregar o conteúdo completo.	—

Conjunto terminal

Ferramenta	Descrição	Ambiente necessário
process	Gerencia processos em segundo plano iniciados com terminal(background=true). Ações: 'list' (mostra todos), 'poll' (verifica status + saída nova), 'log' (saída completa com paginação), 'wait' (bloqueia até terminar ou expirar), 'kill' (encerra), 'write' (env…	—
terminal	Executa comandos de shell num ambiente Linux. O sistema de arquivos persiste entre as chamadas. Defina background=true para servidores de longa duração. Defina notify_on_complete=true (junto com background=true) para receber uma notificação automática quando o processo terminar — sem precisar ficar consultando. NÃO use cat/head/tail — use read_file. NÃO use grep/rg/find — use search_files.	—

Conjunto desktop_ui

Habilitado para sessões cuja origem é o aplicativo de desktop do Hermes, em qualquer backend a que ele esteja conectado (local, SSH, URL ou Hermes Cloud). Ausente em sessões de CLI, TUI, mensagens e cron.

Ferramenta	Descrição	Ambiente necessário
read_terminal	Lê o que está aparecendo no painel de terminal embutido da interface de desktop do Hermes (o shell embutido ao lado desta conversa).	—
close_terminal	Fecha a aba de terminal somente leitura de um processo em segundo plano na interface de desktop do Hermes. NÃO encerra o processo — apenas descarta a aba/visão; use process(action='kill') para pará-lo.	—
open_preview	Abre uma URL da web, uma URL de servidor de desenvolvimento local ou um caminho de arquivo no painel de pré-visualização ao lado da conversa, no aplicativo de desktop do Hermes.	—
close_preview	Fecha o painel de pré-visualização ao lado da conversa, ou uma aba dentro dele. Omita url para fechar o painel inteiro; passe uma URL ou caminho de arquivo para fechar aquela aba.	—
read_preview	Lê o que está aparecendo no painel de pré-visualização da interface de desktop do Hermes — o texto da página do navegador embutido (URL + título + texto renderizado, paginável com start/count) ou a identidade de uma aba de arquivo/artefato.	—
drive_preview	Interage com a página aberta no navegador embutido: elements inventaria o que é clicável e digitável (cada item com uma referência que o nomeia, como btn-sign-in ou inp-email, mais papel, rótulo e valor), e então click, hover, type, scroll e press agem sobre uma referência, enquanto back/forward/reload conduzem o histórico do painel. O ponteiro e o teclado são entrada real, então menus de passagem do mouse abrem. Uma referência dura até a página navegar, inclusive através de uma nova renderização que reconstrua o elemento, então, depois do primeiro inventário, cada ação responde só com um delta — o que foi adicionado, removido, alterado ou reassociado — em vez da página inteira de novo.	—
annotate_preview	Contorna um elemento no navegador embutido e deixa a marca até que ela seja removida — a contraparte deliberada das pistas passageiras que o drive_preview desenha enquanto trabalha. add marca uma referência com um rótulo curto opcional, remove tira uma marca e clear tira todas. As marcas acompanham o elemento e somem com ele, então uma navegação as limpa.	—
read_window_below	Identifica a janela do sistema operacional que está logo abaixo da janela de desktop do Hermes — nome do app, título e limites (só metadados, nunca pixels). No macOS, os títulos dos outros aplicativos aparecem apenas quando a Gravação de Tela já foi autorizada; a ferramenta nunca pede essa permissão.	—
focus_pane	Revela e foca um painel do aplicativo de desktop do Hermes (chat, arquivos, terminal, revisão, sessões).	—
react_to_message	Reage a uma mensagem com um único emoji, no estilo tapback do iMessage. Habilitação explícita em Settings → Appearance (display.message_reactions).	—
tour	Dá um tour guiado ao vivo: escurece a tela, destaca um elemento e anexa um balão narrado (driver.js). Funciona na interface do próprio aplicativo Hermes e em qualquer página aberta no painel de pré-visualização; targets descobre o que está na tela, show narra passo a passo e start entrega ao usuário os controles de avançar e voltar.	—
tip	Aponta para um único elemento com um pequeno balão de destaque e uma seta — o irmão discreto do tour, sem escurecer a tela, sem holofote e sem avançar/voltar. Usa as mesmas âncoras data-tour e a mesma chamada de descoberta tour(action='targets').	—

Tours

A ferramenta tour descobre os próprios alvos — chame action='targets' e ela devolve todo elemento endereçável na tela, com um seletor, um rótulo e uma marca stable. Os seletores estáveis se apoiam em identidade (data-tour, id, data-testid, aria-label) e sobrevivem a uma nova renderização; os caminhos posicionais com nth-child não sobrevivem, então os estáveis vêm primeiro na ordenação e devem ser preferidos.

Para dar a um elemento uma âncora durável sua, marque-o assim:

<div data-tour="composer">…</div>

As âncoras são aplicadas no primitivo, não no ponto de uso, então uma única edição nomeia todas as instâncias. As que já existem:

Âncora	O que ela nomeia
overlay-nav	a navegação da esquerda de qualquer sobreposição de rota (configurações, cron, perfis, agentes)
nav-<id>	uma linha dessa navegação — nav-models, nav-appearance, …
field-<schemaKey>	uma linha de configuração, pela chave de config dela — field-model, field-provider, …
page-tabs	as abas de filtro de qualquer página PageSearchShell (artefatos, skills, …)
artifact-card	um cartão de artefato na grade

Ao acrescentar uma superfície, marque o primitivo compartilhado dela do mesmo jeito, em vez de marcar tela por tela — isso mantém o vocabulário do tour enxuto e impede que os seletores apodreçam.

O mesmo motor sustenta os tours curados (não feitos pelo agente) no aplicativo de desktop, então um recurso pode entregar o próprio passo a passo:

import { startTour, showTourStep, stopTour } from '@/lib/tour'

startTour([
  { selector: '[data-tour="composer"]', title: 'Redação', text: 'Digite aqui.' },
  { selector: '[data-tour="files"]', title: 'Arquivos', text: 'Navegue pelo seu projeto.' }
])

Um passo também pode levar o aplicativo até onde o alvo dele fica, e o tour recoloca tudo no lugar quando termina:

startTour([
  { navigate: '/artifacts', selector: '[data-tour="page-tabs"]', title: 'Filtros', text: '…' },
  { pane: 'sessions', selector: '[data-slot="sidebar"]', title: 'Sessões', text: '…' }
])

navigate recebe um caminho de rota e pane, o nome de um painel do desktop. Os dois rodam quando o passo é iniciado, os alvos que montam tarde são aguardados, e fechar o tour — por qualquer caminho, inclusive com Esc — devolve você ao ponto onde ele começou.

Passe 'preview' como segundo argumento para rodar sobre a página do painel de pré-visualização em vez do aplicativo.

Dicas

Uma dica é um passo de tour sem a produção toda: um balão, uma seta, sem escurecimento e nada para paginar. É o peso certo para uma frase que ficaria mais clara com um dedo apontando para aquilo de que ela fala — "o nome do modelo é um botão" — quando escurecer o aplicativo inteiro não ficaria.

A ferramenta tip aceita os mesmos seletores que o tour(action='targets') relata, então a descoberta é uma só chamada para as duas, e as âncoras duráveis data-tour acima nomeiam alvos para qualquer uma delas. Só uma dica fica na tela por vez; uma nova substitui a anterior.

O aplicativo também pode mostrar as próprias dicas, percorrendo em ordem um catálogo embutido de recursos. Essa metade vem ligada por padrão e é desligada em Settings → Appearance, e o ritmo dela é o de dicas de tela de carregamento de jogo, não o de uma notificação: alguns minutos depois de abrir, no mínimo, depois no máximo uma a cada seis horas, e só num momento de ociosidade genuína. Fechar uma dessas dicas no ✕ aposenta aquela dica para sempre, e a mesma linha de configuração as traz de volta. A ferramenta não está sujeita a esse interruptor — como o tour, ela roda em resposta à conversa, não na ociosidade. Ela compartilha o tempo de espera, então uma dica vinda do Hermes também garante ao usuário seis horas de silêncio da rotação.

Conjunto todo

Ferramenta	Descrição	Ambiente necessário
todo	Gerencia a sua lista de tarefas na sessão atual. Use em tarefas complexas com 3 ou mais passos, ou quando o usuário passar várias tarefas. Chame sem parâmetros para ler a lista atual. Escrita: - Forneça o array 'todos' para criar/atualizar itens - merge=…	—

Conjunto vision

Ferramenta	Descrição	Ambiente necessário
vision_analyze	Analisa imagens com visão por IA. Em modelos principais capazes de visão, devolve os pixels crus da imagem como resultado multimodal de ferramenta, para que o modelo os veja nativamente no turno seguinte. Em modelos principais só de texto, recorre a um modelo auxiliar de visão que descreve a imagem e devolve a descrição como texto. A assinatura da ferramenta é idêntica nos dois casos.	—

Conjunto video

Conjunto de habilitação explícita (não carregado no conjunto padrão do hermes-cli). Adicione com --toolsets video ou inclua video na sua configuração toolsets:.

Ferramenta	Descrição	Ambiente necessário
video_analyze	Analisa o conteúdo de um vídeo a partir de uma URL ou caminho de arquivo — legendas, divisão em cenas, marcas de tempo importantes e descrições visuais.	—

Conjunto video_gen

Conjunto de habilitação explícita (não carregado no conjunto padrão do hermes-cli). Adicione com --toolsets video_gen ou habilite em hermes tools → Video Generation, que também conduz você na escolha de um backend.

Os backends vêm como plugins em plugins/video_gen/<nome>/:

• xAI Grok-Imagine — texto-para-vídeo e imagem-para-vídeo (OAuth do SuperGrok ou XAI_API_KEY).
• FAL.ai — Veo 3.1, Pixverse v6, Kling O3 (exige FAL_KEY).

A única ferramenta video_generate cobre as duas modalidades — passe image_url para animar uma imagem parada, omita para gerar só a partir de texto. O backend ativo encaminha automaticamente para o endpoint certo. A descrição da ferramenta é reconstruída no início da sessão para refletir as capacidades reais do backend ativo (modalidades, proporções, resoluções, faixa de duração, máximo de imagens de referência, suporte a áudio). Veja Plugins de Geração de Vídeo para escrever um backend.

Ferramenta	Descrição	Ambiente necessário
video_generate	Gera um vídeo a partir de um prompt de texto (texto-para-vídeo) ou anima uma imagem parada (imagem-para-vídeo) usando o backend de geração de vídeo configurado pelo usuário. Passe image_url para animar aquela imagem; omita para gerar só a partir de texto. O backend encaminha automaticamente para o endpoint certo. Devolve uma URL HTTP ou um caminho absoluto de arquivo no campo video.	Plugin video_gen ativo + a credencial dele (por exemplo, XAI_API_KEY, FAL_KEY)
xai_video_edit	Edita um vídeo existente com o xAI Imagine. Específica do provedor (separada de video_generate). video_url precisa ser a URL HTTPS pública do MP4 de um resultado anterior do Imagine.	Credenciais do xAI Imagine (OAuth do SuperGrok ou XAI_API_KEY)
xai_video_extend	Estende um vídeo existente com o xAI Imagine. Específica do provedor (separada de video_generate). video_url precisa ser a URL HTTPS pública do MP4 de um resultado anterior do Imagine.	Credenciais do xAI Imagine (OAuth do SuperGrok ou XAI_API_KEY)

Conjunto web

Ferramenta	Descrição	Ambiente necessário
web_search	Busca informação na web. Devolve até 5 resultados por padrão, com títulos, URLs e descrições. Aceita um limit opcional (de 1 a 100, padrão 5). A consulta é repassada ao backend configurado, então operadores como site:domain, filetype:pdf, intitle:word, -term e "exact phrase" podem funcionar quando o backend os suporta.	EXA_API_KEY ou PARALLEL_API_KEY ou FIRECRAWL_API_KEY ou TAVILY_API_KEY
web_extract	Extrai conteúdo de URLs de páginas web. Devolve o conteúdo limpo da página em markdown/texto (sem resumo por LLM — rápido). Também funciona com URLs de PDF (artigos do arxiv, documentos) — passe o link do PDF diretamente. Páginas dentro do orçamento de caracteres (15000 por padrão) voltam inteiras; páginas maiores voltam com uma janela de início+fim e um rodapé apontando para o texto completo salvo em disco. Máximo de 5 URLs por chamada.	EXA_API_KEY ou PARALLEL_API_KEY ou FIRECRAWL_API_KEY ou TAVILY_API_KEY

Conjunto x_search

Ferramenta	Descrição	Ambiente necessário
x_search	Busca posts, perfis e discussões do X (Twitter) usando a ferramenta x_search embutida da API Responses da xAI. Descoberta pública somente leitura no X, para discussões, reações ou afirmações atuais no X público (não para páginas web em geral). Não publica, responde, curte, manda mensagem direta, envia mídia, apaga nem inspeciona a conta autenticada do X — isso exige uma superfície autenticada separada da API do X (por exemplo, a skill xurl). Desligada por padrão — habilite em hermes tools → 🐦 X (Twitter) Search. O schema só é registrado quando há credenciais da xAI configuradas (liberado por check_fn).	XAI_API_KEY ou login OAuth do xAI Grok (SuperGrok / Premium+)

Conjunto tts

Ferramenta	Descrição	Ambiente necessário
text_to_speech	Converte texto em áudio de fala. Devolve um caminho MEDIA: que a plataforma entrega como mensagem de voz. No Telegram, toca como bolha de voz; no Discord/WhatsApp, como anexo de áudio. No modo CLI, salva em ~/voice-memos/. A voz e o provedor…	—

Conjunto discord

Registrado no conjunto de plataforma hermes-discord (só no gateway). Usa o mesmo token de bot do adaptador de mensagens.

Ferramenta	Descrição	Ambiente necessário
discord	Lê e participa de um servidor do Discord. As ações incluem search_members, fetch_messages, send_message, react, fetch_channel, list_channels e outras.	DISCORD_BOT_TOKEN

Conjunto discord_admin

Registrado no conjunto de plataforma hermes-discord. As ações de moderação exigem que o bot tenha as permissões correspondentes no Discord.

Ferramenta	Descrição	Ambiente necessário
discord_admin	Gerencia um servidor do Discord pela API REST: lista guildas/canais/cargos, cria/edita/apaga canais, gerencia concessões de cargo, silenciamentos, expulsões e banimentos.	DISCORD_BOT_TOKEN + permissões do bot

Conjunto spotify

Registrado pelo plugin spotify que já vem no pacote. Exige um token OAuth — rode hermes auth spotify uma vez para autorizar.

Ferramenta	Descrição	Ambiente necessário
spotify_playback	Controla a reprodução do Spotify, inspeciona o estado de reprodução ativo ou busca as faixas tocadas recentemente.	OAuth do Spotify
spotify_devices	Lista os dispositivos do Spotify Connect ou transfere a reprodução para outro dispositivo.	OAuth do Spotify
spotify_queue	Inspeciona a fila do Spotify do usuário ou adiciona um item a ela.	OAuth do Spotify
spotify_search	Busca no catálogo do Spotify por faixas, álbuns, artistas, playlists, programas ou episódios.	OAuth do Spotify
spotify_playlists	Lista, inspeciona, cria, atualiza e modifica playlists do Spotify.	OAuth do Spotify
spotify_albums	Busca os metadados de um álbum do Spotify ou as faixas dele.	OAuth do Spotify
spotify_library	Lista, salva ou remove as faixas ou os álbuns salvos do usuário no Spotify.	OAuth do Spotify

Conjunto hermes-yuanbao

Registrado apenas no conjunto de plataforma hermes-yuanbao. O Yuanbao é o aplicativo de conversa da Tencent; estas ferramentas conduzem as APIs de mensagem direta, grupo e figurinha dele.

Ferramenta	Descrição	Ambiente necessário
yb_query_group_info	Consulta informações básicas de um grupo (chamado de "派/Pai" no aplicativo): nome, dono, número de membros.	Credenciais do Yuanbao
yb_query_group_members	Consulta os membros de um grupo (para menções com @, para achar um usuário pelo nome, para listar bots).	Credenciais do Yuanbao
yb_send_dm	Envia uma mensagem privada/direta a um usuário de um grupo, com arquivos de mídia opcionais.	Credenciais do Yuanbao
yb_search_sticker	Busca por palavra-chave no catálogo de figurinhas embutido do Yuanbao (as carinhas do TIM).	Credenciais do Yuanbao
yb_send_sticker	Envia uma figurinha embutida para a conversa atual do Yuanbao.	Credenciais do Yuanbao

---