Referência de conjuntos de ferramentas

Conjuntos de ferramentas (toolsets) são pacotes nomeados de ferramentas que controlam o que o agente pode fazer. São o mecanismo principal para configurar a disponibilidade de ferramentas por plataforma, por sessão ou por tarefa.

Como os conjuntos funcionam

Toda ferramenta pertence a exatamente um conjunto. Quando você habilita um conjunto, todas as ferramentas daquele pacote ficam disponíveis para o agente. Existem três tipos de conjunto:

• Núcleo — um único grupo lógico de ferramentas relacionadas (por exemplo, file reúne read_file, write_file, patch, search_files)
• Composto — combina vários conjuntos de núcleo para um cenário comum (por exemplo, debugging reúne as ferramentas de arquivo, terminal e web)
• Plataforma — uma configuração completa de ferramentas para um contexto de implantação específico (por exemplo, hermes-cli é o padrão das sessões interativas de CLI)

Configurar conjuntos de ferramentas

Por sessão (CLI)

hermes chat --toolsets web,file,terminal
hermes chat --toolsets debugging        # composto — expande para file + terminal + web
hermes chat --toolsets all              # tudo

Por plataforma (config.yaml)

toolsets:
  - hermes-cli          # padrão da CLI
  # - hermes-telegram   # sobrescreve para o gateway do Telegram

Gerenciamento interativo

hermes tools                            # interface curses para ligar/desligar por plataforma

Ou dentro da sessão:

/tools list
/tools disable browser
/tools enable homeassistant

Conjuntos de núcleo

Conjunto	Ferramentas	Para que serve
browser	browser_back, browser_cdp, browser_click, browser_console, browser_dialog, browser_get_images, browser_navigate, browser_press, browser_scroll, browser_snapshot, browser_type, browser_vision, web_search	Automação de navegador de núcleo. Inclui o web_search como reserva para consultas rápidas. browser_cdp e browser_dialog são liberados em tempo de execução — só são registrados quando há um endpoint CDP alcançável no início da sessão (via /browser connect, configuração browser.cdp_url, Browserbase ou Camofox). O browser_dialog funciona junto com os campos pending_dialogs e frame_tree que o browser_snapshot acrescenta quando há um supervisor CDP conectado.
clarify	clarify	Faz uma pergunta ao usuário quando o agente precisa de esclarecimento.
code_execution	execute_code	Roda scripts Python que chamam as ferramentas do Hermes programaticamente.
coding	composto (file + terminal + search + web + skills + browser + todo + memory + session_search + clarify + code_execution + delegation + vision)	Pacote focado em programação para trabalho de software: edição de arquivos, terminal, busca, documentação na web, skills, navegador, delegação e execução de código.
cronjob	cronjob	Agenda e gerencia tarefas recorrentes.
debugging	composto (file + terminal + web)	Pacote de depuração — arquivo, processo/terminal, extração/busca na web.
delegation	delegate_task	Cria instâncias isoladas de subagente para trabalho em paralelo.
discord	discord	Ações de texto/embed/mensagem direta do Discord (só no gateway). Ativo no conjunto hermes-discord.
discord_admin	discord_admin	Moderação no Discord (banimentos, mudança de cargos, gestão de canais). Ativo no conjunto hermes-discord; exige que o bot tenha as permissões correspondentes no Discord.
feishu_doc	feishu_doc_read	Lê o conteúdo de documentos do Feishu/Lark. Usado pelo handler de resposta inteligente a comentários em documentos do Feishu.
feishu_drive	feishu_drive_add_comment, feishu_drive_list_comments, feishu_drive_list_comment_replies, feishu_drive_reply_comment	Operações de comentário no drive do Feishu/Lark. Restritas ao agente de comentários; não são expostas no hermes-cli nem em outros conjuntos de mensagens.
file	patch, read_file, search_files, write_file	Leitura, escrita, busca e edição de arquivos.
homeassistant	ha_call_service, ha_get_state, ha_list_entities, ha_list_services	Controle de casa inteligente pelo Home Assistant. Só fica disponível quando HASS_TOKEN está definido.
computer_use	computer_use	Controle do desktop em segundo plano pelo cua-driver — não rouba cursor nem foco. Funciona com qualquer modelo que suporte ferramentas. macOS, Windows e Linux; exige o cua-driver no $PATH.
context_engine	(varia)	Ferramentas de runtime expostas pelo plugin de motor de contexto ativo (vazio até um plugin preencher).
image_gen	image_generate	Geração de imagem a partir de texto pelo FAL.ai (com backends opcionais da OpenAI / xAI).
video_gen	video_generate, xai_video_edit, xai_video_extend	Texto para vídeo e imagem para vídeo por backends registrados via plugin (xAI Grok-Imagine, FAL.ai Veo 3.1 / Pixverse v6 / Kling O3). Passe image_url para animar uma imagem; omita para texto para vídeo. xai_video_edit / xai_video_extend são ferramentas de edição/extensão específicas do provedor, liberadas conforme as credenciais do xAI Imagine.
kanban	kanban_attach, kanban_attach_url, kanban_attachments, kanban_block, kanban_comment, kanban_complete, kanban_create, kanban_heartbeat, kanban_link, kanban_list, kanban_request_changes, kanban_request_review, kanban_show, kanban_unblock	Ferramentas de coordenação entre vários agentes. Registradas para os workers de tarefa criados pelo dispatcher (HERMES_KANBAN_TASK) e para perfis que listam o conjunto kanban pelo nome explicitamente (o curinga all/* não habilita). Os workers marcam tarefas como concluídas, pedem revisão de primeira classe, bloqueiam, mandam heartbeat, comentam e criam/vinculam tarefas de acompanhamento; perfis orquestradores ganham ainda ferramentas de roteamento de quadro, como list/unblock. Filhos de delegate_task não são donos de execução do Kanban: o esquema deles remove/desabilita este conjunto e as proteções de runtime recusam mutações diretas no quadro, mesmo que as variáveis de ambiente HERMES_KANBAN_* do pai estejam presentes.
memory	memory	Gestão de memória persistente entre sessões.
desktop_ui	annotate_preview, close_preview, close_terminal, drive_preview, focus_pane, open_preview, react_to_message, read_preview, read_terminal, read_window_below, tour	Recursos que agem sobre o próprio app de desktop do Hermes — ler/fechar o painel de terminal embutido; abrir, ler, fechar, interagir e anotar o navegador dentro do app; identificar a janela do sistema atrás do app; revelar um painel; reagir a uma mensagem; rodar um tour guiado (destacar + narrar elementos da interface no app ou no painel de pré-visualização). Habilitado para sessões cuja origem é o app de desktop, seja qual for o backend a que ele está conectado (local, SSH, URL ou Hermes Cloud). Nunca aparece em sessões de CLI, TUI, mensagens ou cron.
project	project_create, project_list, project_switch	Cria e alterna Projetos do desktop (espaços de trabalho nomeados, com várias pastas). Só em sessões de GUI / desktop.
safe	image_generate, vision_analyze, web_extract, web_search (via includes)	Pesquisa somente de leitura + geração de mídia. Sem escrita em arquivos, sem terminal, sem execução de código.
search	web_search	Só busca na web (sem extração).
session_search	session_search	Busca em sessões de conversa passadas.
skills	skill_manage, skill_view, skills_list	CRUD e navegação de skills.
spotify	spotify_albums, spotify_devices, spotify_library, spotify_playback, spotify_playlists, spotify_queue, spotify_search	Controle nativo do Spotify (reprodução, fila, busca, playlists, álbuns, biblioteca). Registrado pelo plugin embutido spotify.
terminal	process, terminal	Execução de comandos de shell e gestão de processos em segundo plano.
todo	todo	Gestão da lista de tarefas dentro de uma sessão.
tts	text_to_speech	Geração de áudio a partir de texto.
vision	vision_analyze	Análise de imagem por modelos com visão.
video	video_analyze	Ferramentas de análise e compreensão de vídeo (opcional, não entra no conjunto padrão — adicione explicitamente via --toolsets).
web	web_extract, web_search	Busca na web e extração do conteúdo de páginas.
x_search	x_search	Descoberta pública no X, somente leitura, pela ferramenta Responses x_search embutida da xAI. Use a skill xurl para leituras autenticadas da API do X e ações de conta. Desligado por padrão; habilite via hermes tools. O esquema só é registrado quando as credenciais da xAI (OAuth do SuperGrok ou XAI_API_KEY) estão configuradas.
yuanbao	yb_query_group_info, yb_query_group_members, yb_search_sticker, yb_send_dm, yb_send_sticker	Ações de mensagem direta/grupo e busca de figurinhas no Yuanbao. Registradas só no hermes-yuanbao.

Conjuntos de plataforma

Conjuntos de plataforma definem a configuração completa de ferramentas para um destino de implantação. A maioria das plataformas de mensagens usa o mesmo conjunto do hermes-cli:

Conjunto	Diferenças em relação ao hermes-cli
hermes-cli	Conjunto completo — o padrão das sessões interativas de CLI. Inclui arquivo, terminal, web, navegador, memória, skills, visão, image_gen, todo, tts, delegação, code_execution, cronjob, session_search, clarify, computer_use, Home Assistant e as ferramentas de kanban (todas liberadas por check_fn em tempo de execução).
hermes-acp	Tira clarify, cronjob, image_generate, text_to_speech, computer_use, as quatro ferramentas do Home Assistant e as ferramentas de kanban. Focado em tarefas de programação no contexto da IDE.
hermes-api-server	Tira clarify, text_to_speech, computer_use e as ferramentas de kanban. Mantém todo o resto — serve para acesso programático, em que não dá para interagir com o usuário.
hermes-cron	Igual ao hermes-cli.
hermes-telegram	Igual ao hermes-cli.
hermes-discord	Acrescenta discord e discord_admin em cima do hermes-cli.
hermes-slack	Igual ao hermes-cli.
hermes-whatsapp	Igual ao hermes-cli.
hermes-signal	Igual ao hermes-cli.
hermes-matrix	Igual ao hermes-cli.
hermes-mattermost	Igual ao hermes-cli.
hermes-email	Igual ao hermes-cli.
hermes-sms	Igual ao hermes-cli.
hermes-bluebubbles	Igual ao hermes-cli.
hermes-dingtalk	Igual ao hermes-cli.
hermes-feishu	Acrescenta as cinco ferramentas feishu_doc_* / feishu_drive_* (usadas só pelo handler de comentários em documentos, não pelo adaptador de chat comum).
hermes-qqbot	Igual ao hermes-cli.
hermes-wecom	Igual ao hermes-cli.
hermes-wecom-callback	Igual ao hermes-cli.
hermes-weixin	Igual ao hermes-cli.
hermes-yuanbao	Acrescenta as cinco ferramentas yb_* (mensagem direta/grupo/figurinha) em cima do hermes-cli.
hermes-homeassistant	Igual ao hermes-cli (as ferramentas do Home Assistant já vêm presentes por padrão e ativam quando HASS_TOKEN está definido).
hermes-webhook	Subconjunto seguro e restrito — só web_search, web_extract, vision_analyze e clarify. Execuções disparadas por webhook não têm acesso a terminal, arquivos nem navegador.
hermes-gateway	Conjunto interno do orquestrador do gateway — a união de todos os conjuntos hermes-<platform>; usado quando o gateway precisa aceitar qualquer origem de mensagem.

Conjuntos dinâmicos

Conjuntos de servidores MCP

Cada servidor MCP configurado gera um conjunto mcp-<server> em tempo de execução. Por exemplo, se você configura um servidor MCP github, é criado um conjunto mcp-github com todas as ferramentas que aquele servidor expõe.

# config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]

Isso cria um conjunto mcp-github que você pode citar em --toolsets ou nas configurações de plataforma.

Conjuntos de plugins

Plugins podem registrar os próprios conjuntos via ctx.register_tool() durante a inicialização do plugin. Eles aparecem ao lado dos conjuntos embutidos e podem ser habilitados/desabilitados do mesmo jeito.

Conjuntos personalizados

Defina conjuntos personalizados no config.yaml para criar pacotes específicos do projeto:

toolsets:
  - hermes-cli
custom_toolsets:
  data-science:
    - file
    - terminal
    - code_execution
    - web
    - vision

Curingas

• all ou * — expande para todo conjunto registrado (embutido + dinâmico + de plugin)

Um punhado de ferramentas tem uma checagem extra de disponibilidade, além de pertencer a um conjunto, e não é ligado só por all/*:

• Ferramentas liberadas por capacidade (navegador, computer_use, code_execution, Feishu, Home Assistant, cronjob) só aparecem quando o pré-requisito de backend/credencial está configurado.
• Ferramentas liberadas por fluxo de trabalho — o conjunto kanban — são opcionais de propósito. all/* não habilita o kanban; você precisa listar kanban explicitamente (ou ser um worker criado pelo dispatcher, com HERMES_KANBAN_TASK definido). As ferramentas de kanban alteram o estado compartilhado do quadro, então continuam desligadas por padrão, mesmo sob all.

Relação com o hermes tools

O comando hermes tools oferece uma interface em curses para ligar ou desligar ferramentas individuais por plataforma. Ele opera no nível da ferramenta (mais fino que o conjunto) e persiste no config.yaml. Ferramentas desabilitadas são filtradas mesmo que o conjunto delas esteja habilitado.

Veja também: Referência de ferramentas para a lista completa de ferramentas individuais e seus parâmetros.

---