Arquitetura

Esta página é o mapa de alto nível das entranhas do Hermes Agent. Use-a para se situar no código e depois mergulhe na documentação de cada subsistema para os detalhes de implementação.

Visão geral do sistema

┌─────────────────────────────────────────────────────────────────────┐
│                        Entry Points                                  │
│                                                                      │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)     │
│  Batch Runner    API Server                  Python Library          │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                          │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │ Prompt       │  │ Provider     │  │ Tool         │               │
│  │ Builder      │  │ Resolution   │  │ Dispatch     │               │
│  │ (prompt_     │  │ (runtime_    │  │ (model_      │               │
│  │  builder.py) │  │  provider.py)│  │  tools.py)   │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                 │                       │
│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
│  │ Compression  │  │ 3 API Modes  │  │ Tool Registry│               │
│  │ & Caching    │  │ chat_compl.  │  │ (registry.py)│               │
│  │              │  │ codex_resp.  │  │ 70+ tools    │               │
│  │              │  │ anthropic    │  │ 28 toolsets  │               │
│  └──────────────┘  └──────────────┘  └──────────────┘               │
└─────────┴─────────────────┴─────────────────┴───────────────────────┘
           │                                    │
           ▼                                    ▼
┌───────────────────┐              ┌──────────────────────┐
│ Session Storage   │              │ Tool Backends         │
│ (SQLite + FTS5)   │              │ Terminal (6 backends) │
│ hermes_state.py   │              │ Browser (5 backends)  │
│ gateway/session.py│              │ Web (4 backends)      │
└───────────────────┘              │ MCP (dynamic)         │
                                   │ File, Vision, etc.    │
                                   └──────────────────────┘

Estrutura de diretórios

hermes-agent/
├── run_agent.py              # AIAgent — laço central de conversa (arquivo grande)
├── cli.py                    # HermesCLI — UI interativa de terminal (arquivo grande)
├── model_tools.py            # Descoberta de ferramentas, coleta de esquemas, despacho
├── toolsets.py               # Agrupamentos de ferramentas e presets por plataforma
├── hermes_state.py           # Banco SQLite de sessão/estado com FTS5
├── hermes_constants.py       # HERMES_HOME, caminhos cientes de perfil
├── batch_runner.py           # Geração de trajetórias em lote
│
├── agent/                    # Entranhas do agente
│   ├── prompt_builder.py     # Montagem do prompt de sistema
│   ├── context_engine.py     # ABC ContextEngine (plugável)
│   ├── context_compressor.py # Motor padrão — sumarização com perda
│   ├── prompt_caching.py     # Cache de prompt da Anthropic
│   ├── auxiliary_client.py   # LLM auxiliar para tarefas laterais (visão, sumarização)
│   ├── model_metadata.py     # Tamanhos de contexto, estimativa de tokens
│   ├── models_dev.py         # Integração com o registro models.dev
│   ├── anthropic_adapter.py  # Conversão para o formato Anthropic Messages API
│   ├── display.py            # KawaiiSpinner, formatação de prévia de ferramenta
│   ├── skill_commands.py     # Comandos de barra das skills
│   ├── memory_manager.py    # Orquestração do gerenciador de memória
│   ├── memory_provider.py   # ABC do provedor de memória
│   └── trajectory.py         # Auxiliares para salvar trajetórias
│
├── hermes_cli/               # Subcomandos da CLI e configuração
│   ├── main.py               # Ponto de entrada — todos os subcomandos `hermes` (arquivo grande)
│   ├── config.py             # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migração
│   ├── commands.py           # COMMAND_REGISTRY — definições centrais dos comandos de barra
│   ├── auth.py               # PROVIDER_REGISTRY, resolução de credenciais
│   ├── runtime_provider.py   # Provedor → api_mode + credenciais
│   ├── models.py             # Catálogo de modelos, listas por provedor
│   ├── model_switch.py       # Lógica do comando /model (compartilhada CLI + gateway)
│   ├── setup.py              # Assistente interativo de configuração (arquivo grande)
│   ├── skin_engine.py        # Motor de temas da CLI
│   ├── skills_config.py      # hermes skills — habilita/desabilita por plataforma
│   ├── skills_hub.py         # Comando de barra /skills
│   ├── tools_config.py       # hermes tools — habilita/desabilita por plataforma
│   ├── plugins.py            # PluginManager — descoberta, carregamento, hooks
│   ├── callbacks.py          # Callbacks de terminal (esclarecimento, sudo, aprovação)
│   └── gateway.py            # hermes gateway start/stop
│
├── tools/                    # Implementações de ferramentas (um arquivo por ferramenta)
│   ├── registry.py           # Registro central de ferramentas
│   ├── approval.py           # Detecção de comandos perigosos
│   ├── terminal_tool.py      # Orquestração de terminal
│   ├── process_registry.py   # Gerenciamento de processos em segundo plano
│   ├── file_tools.py         # read_file, write_file, patch, search_files
│   ├── web_tools.py          # web_search, web_extract
│   ├── browser_tool.py       # 10 ferramentas de automação de navegador
│   ├── code_execution_tool.py # sandbox do execute_code
│   ├── delegate_tool.py      # Delegação para subagentes
│   ├── mcp_tool.py           # Cliente MCP (arquivo grande)
│   ├── credential_files.py   # Repasse de credenciais baseado em arquivo
│   ├── env_passthrough.py    # Repasse de variáveis de ambiente para sandboxes
│   ├── ansi_strip.py         # Remoção de escapes ANSI
│   └── environments/         # Backends de terminal (local, docker, ssh, modal, daytona, singularity)
│
├── gateway/                  # Gateway das plataformas de mensagem
│   ├── run.py                # GatewayRunner — despacho de mensagens (arquivo grande)
│   ├── session.py            # SessionStore — persistência das conversas
│   ├── delivery.py           # Entrega de mensagens de saída
│   ├── pairing.py            # Autorização de pareamento em DM
│   ├── hooks.py              # Descoberta de hooks e eventos de ciclo de vida
│   ├── mirror.py             # Espelhamento de mensagens entre sessões
│   ├── status.py             # Travas de token, rastreio de processos por perfil
│   ├── builtin_hooks/        # Ponto de extensão para hooks sempre registrados (nenhum embarcado)
│   └── platforms/            # Adaptadores embutidos: signal, weixin, bluebubbles,
│                             #   qqbot, whatsapp_cloud, yuanbao, webhook, api_server
│
├── plugins/platforms/        # Plugins de plataforma embarcados: telegram, discord, slack,
│                             #   whatsapp, matrix, mattermost, email, sms, dingtalk,
│                             #   feishu, wecom, homeassistant, irc, line, teams,
│                             #   google_chat, buzz, ntfy, photon, raft, simplex
│
├── acp_adapter/              # Servidor ACP (VS Code / Zed / JetBrains)
├── cron/                     # Agendador (jobs.py, scheduler.py)
├── plugins/memory/           # Plugins de provedor de memória
├── plugins/context_engine/   # Plugins de motor de contexto
├── skills/                   # Skills embarcadas (sempre disponíveis)
├── optional-skills/          # Skills opcionais oficiais (instale explicitamente)
├── website/                  # Site de documentação em Docusaurus
└── tests/                    # Suíte pytest (~25.000 testes em ~1.250 arquivos)

Fluxo de dados

Sessão da CLI

Entrada do usuário → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → chamada de API (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → laço
    → resposta final → exibição → grava no SessionDB

Mensagem de gateway

Evento da plataforma → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → autoriza o usuário
    → resolve a chave de sessão
    → cria o AIAgent com o histórico da sessão
    → AIAgent.run_conversation()
    → devolve a resposta pelo adaptador

Tarefa de cron

Tique do agendador → carrega tarefas vencidas de jobs.json
  → cria um AIAgent novo (sem histórico)
  → injeta as skills anexadas como contexto
  → roda o prompt da tarefa
  → entrega a resposta na plataforma de destino
  → atualiza o estado da tarefa e o next_run

Ordem de leitura recomendada

Se você é novo no código:

1. Esta página — para se situar
2. Laço do Agente por Dentro — como o AIAgent funciona
3. Montagem do Prompt — construção do prompt de sistema
4. Resolução de Runtime de Provedores — como os provedores são escolhidos
5. Adicionar Provedores — guia prático para adicionar um provedor novo
6. Runtime de Ferramentas — registro, despacho e ambientes de ferramentas
7. Armazenamento de Sessões — esquema SQLite, FTS5, linhagem de sessões
8. Gateway por Dentro — gateway das plataformas de mensagem
9. Compressão de Contexto e Cache de Prompt — compressão e cache
10. ACP por Dentro — integração com a IDE

Principais subsistemas

Laço do agente

O motor de orquestração síncrono (AIAgent, em run_agent.py). Cuida da escolha de provedor, construção do prompt, execução de ferramentas, novas tentativas, fallback, callbacks, compressão e persistência. Suporta três modos de API para backends de provedor diferentes.

→ Laço do Agente por Dentro

Sistema de prompt

Construção e manutenção do prompt ao longo do ciclo de vida da conversa:

• system_prompt.py + prompt_builder.py — montam as camadas ordenadas do prompt de sistema (stable → context → volatile): identidade/orientações de ferramenta/skills, arquivos de contexto e depois os blocos de memória/perfil/timestamp
• prompt_caching.py — aplica os pontos de corte de cache da Anthropic para cache de prefixo
• context_compressor.py — sumariza os turnos do meio da conversa quando o contexto passa dos limites

→ Montagem do Prompt, Compressão de Contexto e Cache de Prompt

Resolução de provedores

Um resolvedor de runtime compartilhado, usado por CLI, gateway, cron, ACP e chamadas auxiliares. Mapeia tuplas (provider, model) para (api_mode, api_key, base_url). Lida com mais de 18 provedores, fluxos OAuth, pools de credenciais e resolução de apelidos.

→ Resolução de Runtime de Provedores

Sistema de ferramentas

Registro central de ferramentas (tools/registry.py) com mais de 70 ferramentas registradas em cerca de 28 conjuntos. Cada arquivo de ferramenta se registra sozinho no momento do import. O registro cuida da coleta de esquemas, do despacho, da checagem de disponibilidade e do empacotamento de erros. As ferramentas de terminal suportam 7 backends (local, Docker, SSH, Daytona, Modal, Singularity, Vercel Sandbox).

→ Runtime de Ferramentas

Persistência de sessões

Armazenamento de sessões em SQLite com busca em texto completo via FTS5. As sessões têm rastreio de linhagem (pai/filho ao longo das compressões), isolamento por plataforma e escritas atômicas com tratamento de concorrência.

→ Armazenamento de Sessões

Gateway de mensagens

Processo de longa duração com mais de 25 adaptadores de plataforma (embutidos + plugins embarcados), roteamento unificado de sessões, autorização de usuários (listas de permissão + pareamento em DM), despacho de comandos de barra, sistema de hooks, tique do cron e manutenção em segundo plano.

→ Gateway por Dentro

Sistema de plugins

Três fontes de descoberta: ~/.hermes/plugins/ (usuário), .hermes/plugins/ (projeto) e entry points do pip. Os plugins registram ferramentas, hooks e comandos de CLI por uma API de contexto. Existem dois tipos especializados de plugin: provedores de memória (plugins/memory/) e motores de contexto (plugins/context_engine/). Ambos são de seleção única — só um de cada pode estar ativo por vez, configurado via hermes plugins ou config.yaml.

→ Guia de Plugins, Plugin de Provedor de Memória

Cron

Tarefas de agente de primeira classe (não tarefas de shell). As tarefas ficam em JSON, aceitam vários formatos de agendamento, podem anexar skills e scripts, e entregam em qualquer plataforma.

→ Cron por Dentro

Integração ACP

Expõe o Hermes como agente nativo do editor sobre stdio/JSON-RPC para VS Code, Zed e JetBrains.

→ ACP por Dentro

Trajetórias

Gera trajetórias no formato ShareGPT a partir das sessões do agente, para produzir dados de treinamento.

→ Trajetórias e Formato de Treinamento

Princípios de projeto

Princípio	O que significa na prática
Estabilidade do prompt	O prompt de sistema não muda no meio da conversa. Nenhuma mutação que quebre o cache, exceto por ações explícitas do usuário (/model).
Execução observável	Toda chamada de ferramenta fica visível para o usuário via callbacks. Atualizações de progresso na CLI (spinner) e no gateway (mensagens de chat).
Interrompível	Chamadas de API e execução de ferramentas podem ser canceladas em pleno voo por entrada do usuário ou por sinais.
Núcleo agnóstico de plataforma	Uma única classe AIAgent atende CLI, gateway, ACP, lote e servidor de API. As diferenças de plataforma vivem no ponto de entrada, não no agente.
Acoplamento fraco	Subsistemas opcionais (MCP, plugins, provedores de memória, ambientes de RL) usam padrões de registro e liberação por check_fn, não dependências rígidas.
Isolamento de perfis	Cada perfil (hermes -p <nome>) ganha o seu próprio HERMES_HOME, configuração, memória, sessões e PID de gateway. Vários perfis rodam ao mesmo tempo.

Cadeia de dependências entre arquivos

tools/registry.py  (sem dependências — importado por todos os arquivos de ferramenta)
       ↑
tools/*.py  (cada um chama registry.register() no momento do import)
       ↑
model_tools.py  (importa tools/registry + dispara a descoberta de ferramentas)
       ↑
run_agent.py, cli.py, batch_runner.py, environments/

Essa cadeia significa que o registro de ferramentas acontece no momento do import, antes de qualquer instância de agente ser criada. Qualquer arquivo tools/*.py com uma chamada registry.register() de nível superior é descoberto automaticamente — não é preciso manter lista de imports.

---