도구(Tool) 추가

기준일: 2026-07-26
난이도: 중급
공식 기준: Adding Tools

개요

Hermes 빌트인 도구를 코어 저장소에 추가하는 방법입니다. 개인/프로젝트 전용 도구는 코어를 수정하지 말고 플러그인 경로를 쓰세요.

선택	조건
Skill	기존 도구 + 셸 + 지침으로 충분 (arXiv, git 워크플로 등)
Tool (plugin)	커스텀 로직이 필요하지만 코어 수정 불필요
Tool (built-in)	공식 배포 toolset에 실을 통합 (API 키, 바이너리, 스트리밍)

핵심 개념

항목	설명
tools/your_tool.py	handler + schema + registry.register()
toolsets.py	toolset 소속 (_HERMES_CORE_TOOLS 등)
auto-discovery	tools/*.py의 top-level registry.register() 자동 수집
availability check	의존성/키 없으면 도구 숨김
async handler	비동기 실행 지원
agent-loop intercepted	루프가 특수 처리하는 도구

상세

Overview — 건드리는 파일 2개

1. tools/your_tool.py
2. toolsets.py

Step 1: 도구 파일

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

import json
import os
import logging

logger = logging.getLogger(__name__)

def check_weather_requirements() -> bool:
    return bool(os.getenv("WEATHER_API_KEY"))

def weather_tool(location: str, units: str = "metric") -> str:
    api_key = os.getenv("WEATHER_API_KEY")
    if not api_key:
        return json.dumps({"error": "WEATHER_API_KEY not configured"})
    try:
        return json.dumps({"location": location, "temp": 22, "units": units})
    except Exception as e:
        return json.dumps({"error": str(e)})

WEATHER_SCHEMA = {
    "name": "weather",
    "description": "Get current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City name"},
            "units": {"type": "string", "enum": ["metric", "imperial"]},
        },
        "required": ["location"],
    },
}

# registry.register(name, handler, schema, check=...)

핵심 규칙

• handler 반환은 문자열(보통 JSON 문자열)
• schema name과 등록 이름 일치
• 예외를 삼키고 구조화 에러 반환
• 시크릿을 반환/로그에 넣지 말 것

Step 2: toolset 등록

# toolsets.py — 전 플랫폼 기본
_HERMES_CORE_TOOLS = [
    # ...
    "weather",
]

# 또는 독립 toolset
TOOLSETS["weather"] = ["weather"]

Discovery import (불필요)

과거 수동 import 목록은 제거되었습니다. registry.register()만으로 충분합니다.

Async / task_id

• async handler 가능
• 일부 도구는 task_id로 진행 상태·취소를 연동
• agent-loop intercepted tools는 일반 RPC 경로와 다름 (delegate_task 등)

Setup wizard 연동 (선택)

새 API 키가 필요하면 hermes setup 흐름에 env 프롬프트를 추가합니다.

공식 체크리스트

• Skill로 충분한지 재검토
• plugin으로 충분한지 재검토
• handler + schema + register
• toolset 소속 결정
• availability check
• 단위 테스트 + 라이브 스모크
• 문서·changelog

체크리스트

• 이 페이지의 공식 문서를 원문과 대조했다
• 로컬 환경에서 관련 명령/config.yaml 항목을 확인했다
• 보안·allowlist·자격증명 노출 위험을 점검했다
• 다음 단계 문서로 연결 경로를 확인했다

다음 단계

• 관련 공식 문서: Adding Tools
• 상위 허브: Hermes Agent 소개
• 문제 해결: 트러블슈팅

---

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스