إضافة أداة جديدة
Adding Tools
ما هذه الصفحة، وماذا تحتوي.
الأدوات: الأفعال التي يستطيع Hermes تنفيذها فعلًا: قراءة ملف، تشغيل أمر، البحث في الويب، إرسال رسالة. الفرق بين مساعد يتكلّم ووكيل ينجز هو الأدوات. من دونها يبقى كلامًا. الصفحة فيها تحذير من المصدر، و4 دقائق قراءة. انتبه: كل أداة تفتح بابًا. أدوات الكتابة والحذف والإرسال تستحق وقفة قبل تفعيلها، وليست كل مهمة تحتاجها.
How to add a new tool to Hermes Agent — schemas, handlers, registration, and toolsets
نتائج مأخوذة من هذه الصفحة، لا من قالب.
- تعرف ما الأدوات ولماذا قد تحتاجه.
- تضبط
WEATHER_API_KEYفي المكان الصحيح. - تتجنّب الخطأ الذي يحذّر منه المصدر.
كما تظهر تمامًا داخل Hermes.
WEATHER_API_KEYWEATHER_SCHEMAOPTIONAL_ENV_VARS
انتقل مباشرة إلى ما تحتاجه.
بلا اختصار أو حذف.
النص أدناه منقول من المصدر الرسمي بالإنجليزية حتى تبقى الأوامر والأسماء دقيقة كما هي. قبل كل قسم شرح عربي يوضّح ما بداخله.
Before writing a tool, ask yourself: should this be a skill instead?
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
شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه. تذكير: الأفعال التي يستطيع Hermes تنفيذها فعلًا: قراءة ملف، تشغيل أمر، البحث في الويب، إرسال رسالة.
Adding a tool touches 2 files:
tools/your_tool.py— handler, schema, check function,registry.register()calltoolsets.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."""
logger = logging.getLogger(__name__)
# --- Availability check ---
def check_weather_requirements() -> bool:
"""Return True if the tool's dependencies are available."""
return bool(os.getenv("WEATHER_API_KEY"))
# --- Handler ---
def weather_tool(location: str, units: str = "metric") -> str:
"""Fetch weather for a location. Returns JSON string."""
api_key = os.getenv("WEATHER_API_KEY")
if not 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
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": []
},~~Step 3: Add Discovery Import~~ (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
إعدادات تضبطها مرة وتنساها. غيّر واحدًا في كل مرة حتى تعرف أثر كل تغيير. تضبط WEATHER_SCHEMA خارج المحادثة، في بيئة التشغيل.
If your handler needs async code, mark it with is_async=True:
async def weather_tool_async(location: str) -> str:
async with 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 taskid
شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.
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
إعدادات تضبطها مرة وتنساها. غيّر واحدًا في كل مرة حتى تعرف أثر كل تغيير. تضبط OPTIONAL_ENV_VARS خارج المحادثة، في بيئة التشغيل.
- [ ] 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_VARSinhermes_cli/config.py - [ ] Optional: Added to
toolset_distributions.pyfor batch processing - [ ] Tested with
hermes chat -q "Use the weather tool for London"
3 أسئلة إجاباتها كلها في هذه الصفحة.
كل خيار اسم حقيقي من توثيق Hermes. حتى الخيارات الخاطئة حقيقية، لكنها من صفحات أخرى.