Tool System

Relevant source files

• batch_runner.py
• contributors/emails/tars@users.noreply.github.com
• docs/middleware/README.md
• gateway/builtin_hooks/__init__.py
• gateway/hooks.py
• hermes_cli/codex_models.py
• hermes_cli/middleware.py
• hermes_cli/nous_account.py
• hermes_cli/nous_subscription.py
• hermes_cli/plugins.py
• hermes_cli/tools_config.py
• model_tools.py
• tests/hermes_cli/test_auth_codex_provider.py
• tests/hermes_cli/test_auth_codex_self_heal.py
• tests/hermes_cli/test_codex_cli_model_picker.py
• tests/hermes_cli/test_codex_models.py
• tests/hermes_cli/test_image_gen_picker.py
• tests/hermes_cli/test_install_cua_driver.py
• tests/hermes_cli/test_nous_subscription.py
• tests/hermes_cli/test_plugins.py
• tests/hermes_cli/test_setup.py
• tests/hermes_cli/test_setup_model_provider.py
• tests/hermes_cli/test_status_model_provider.py
• tests/hermes_cli/test_tools_config.py
• tests/hermes_cli/test_video_gen_picker.py
• tests/run_agent/test_concurrent_interrupt.py
• tests/run_agent/test_image_rejection_fallback.py
• tests/test_batch_runner_checkpoint.py
• tests/test_model_tools.py
• tests/tools/test_approval_plugin_hooks.py
• tests/tools/test_local_tempdir.py
• tests/tools/test_registry.py
• tests/tools/test_tool_backend_helpers.py
• tests/tools/test_tool_result_storage.py
• tools/__init__.py
• tools/binary_extensions.py
• tools/registry.py
• tools/tool_backend_helpers.py
• tools/tool_result_storage.py
• toolsets.py
• website/docs/user-guide/features/hooks.md
• website/docs/user-guide/features/plugins.md

The tool system provides the Hermes Agent with its action capabilities through a structured function-calling architecture. This page introduces the high-level framework of the tool registry, how toolsets are composed and managed, and how tool discovery and execution flow through the system.

Specific technical details about individual tool categories and implementations are delegated to child pages, linked below. This parent page provides the architectural context and explains the integration among major components involved in the Hermes tool system.

Architecture Overview

The Hermes Agent leverages a centralized registry pattern for tools, where each tool module self-registers its schema, handler, and a function to check availability, triggered at module import time. tools/registry.py1-15

• The tool registry singleton (ToolRegistry) holds metadata and handlers, serving as the definitive source of available tools in the system. tools/registry.py87-118
• The model_tools.py module orchestrates tool discovery by importing all tool modules, then provides the public API for retrieving tool schemas and handling function calls. model_tools.py1-21
• Toolsets declared in toolsets.py group tools by use case or scenario. Toolsets may be composed from individual tools or by including other toolsets recursively, enabling flexible configuration. toolsets.py1-24
• Plugins can also register tools and hooks, extending the agent's capabilities without modifying core code. hermes_cli/plugins.py28-32
• MCP (Model Context Protocol) servers provide dynamically registered external tools that are seamlessly integrated into the same registry to be invoked like built-in tools.

This modular design supports both synchronous and asynchronous tools, with robust bridging between sync agent logic and async handlers to optimize external calls.

Sources: model_tools.py1-30 toolsets.py1-24 tools/registry.py1-118 hermes_cli/plugins.py28-32

---

Tool Registration and Discovery

Registration

Each tool registers itself by calling registry.register() at module load time. This registers metadata including:

• Tool name (string identifier)
• Toolset membership (categorical grouping)
• JSON schema for the tool parameters (OpenAI function calling style)
• Handler function (signature: takes args dict and optional kwargs)
• Availability check function (check_fn)
• Metadata like description, emoji icon, async status, and max result size. tools/registry.py87-118

Discovery Process

Tool discovery is primarily performed by model_tools.py invoking discover_builtin_tools() from tools/registry.py:

Title: Tool Discovery Sequence

• The discovery imports all tool modules found in the tools/ directory that contain top-level registry.register() calls. tools/registry.py67-84
• Plugins are discovered and loaded by the PluginManager, which then registers their tools via ctx.register_tool(). hermes_cli/plugins.py5-32
• Configurable toolsets for UI display and platform-specific logic are defined in tools_config.py. hermes_cli/tools_config.py91-121

For details, see Tool Registry and Toolsets.

Sources: model_tools.py31-34 tools/registry.py67-84 hermes_cli/tools_config.py91-121 hermes_cli/plugins.py5-32

---

Tool Structure

Each tool consists of the following elements:

Schema

Tools specify their parameter interface using OpenAI-compatible function calling schemas. This includes the tool name, description, and JSON Schema parameters. tools/registry.py99-101

Handler Function

• Signature: handler(args: dict, **kwargs) -> str
• Returns a string representing the tool's response (often JSON).
• Handlers may be synchronous or asynchronous. The system uses internal bridging to await async handlers transparently via _run_async. model_tools.py97-116

Availability Check

Tools can specify a check_fn returning a boolean indicating runtime availability. This allows conditional exposure for tools depending on API keys, environment dependencies (e.g., Docker, Playwright), or platform capabilities. Results are cached for ~30 seconds via _check_fn_cached. tools/registry.py154-181

Sources: tools/registry.py87-181 model_tools.py11-20

---

Tool Dispatch Flow

Invocation Sequence

Title: Tool Invocation Flow

• The agent uses handle_function_call() as the entry point for tool execution. model_tools.py13
• Before execution, pre_tool_call hooks registered by plugins are invoked. hermes_cli/plugins.py136
• This function uses _run_async() to execute either sync or async handlers correctly across different thread contexts (main thread vs. worker threads). model_tools.py97-116
• After execution, post_tool_call hooks are invoked. hermes_cli/plugins.py137
• Results are normalized and truncated if they exceed the tool's max_result_size_chars. tools/registry.py108

Sources: model_tools.py11-116 tools/registry.py87-118 hermes_cli/plugins.py135-137

---

Toolsets

Tools are grouped into logical toolsets to simplify configuration and filtering. Toolsets are defined in toolsets.py and map tool names to functional groups. toolsets.py31-81

Core Toolsets and Composition

Toolset	Description	Primary Tools
web	Web research and content extraction	web_search, web_extract
terminal	Command execution and processes	terminal, process
file	File manipulation (read, write, patch)	read_file, write_file, patch
browser	Browser automation (Playwright)	browser_navigate, browser_click
vision	Image analysis	vision_analyze
video	Video analysis and understanding	video_analyze
code_execution	Sandboxed code execution	execute_code
delegation	Task delegation to subagents	delegate_task

Toolsets can include other toolsets using the includes key, enabling nested composition. toolsets.py96-102

For details, see Tool Registry and Toolsets.

Sources: toolsets.py31-224 hermes_cli/tools_config.py91-121

---

Tool Categories and Configuration

The hermes_cli/tools_config.py module defines CONFIGURABLE_TOOLSETS for UI toggling and provider-aware configuration (e.g., setting API keys for vision or search). hermes_cli/tools_config.py95-121

Plugin Tool Integration

Hermes agent supports external tools via the Plugin system. Plugins are configured under the plugins key in ~/.hermes/config.yaml. hermes_cli/plugins.py1-32

• Discovery: Discovers tools from bundled, user, project, or pip sources. hermes_cli/plugins.py5-17
• Registration: Plugins use ctx.register_tool() to add tools to the central registry. hermes_cli/plugins.py30-31
• Execution: Tool calls are handled via the registered handler function, which can be sync or async.

For details, see Tool Registry and Toolsets.

Sources: hermes_cli/plugins.py1-32 hermes_cli/tools_config.py91-121

---

Async Tool Support

The model_tools.py module implements a robust asynchronous bridge _run_async(coro) that ensures asynchronous tool handlers can be called safely from synchronous agent loops. model_tools.py97-116

• Persistent Loop: Maintains a long-lived event loop (_tool_loop) on the main thread to prevent "Event loop is closed" errors. model_tools.py60-73
• Worker Threads: For worker threads (used in subagent delegation), stores thread-local persistent event loops in _worker_thread_local. model_tools.py75-94
• Safety: Detects if already running inside an async event loop (e.g., the messaging gateway) and spins up a disposable thread if necessary. model_tools.py118-122

Sources: model_tools.py51-125

---

Related Child Pages

For detailed technical documentation and implementation specifics, see the following child pages:

• Tool Registry and Toolsets — Tool registration, discovery, and platform-specific configurations.
• Terminal and File Operations — Terminal execution and semantic file tools.
• Process Management — Background process spawning and lifecycle management.
• Security and Command Approval — Dangerous command detection and approval callbacks.
• Web, Browser, and Vision Tools — Web search, Playwright automation, and multimodal analysis.
• Code Execution and MCP Tools — Python sandbox and MCP server integration.
• Subagent Delegation — Subagent spawning and iteration budget sharing.
• Other Tools — Memory, image/video generation, and computer use.

---

Title: Toolset and Tool Code Entities

Sources: model_tools.py1-125 tools/registry.py67-181 toolsets.py31-81 hermes_cli/tools_config.py91-121 hermes_cli/plugins.py5-32