도구 추가

도구를 작성하기 전에 스스로에게 물어보세요. 대신 기술이어야 할까요?

Built-in Core Tools Only

이 페이지는 저장소 자체에 내장된 Hermes 도구를 추가하기 위한 것입니다. 개인용, 프로젝트 로컬용 또는 기타 맞춤형 도구를 원하는 경우 Hermes 코어를 수정하려면 대신 플러그인 경로를 사용하세요.

대부분의 사용자 정의 도구 생성을 위한 기본 플러그인입니다. 다음 경우에만 이 페이지를 따르세요. tools/ 및 toolsets.py에 새로운 내장 도구를 명시적으로 제공하려고 합니다.

기능을 지침 + 셸 명령 + 기존 도구(arXiv 검색, git 워크플로, Docker 관리, PDF 처리)로 표현할 수 있는 경우 기술로 만듭니다.

API 키, 사용자 정의 처리 로직, 바이너리 데이터 처리 또는 스트리밍(브라우저 자동화, TTS, 비전 분석)과의 엔드투엔드 통합이 필요한 경우 도구로 만드세요.

개요

도구를 추가하면 2개 파일에 영향을 미칩니다.

tools/your_tool.py — 핸들러, 스키마, 검사 함수, registry.register() 호출
toolsets.py — _HERMES_CORE_TOOLS(또는 특정 도구 세트)에 도구 이름 추가

최상위 registry.register() 호출이 포함된 모든 tools/*.py 파일은 시작 시 자동으로 검색됩니다. 수동 가져오기 목록이 필요하지 않습니다.

1단계: 내장 도구 파일 생성

모든 도구 파일은 동일한 구조를 따릅니다.

# 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 ---

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"],
)

주요 규칙

Important {#key-rules}

핸들러는 반드시 JSON 문자열(json.dumps()을 통해)을 반환해야 하며 원시 사전은 반환하지 않습니다.
오류 반드시 {"error": "message"}로 반환되어야 하며, 예외로 발생하지 않습니다.
도구 정의를 작성할 때 check_fn이 호출됩니다. False을 반환하면 도구가 자동으로 제외됩니다.
handler은 (args: dict, **kwargs)을 수신합니다. 여기서 args는 LLM의 도구 호출 인수입니다.

2단계: 도구 세트에 기본 제공 도구 추가

toolsets.py에 도구 이름을 추가합니다.

# 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": 
},

3단계: 검색 가져오기 추가 (더 이상 필요하지 않음)

최상위 registry.register() 호출이 있는 도구 모듈은 tools/registry.py의 discover_builtin_tools()에 의해 자동 검색됩니다. 유지 관리할 수동 가져오기 목록이 없습니다. tools/에 파일을 생성하면 시작 시 선택됩니다.

비동기 처리기

핸들러에 비동기 코드가 필요한 경우 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
)

레지스트리는 비동기 브리징을 투명하게 처리하므로 asyncio.run()을 직접 호출하지 않습니다.

task_id가 필요한 핸들러

세션별 상태를 관리하는 도구는 **kwargs을 통해 task_id을 받습니다.

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,
)

에이전트 루프 차단 도구

일부 도구(todo, memory, session_search, delegate_task)는 세션별 에이전트 상태에 액세스해야 합니다. 이는 레지스트리에 도달하기 전에 run_agent.py에 의해 차단됩니다. 레지스트리는 여전히 스키마를 보유하고 있지만, 인터셉트가 우회되면 dispatch()은 대체 오류를 반환합니다.

선택 사항: 설치 마법사 통합

도구에 API 키가 필요한 경우 이를 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,
    },
}

체크리스트

핸들러, 스키마, 검사 함수, 등록으로 생성된 도구 파일
toolsets.py의 적절한 도구 세트에 추가되었습니다.
이것이 실제로 플러그인이 아닌 내장/핵심 도구여야 함을 확인했습니다.
핸들러는 JSON 문자열을 반환하고 오류는 {"error": "..."}으로 반환됩니다.
선택사항: hermes_cli/config.py의 OPTIONAL_ENV_VARS에 API 키가 추가되었습니다.
선택사항: 일괄 처리를 위해 toolset_distributions.py에 추가됨
hermes chat -q "Use the weather tool for London"으로 테스트되었습니다.

개요​

1단계: 내장 도구 파일 생성​

주요 규칙​

2단계: 도구 세트에 기본 제공 도구 추가​

3단계: 검색 가져오기 추가 (더 이상 필요하지 않음)​

비동기 처리기​

task_id가 필요한 핸들러​

에이전트 루프 차단 도구​

선택 사항: 설치 마법사 통합​

체크리스트​

개요