【#5】Hermes Agent 분석하기
요약
Hermes Agent의 툴 시스템(Tool System) 구조를 분석하며, 71개의 실제 호출 가능한 툴 카탈로그와 자기 등록 방식의 레지스트리 메커니즘을 설명합니다. 각 툴은 자격 증명 확인을 위한 30초 TTL 캐시를 사용하여 효율적으로 가용성을 관리합니다.
핵심 포인트
- 툴 모듈이 import 시 스스로 등록하는 자기 등록(Self-registration) 방식 채택
- 자격 증명 및 환경 확인을 위한 30초 TTL 캐시 적용으로 성능 최적화
- 웹 검색, 멀티모달 분석, 터미널 제어 등 71개의 다양한 툴 제공
- 파일 읽기/쓰기 등 시스템 제어를 위한 전용 툴 인터페이스 구축
연재 「Hermes Agent 분석하기」 제5회.
연재 「Hermes Agent 분석하기」 총 10회
- [제1회 전체상과 읽는 법]
- [제2회 핵심 대화 루프 (Conversation Loop)]
- [제3회 상태 관리 (State Management)와 컴팩션 (Compaction)]
- [제4회 기억 아키텍처 (Memory Architecture)와 인격]
[제5회 툴 시스템 (Tool System)] (본 기사) - [제6회 멀티 에이전트 병렬 (Multi-agent Parallel)]
- [제7회 Kanban 영구 태스크 보드]
- [제8회 접속층과 인터페이스 총람]
- [제9회 확장 운용]
- [제10회 보안과 안전 운용]
지금까지 대화 루프, 상태, 기억이라는 「중추」를 살펴보았다. 후반전의 입구로서, 에이전트의 「손과 발」——툴(Tool)을 정리한다. 제1회에서 언급했듯이, tools/ 직하에는 82개의 파일이 있지만, 실제로 호출할 수 있는 툴은 71개다. 이번에는 그 71개를 생략 없이 전부 나열한다. 카탈로그로서 곁에 둘 수 있도록 하는 것이 목적이다.
툴은 중앙 명부에 수동으로 등록되는 것이 아니다. 각 툴 모듈이 import 되는 순간 registry.register(...)를 호출하여 스스로를 등록한다——자기 등록 방식이다.
게다가, 각 툴의 가용성에는 30초 TTL (Time To Live) 캐시가 적용된다 (tools/registry.py:121). 툴을 사용할 수 있는지 여부를 판정하는 check_fn은 자격 증명이나 환경 변수의 유무를 확인하는데, 매번 평가하면 무겁다. 30초 캐시로 「최근의 판정 결과」를 재사용한다.
규모를 다시 확정한다. 레지스트리(Registry) 등록 툴은 71개, tools/ 직하는 82개 파일, 재귀적으로 탐색하면 99개(승인·URL 안전 체크 등의 비툴 모듈 포함)다. 「82개 툴」은 오류라는 점이 제1회부터의 일관된 주의 사항이다.
레지스트리 실측치인 71개를 카테고리별로 전수 나열한다. 각 툴은 check_fn을 통해 자격 증명/환경이 갖춰졌을 때만 유효해진다 (예: Home Assistant 계열은 HASS_TOKEN, x_search는 xAI 인증).
| 툴 | 설명 |
|---|---|
web_search | Web 검색. 기본적으로 최대 5건(제목 / URL / 설명)을 반환 |
web_extract | URL로부터 본문을 Markdown으로 추출 (PDF / arXiv도 가능) |
x_search | xAI의 X(Twitter) 검색 (게시물 / 프로필 / 스레드. 현재의 논의·반응 확인용, 기본 off) |
| 툴 | 설명 |
|---|---|
vision_analyze | 이미지를 대화에 불러오기 (URL / 로컬 / dataURL). 네이티브 vision 모델로 시각 확인 |
video_analyze | 동영상 (URL / 로컬)을 멀티모달 모델 (Gemini 등)로 해석 |
image_generate | 텍스트로부터 고품질 이미지 생성 (백엔드 = FAL / OpenAI 등은 사용자 설정) |
video_generate | 텍스트 / 이미지로부터 동영상 생성 (스키마는 실행 시 동적으로 구축) |
| 툴 | 설명 |
|---|---|
terminal | 쉘(Shell) 커맨드 실행 (Linux 환경, 상태는 통상 영구적). cat / head / tail은 사용하지 않고 read_file 사용을 권장 |
process | terminal(background=true)의 백그라운드 프로세스 관리 (list / poll / log 등) |
read_file | 행 번호를 포함하여 파일 읽기 (페이징, cat / head / tail의 대체) |
write_file | 파일 전체 교체 쓰기 (상위 디렉토리 자동 생성, echo / heredoc의 대체) |
patch | 파일의 find-and-replace (9가지 전략의 퍼지 매칭(Fuzzy Match), sed / awk의 대체) |
search_files | 내용 검색 / 파일명 검색 (ripgrep 기반, grep / find / ls의 대체) |
| 도구 | 설명 |
|---|---|
browser_navigate | URL로 이동 및 세션 초기화 (다른 browser_* 도구 사용을 위한 전제 조건) |
browser_snapshot | 액세서빌리티 트리 (Accessibility Tree)의 텍text 스냅샷 (요소에 @e1 등의 ref ID 부여) |
browser_click | ref ID로 요소 클릭 |
browser_type | 입력란에 ref 지정하여 타이핑 (먼저 입력 내용 삭제) |
browser_scroll | 페이지 스크롤 |
browser_back | 히스토리 뒤로 가기 |
browser_press | 키 입력 (Enter / Tab / 단축키) |
browser_get_images | 페이지 내 이미지의 URL / alt 목록 (Vision 분석용) |
browser_vision | 스크린샷을 통한 시각적 확인 |
browser_console | 콘솔 출력 / JS 에러 취득. expression 지정 시 페이지 문맥에서 JS 평가 가능 |
browser_cdp | 로우(raw) Chrome DevTools Protocol 명령 (에스케이프 해치) |
browser_dialog | 네이티브 다이얼로그 (alert / confirm / prompt)에 대한 응답 |
| 도구 | 설명 |
|---|---|
todo | 세션 내 태스크 리스트 관리 (3단계 이상의 작업 시 권장) |
memory | 세션 간 영구 메모리 저장 (향후 턴에 주입. 간결하게 유지할 것) |
session_search | 로컬 SQLite의 과거 세션을 FTS5로 검색 (LLM 미사용) |
clarify | 사용자에게 확인 질문 (선택식 / 자유 기술) |
| 도구 | 설명 |
|---|---|
skills_list | 이용 가능한 스킬 목록 (이름 + 설명) |
skill_view | 스킬 본문 / 부속 스크립트·템플릿 로드 |
skill_manage | 스킬 생성 / 업데이트 / 삭제 (절차적 기억. ~/.hermes/skills) |
| 도구 | 설명 |
|---|---|
execute_code | Hermes 도구를 호출할 수 있는 Python 실행 (3회 이상의 도구 호출 Round Trip 감소) |
delegate_task | 격리된 컨텍스트에서 서브 에이전트 (Sub-agent) 생성 (독자적인 대화 / 터미널 / 도구 세트) |
mixture_of_agents | 난제를 여러 프론티어 LLM(Frontier LLM)으로 협업 (5 API 호출 = 참조 4 + 집약 1) |
| 도구 | 설명 |
|---|---|
text_to_speech | 텍스트 → 음성 (MEDIA: 경로를 반환하며, 각 플랫폼이 음성으로 송출) |
cronjob | cron 작업 관리 (create / list / update / pause / resume / remove / trigger) |
send_message | 연결된 메시징 플랫폼으로 전송 / 수신처 목록 |
HERMES_KANBAN_TASK
설정 시에만 유효해지는, 영구 태스크 보드용 작업 도구군 (상세 내용은 제7회).
| 도구 | 설명 |
|---|---|
kanban_show | 태스크의 모든 상태 (본문 / 담당 / 부모 핸드오프 / 과거 시도 / 코멘트 / 이벤트) 읽기 |
kanban_list | 태스크 요약 목록 (Orchestrator가 라우팅용으로 사용. 담당 / 상태로 필터링) |
kanban_complete | 태스크 완료 + 구조화된 핸드오프 (summary / result / metadata) |
kanban_block | 사용자 입력 대기를 위해 blocked 상태로 변경 (이유를 보드에 표시) |
kanban_heartbeat | 장시간 처리 중인 작업의 생존 신호 (Heartbeat) |
kanban_comment | 스레드에 영구 코멘트 추가 |
kanban_create | 새 태스크 생성 (현재 태스크의 자식 태스크로도 생성 가능) |
kanban_link | 부모 → 자식 의존성 엣지(Edge) 추가 (부모가 done 상태가 되기 전까지 자식은 ready 상태가 되지 않음) |
kanban_unblock | blocked 상태를 ready 상태로 변경 (Orchestrator 한정) |
| 도구 | 설명 |
|---|---|
ha_list_entities | 엔티티 목록 (domain / area로 필터링) |
ha_get_state | 단일 엔티티의 상세 상태 (속성 포함) |
ha_list_services | 제어용 서비스 (액션) 목록 |
ha_call_service | 서비스 호출을 통한 디바이스 제어 |
| 도구 | 설명 |
|---|---|
discord | 서버 읽기 / 참여 (멤버 검색 / 메시지 취득 / 스레드 생성) |
discord_admin | 서버 관리 (채널 / 역할 목록, 핀, 역할 부여) |
| 도구 | 설명 |
|---|---|
feishu_doc_read | 문서의 전문을 플레인 텍스트 (Plain Text)로 읽기 |
feishu_drive_list_comments | 문서의 댓글 목록 |
feishu_drive_list_comment_replies | 댓글 스레드의 답글 목록 |
feishu_drive_reply_comment | 로컬 (인용 텍스트) 댓글에 답글 달기 |
feishu_drive_add_comment | 문서 전체 댓글 신규 추가 |
| 도구 | 설명 |
|---|---|
spotify_playback | 재생 제어 / 재생 상태 / 최근 재생 |
spotify_devices | Connect 디바이스 목록 / 재생 전송 |
spotify_queue | 큐 (Queue) 확인 / 추가 |
spotify_search | 카탈로그 검색 (곡 / 앨범 / 아티스트 / 플레이리스트 / 프로그램 / 에피소드) |
spotify_playlists | 플레이리스트 목록 / 열람 / 생성 / 갱신 / 편집 |
spotify_albums | 앨범 메타데이터 / 트랙 취득 |
spotify_library | 저장된 트랙 / 앨범 목록 / 저장 / 삭제 |
| 도구 | 설명 |
|---|---|
yb_query_group_info | 그룹 (파 / Pai)의 기본 정보 (이름 / 소유자 / 인원수) |
yb_query_group_members | 그룹 멤버 조회 (@멘션 / Bot 탐지용) |
yb_send_dm | 그룹 내 사용자에게 DM 전송 (미디어 가능, 이름으로 식별) |
yb_search_sticker | 내장 스티커 (이모티콘) 키워드 검색 |
yb_send_sticker | 내장 스티커 전송 |
| 도구 | 설명 |
|---|---|
computer_use | macOS 데스크톱 배경 조작 (스크린샷 / 마우스 / 키보드 / 스크롤 / 드래그. 커서 / 포커스를 뺏지 않음) |
합계는 71개입니다. 내역은 Web 3 + 비전/생성 4 + 단말/파일 6 + 브라우저 12 + 계획/대화 4 + 스킬 3 + 실행/위임 3 + 음성/스케줄/전송 3 + Kanban 9 + HA 4 + Discord 2 + Feishu 5 + Spotify 7 + Yuanbao 5 + computer_use 1 = 71입니다.
카탈로그를 살펴보면 Hermes가 "범용 코어 + 플랫폼별 도구 세트"라는 구조를 취하고 있음을 알 수 있습니다. Web / 파일 / 브라우저 / 실행 계열이 코어의 범용 능력이며, Discord / Feishu / Spotify / Yuanbao는 특정 서비스용 세트입니다. 후자는 자격 증명(Credentials)이 없으면 check_fn에 의해 비활성화되므로, 71개 전부가 항상 활성화되어 있는 것은 아닙니다.
도구는 개별적으로 활성화할 뿐만 아니라, **도구 세트 (Toolsets)**로 묶어서 다룰 수 있습니다. TOOLSETS는 57개 엔트리 (기능 계열 33 + hermes-* 서피스 / 플랫폼 24)로 구성됩니다. includes를 통해 다른 세트를 합성할 수 있으며, 배치 실행용으로는 확률 분포를 가집니다 (학습 데이터 생성 시 다양한 도구 구성을 샘플링하기 위함. 제9회 참고). 전체 57개 목록은 원문 맵 §4.2를 참조하십시오.
파괴적인 작업에는 승인 게이트가 적용됩니다. DANGEROUS_PATTERNS에는 rm -rf / sudo / git
의 force 계열 등이 등록되어 있으며, 이에 매칭되는 커맨드는 승인을 요구한다. 하드라인 (Hardline) (반드시 중단)과, --yolo에 의한 바이패스 (Bypass) (모든 승인 스킵)라는 양극단이 존재하며, 후자는 제10회에서 "최대급의 리스크"로 다룬다.
SSRF 대책: 클라우드의 메타데이터 IP (169.254.169.254 등)를 상시 차단. URL을 다루는 툴이 내부 메타데이터를 탈취하는 고전적인 공격을 방어함
패스 트래버설 (Path Traversal) 대책: Path.resolve() + relative_to()를 사용하여 워크스페이스 외부로 탈출하는 것을 방지함
샌드박스 (Sandbox): execute_code에서 호출할 수 있는 Hermes 툴은 7종으로 제한. 여기에 추가로 timeout 300초 / 50회 호출 / 출력 50KB / 1개 툴 결과 10KB의 상한을 가짐 (code_execution_tool.py:61)
execute_code는 "Python에서 Hermes 툴을 호출하는" 강력한 통로인 만큼, 호출 가능한 툴을 7종으로 압축하고 실행 시간·횟수·출력량에 천장을 설정해 두었다. 편의성과 공격 표면 (Attack Surface) 사이의 트레이드오프 (Trade-off)를 상한값 설정이라는 방식으로 해결한 형태다.
다음 회차에서는 툴 중에서도 격이 다른 두 가지 —— delegate_task와 mixture_of_agents, 멀티 에이전트 병렬 처리에 대해 깊이 파고든다.
대응 맵 장: §4 / 행 번호는 hermes update에 따라 어긋날 수 있음
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기