This page documents the Hermes Agent tool registry system, focusing on tool registration, discovery, toolset composition, and platform-specific toolset management. It details how individual tools self-register in the centralized registry, how toolsets group tools for different use cases, and the dynamic aspects such as MCP tool integration and persistent per-platform configuration.
For implementation details of specific tools (terminal, web, vision, etc.), see related leaf pages like 5.2 Terminal and File Operations, 5.5 Web, Browser, and Vision Tools, and 5.8 Other Tools. For secure command approval details, see 5.4 Security and Command Approval.
Hermes Agent uses a centralized tool registry pattern, where each tool module registers its schema, handler function, toolset category, and runtime availability check at import time model_tools.py5-9 The registry acts as a unified store for tool metadata and dispatching logic tools/registry.py1-6 This decouples the core agent orchestration from individual tool implementations and avoids maintaining redundant data structures.
Toolsets are logical groupings of tools that can be used to enable or disable coherent bundles of functionality (e.g., web research, terminal execution, vision analysis) toolsets.py5-7 Toolsets support composition by including other toolsets, allowing flexible scenario-based configuration toolsets.py93-237
Sources: model_tools.py1-21 tools/registry.py1-15 toolsets.py1-24
The system structure is as follows:
tools/terminal_tool.py) define tool schemas, handlers, and register them on import using registry.register() tools/registry.py3-4tools/registry.py) collects all tool entries, including schemas and handlers, and provides availability checking and dispatching tools/registry.py151-167toolsets.py) defines named groups of tools and supports resolving composed toolsets into flat lists of tool names toolsets.py93-237model_tools.py) triggers discovery (imports tool modules), fetches filtered tool definitions by enabled toolsets, and exposes handle_function_call() for performing tool invocation model_tools.py11-21run_agent.py), CLI (hermes_cli/chat.py), messaging gateways (gateway/gateway_runner.py), batch runner (batch_runner.py), and RL environments consume this API to integrate tool functionality model_tools.py8-9Sources: model_tools.py11-21 toolsets.py1-24 tools/registry.py151-167 tools/registry.py169-181
Tools are discovered by dynamically importing tool modules that contain top-level registry.register() calls. The main discovery function discover_builtin_tools() scans the tools/ directory, parses files for registry.register usage using AST tools/registry.py29-54 then imports valid modules to trigger registration tools/registry.py57-74
After importing built-in tools, additional MCP tools and plugin tools are discovered.
| Category | Tools Registered |
|---|---|
| Web | web_search, web_extract toolsets.py97-101 |
| Terminal, Process | terminal, process toolsets.py160-164 |
| File | read_file, write_file, patch, search_files toolsets.py191-203 |
| Vision/Image | vision_analyze, image_generate toolsets.py120-124 toolsets.py132-136 |
| Browser Automation | browser_navigate, browser_snapshot, browser_click, etc. toolsets.py172-182 |
| Skills | skills_list, skill_view, skill_manage toolsets.py166-170 |
| Miscellaneous | text_to_speech, todo, memory, session_search, clarify, execute_code, delegate_task, cronjob, homeassistant, spotify, discord, discord_admin, yuanbao, computer_use toolsets.py31-80 |
Sources: model_tools.py32 tools/registry.py29-74 toolsets.py31-80 toolsets.py97-101 toolsets.py120-124 toolsets.py132-136 toolsets.py160-164 toolsets.py166-170 toolsets.py172-182 toolsets.py191-203
The core class ToolRegistry managed in tools/registry.py handles tool metadata and toolset state. Each tool registers itself using the register method which creates a ToolEntry tools/registry.py77-98
Key metadata in ToolEntry:
| Parameter | Description |
|---|---|
name | Unique tool name (string), e.g., "terminal" |
toolset | Toolset group name (string) to which this tool belongs |
schema | JSON schema describing the tool function compatible with OpenAI function calls |
handler | Callable to invoke the tool logic. Can be async or sync functions |
check_fn | Optional callable to verify runtime prerequisites (e.g., API keys) |
is_async | Boolean flag indicating if the handler is asynchronous |
dynamic_schema_overrides | Callable returning schema overrides applied at runtime tools/registry.py99-106 |
Availability checks per toolset or tool allow conditional enabling. The registry caches these checks with a TTL of 30 seconds tools/registry.py143-148 to allow for dynamic changes in environment variables or external state to propagate without excessive re-probes tools/registry.py119-132 A transient failure grace window of 60 seconds is used to suppress flakes in external probes tools/registry.py146-147
Tool invocation occurs via registry.dispatch(tool_name, args_dict) which calls the registered handler with JSON arguments and returns JSON results tools/registry.py169-181 Errors during execution are caught and returned as JSON error messages.
Tools support async handlers. model_tools.py provides _run_async() to run async handlers from sync contexts model_tools.py88-107 It uses persistent event loops (_tool_loop for CLI model_tools.py51-63 _worker_thread_local.loop for workers model_tools.py66-85) to avoid "Event loop is closed" errors common with asyncio.run() when cached clients are garbage collected model_tools.py53-58
Sources: tools/registry.py77-181 model_tools.py42-172
Toolsets are named bundles of tools that simplify enabling/disabling related capabilities toolsets.py5-7
The TOOLSETS dict in toolsets.py defines built-in toolset compositions:
| Toolset | Description | Tools Included |
|---|---|---|
web | Web research and content extraction | web_search, web_extract toolsets.py97-101 |
terminal | Terminal execution and process management | terminal, process toolsets.py160-164 |
file | File manipulation (read, write, patch, search) | read_file, write_file, patch, search_files toolsets.py191-203 |
browser | Full browser automation suite | browser_navigate, browser_snapshot, browser_click, etc. toolsets.py172-182 |
computer_use | macOS desktop control via cua-driver | computer_use toolsets.py150-158 |
skills | Skill CRUD and management | skills_list, skill_view, skill_manage toolsets.py166-170 |
The function resolve_toolset(name: str) -> Set[str] recursively expands a toolset by including explicitly listed tools and the union of tools from any nested includes toolsets toolsets.py240-246
Sources: toolsets.py95-246
Hermes Agent integrates external tool servers via the Model Context Protocol (MCP) model_tools.py11-21
~/.hermes/config.yaml.sampling/createMessage.supports_parallel_tool_calls.Sources: model_tools.py12-21 toolsets.py31-80
The plugin system allows third-party extensions to register tools that appear alongside built-in capabilities hermes_cli/plugins.py28-32
~/.hermes/plugins/), and project-local directories hermes_cli/plugins.py5-15plugin.yaml manifest and an __init__.py with a register(ctx) function hermes_cli/plugins.py19-20PluginContext.register_tool() delegates to the central tools.registry.register() hermes_cli/plugins.py30-31Sources: hermes_cli/plugins.py1-32 tests/hermes_cli/test_plugins.py35-85
Users configure toolsets per platform (e.g., CLI, Discord) via hermes tools hermes_cli/tools_config.py1-6 Selections are saved persistently in ~/.hermes/config.yaml under the platform_toolsets key hermes_cli/tools_config.py8-9
Some toolsets are disabled by default on new installs (e.g., homeassistant, spotify, discord, video, video_gen, x_search) hermes_cli/tools_config.py153 The agent.disabled_toolsets configuration key can globally suppress toolsets across all platforms tests/hermes_cli/test_tools_config.py31-44
The CONFIGURABLE_TOOLSETS list in hermes_cli/tools_config.py defines the mapping between toolset keys and human-readable labels used in the CLI/TUI configurator hermes_cli/tools_config.py95-121
Certain toolsets auto-enable based on credentials. For example, x_search auto-enables if xAI OAuth tokens or an XAI_API_KEY are detected hermes_cli/tools_config.py156-157 Similarly, homeassistant tools auto-enable if a HASS_TOKEN is present tests/hermes_cli/test_tools_config.py198-199
Sources: hermes_cli/tools_config.py1-156 tests/hermes_cli/test_tools_config.py31-44 hermes_cli/tools_config.py95-121
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.