Sókrates Wiki

Hermes Agent Tool Integration Process

3 min read

Hermes Agent Tool Integration Process

Summary

The process for extending the Hermes Agent’s capabilities through the implementation and registration of custom Tools. This workflow involves creating a dedicated tool module, defining its JSON schema and execution logic, and registering it within the Hermes core toolsets and discovery system.

Details

Adding a tool to the Hermes Agent is a structured process required when a capability needs end-to-end integration with API keys, custom processing logic, binary data handling, or streaming. This is distinct from a “Skill,” which is typically expressed through instructions and shell commands.

1. Tool Implementation and Registration

Every tool requires a dedicated file within the tools/ directory (e.g., tools/weather_tool.py). This file must contain four specific components:

  • Availability Check (check_fn): A function that returns a boolean indicating if the tool’s dependencies (like environment variables or API keys) are present. If this returns False, the tool is silently excluded from the agent’s available toolset.
  • Handler: The core logic of the tool. Handlers receive (args: dict, **kwargs) and must return a JSON-formatted string. They are designed to handle errors internally, returning a JSON object like {"error": "message"} rather than raising exceptions.
  • Schema: A JSON schema defining the tool’s name, description, and parameters. This schema is what the LLM uses to understand how to invoke the tool.
  • Registry Call: A call to registry.register() that binds the name, toolset, schema, handler, and check function together.

2. Toolset Configuration

Once the tool file is created, it must be registered in toolsets.py. Developers can add the tool to the _HERMES_CORE_TOOLS list to make it available across all platforms (CLI and messaging channels) or define a new standalone toolset. Standalone toolsets allow for grouping related tools (e.g., a “weather” toolset containing multiple weather-related utilities).

3. Discovery and Import

For the tool to be recognized by the system, its module must be added to the _discover_tools() list in model_tools.py. This import triggers the registry.register() call at the bottom of the tool file during system initialization.

4. Advanced Integration Features

  • Async Support: If a tool requires asynchronous execution (e.g., using aiohttp), the registration must include is_async=True. The Hermes registry manages the async bridging transparently.
  • Session Context: Tools that require per-session state can access a task_id via **kwargs passed to the handler.
  • Setup Wizard: For tools requiring sensitive configuration like API keys, the OPTIONAL_ENV_VARS dictionary in hermes_cli/config.py should be updated. This allows the sokrates-ctl or Hermes CLI setup wizard to prompt the user for the necessary credentials, including descriptions and documentation URLs.

5. Validation and Testing

The standard validation path involves checking that the handler returns JSON strings and testing the integration via the CLI using a command such as hermes chat -q "Use the [tool name] for [specific task]".

Graph View