VOOZH about

URL: https://hermes-agent.nousresearch.com/docs/developer-guide/adding-tools

⇱ Adding Tools | Hermes Agent

Skip to main content

Before writing a tool, ask yourself: should this be a skill instead?

Built-in Core Tools Only

This page is for adding a built-in Hermes tool to the repository itself. If you want a personal, project-local, or otherwise custom tool without modifying Hermes core, use the plugin route instead:

Default to plugins for most custom tool creation. Only follow this page when you explicitly want to ship a new built-in tool in tools/ and toolsets.py.

Make it a Skill when the capability can be expressed as instructions + shell commands + existing tools (arXiv search, git workflows, Docker management, PDF processing).

Make it a Tool when it requires end-to-end integration with API keys, custom processing logic, binary data handling, or streaming (browser automation, TTS, vision analysis).

Overview​

Adding a tool touches 2 files:

  1. tools/your_tool.py — handler, schema, check function, registry.register() call
  2. toolsets.py — add tool name to _HERMES_CORE_TOOLS (or a specific toolset)

Any tools/*.py file with a top-level registry.register() call is auto-discovered at startup — no manual import list required.

Step 1: Create the Built-in Tool File​

Every tool file follows the same structure:

# tools/weather_tool.py
"""Weather Tool -- look up current weather for a location."""

import json
import os
import logging

logger = logging.getLogger(__name__)


# --- Availability check ---

defcheck_weather_requirements()->bool:
"""Return True if the tool's dependencies are available."""
returnbool(os.getenv("WEATHER_API_KEY"))


# --- Handler ---

defweather_tool(location:str, units:str="metric")->str:
"""Fetch weather for a location. Returns JSON string."""
 api_key = os.getenv("WEATHER_API_KEY")
ifnot api_key:
return json.dumps({"error":"WEATHER_API_KEY not configured"})
try:
# ... call weather API ...
return json.dumps({"location": location,"temp":22,"units": units})
except Exception as e:
return json.dumps({"error":str(e)})


# --- Schema ---

WEATHER_SCHEMA ={
"name":"weather",
"description":"Get current weather for a location.",
"parameters":{
"type":"object",
"properties":{
"location":{
"type":"string",
"description":"City name or coordinates (e.g. 'London' or '51.5,-0.1')"
},
"units":{
"type":"string",
"enum":["metric","imperial"],
"description":"Temperature units (default: metric)",
"default":"metric"
}
},
"required":["location"]
}
}


# --- Registration ---

from tools.registry import registry

registry.register(
 name="weather",
 toolset="weather",
 schema=WEATHER_SCHEMA,
 handler=lambda args,**kw: weather_tool(
 location=args.get("location",""),
 units=args.get("units","metric")),
 check_fn=check_weather_requirements,
 requires_env=["WEATHER_API_KEY"],
)

Key Rules​

Important
  • Handlers MUST return a JSON string (via json.dumps()), never raw dicts
  • Errors MUST be returned as {"error": "message"}, never raised as exceptions
  • The check_fn is called when building tool definitions — if it returns False, the tool is silently excluded
  • The handler receives (args: dict, **kwargs) where args is the LLM's tool call arguments

Step 2: Add the Built-in Tool to a Toolset​

In toolsets.py, add the tool name:

# If it should be available on all platforms (CLI + messaging):
_HERMES_CORE_TOOLS =[
...
"weather",# <-- add here
]

# Or create a new standalone toolset:
"weather":{
"description":"Weather lookup tools",
"tools":["weather"],
"includes":[]
},

(No longer needed)​

Tool modules with a top-level registry.register() call are auto-discovered by discover_builtin_tools() in tools/registry.py. No manual import list to maintain — just create your file in tools/ and it's picked up at startup.

Async Handlers​

If your handler needs async code, mark it with is_async=True:

asyncdefweather_tool_async(location:str)->str:
asyncwith aiohttp.ClientSession()as session:
...
return json.dumps(result)

registry.register(
 name="weather",
 toolset="weather",
 schema=WEATHER_SCHEMA,
 handler=lambda args,**kw: weather_tool_async(args.get("location","")),
 check_fn=check_weather_requirements,
 is_async=True,# registry calls _run_async() automatically
)

The registry handles async bridging transparently — you never call asyncio.run() yourself.

Handlers That Need task_id​

Tools that manage per-session state receive task_id via **kwargs:

def_handle_weather(args,**kw):
 task_id = kw.get("task_id")
return weather_tool(args.get("location",""), task_id=task_id)

registry.register(
 name="weather",
...
 handler=_handle_weather,
)

Agent-Loop Intercepted Tools​

Some tools (todo, memory, session_search, delegate_task) need access to per-session agent state. These are intercepted by run_agent.py before reaching the registry. The registry still holds their schemas, but dispatch() returns a fallback error if the intercept is bypassed.

Optional: Setup Wizard Integration​

If your tool requires an API key, add it to hermes_cli/config.py:

OPTIONAL_ENV_VARS ={
...
"WEATHER_API_KEY":{
"description":"Weather API key for weather lookup",
"prompt":"Weather API key",
"url":"https://weatherapi.com/",
"tools":["weather"],
"password":True,
},
}

Checklist​

  • Tool file created with handler, schema, check function, and registration
  • Added to appropriate toolset in toolsets.py
  • Confirmed this really should be a built-in/core tool and not a plugin
  • Handler returns JSON strings, errors returned as {"error": "..."}
  • Optional: API key added to OPTIONAL_ENV_VARS in hermes_cli/config.py
  • Optional: Added to toolset_distributions.py for batch processing
  • Tested with hermes chat -q "Use the weather tool for London"