툴셋 참조
툴셋(toolset)은 에이전트가 무엇을 할 수 있는지 제어하는 이름 있는 도구 묶음입니다. 플랫폼별, 세션별, 작업별로 도구 가용성을 설정하는 기본 메커니즘입니다.
툴셋 동작 방식
모든 도구는 정확히 하나의 툴셋에 속합니다. 툴셋을 활성화하면 그 묶음 안의 모든 도구가 에이전트에 제공됩니다. 툴셋은 세 종류로 나뉩니다.
- Core - 관련 도구의 단일 논리 그룹입니다. 예를 들어
file은read_file,write_file,patch,search_files를 묶습니다. - Composite - 일반적인 시나리오에 맞게 여러 core 툴셋을 조합합니다. 예를 들어
debugging은 file, terminal, web 도구를 묶습니다. - Platform - 특정 배포 맥락에 맞춘 완성형 도구 구성입니다. 예를 들어
hermes-cli는 대화형 CLI 세션의 기본값입니다.
툴셋 설정
세션 단위(CLI)
hermes chat --toolsets web,file,terminal
hermes chat --toolsets debugging # composite - file + terminal + web으로 확장
hermes chat --toolsets all # 전체 도구
플랫폼 단위(config.yaml)
toolsets:
- hermes-cli # CLI 기본값
# - hermes-telegram # Telegram 게이트웨이용 재정의
대화형 관리
hermes tools # 플랫폼별 활성화/비활성화를 위한 curses UI
세션 안에서는 다음 명령을 사용할 수 있습니다.
/tools list
/tools disable browser
/tools enable homeassistant
Core 툴셋
| 툴셋 | 도구 | 목적 |
|---|---|---|
browser | browser_back, browser_cdp, browser_click, browser_console, browser_dialog, browser_get_images, browser_navigate, browser_press, browser_scroll, browser_snapshot, browser_type, browser_vision, web_search | 핵심 브라우저 자동화입니다. 빠른 조회 대체 수단으로 web_search도 포함합니다. browser_cdp와 browser_dialog는 런타임 게이트가 있어 세션 시작 시 CDP 엔드포인트에 접근할 수 있을 때만 등록됩니다(/browser connect, browser.cdp_url 설정, Browserbase, Camofox). CDP 슈퍼바이저가 붙어 있으면 browser_snapshot이 추가하는 pending_dialogs, frame_tree 필드와 함께 browser_dialog를 사용합니다. |
clarify | clarify | 에이전트가 진행 전에 확인이 필요할 때 사용자에게 질문합니다. |
code_execution | execute_code | Hermes 도구를 프로그래밍 방식으로 호출하는 Python 스크립트를 실행합니다. |
cronjob | cronjob | 반복 작업을 예약하고 관리합니다. |
debugging | composite(file + terminal + web) | 디버깅 묶음입니다. 파일, 프로세스/터미널, 웹 추출/검색을 포함합니다. |
delegation | delegate_task | 병렬 작업을 위해 격리된 서브에이전트 인스턴스를 생성합니다. |
discord | discord | Discord text/embed/DM 작업입니다. 게이트웨이 전용이며 hermes-discord 툴셋에서 활성화됩니다. |
discord_admin | discord_admin | Discord moderation입니다. ban, role 변경, channel 관리 등을 수행합니다. hermes-discord 툴셋에서 활성화되며, 봇에 필요한 Discord 권한이 있어야 합니다. |
feishu_doc | feishu_doc_read | Feishu/Lark 문서 내용을 읽습니다. Feishu 문서 댓글 지능형 응답 핸들러가 사용합니다. |
feishu_drive | feishu_drive_add_comment, feishu_drive_list_comments, feishu_drive_list_comment_replies, feishu_drive_reply_comment | Feishu/Lark Drive 댓글 작업입니다. 댓글 에이전트에만 범위가 제한되며, hermes-cli나 다른 메시징 툴셋에는 노출되지 않습니다. |
file | patch, read_file, search_files, write_file | 파일 읽기, 쓰기, 검색, 편집입니다. |
homeassistant | ha_call_service, ha_get_state, ha_list_entities, ha_list_services | Home Assistant를 통한 스마트홈 제어입니다. HASS_TOKEN이 설정된 경우에만 사용할 수 있습니다. |
computer_use | computer_use | cua-driver를 통한 백그라운드 macOS 데스크톱 제어입니다. 커서나 포커스를 훔치지 않습니다. 도구 사용 가능 모델이면 사용할 수 있습니다. macOS 전용이며 $PATH에 cua-driver가 필요합니다. |
image_gen | image_generate | FAL.ai를 통한 text-to-image 생성입니다. OpenAI/xAI 백엔드는 옵트인입니다. |
video_gen | video_generate | 플러그인이 등록한 백엔드(xAI Grok-Imagine, FAL.ai Veo 3.1 / Pixverse v6 / Kling O3)를 통한 text-to-video 및 image-to-video입니다. 이미지를 움직이려면 image_url을 전달하고, text-to-video는 생략합니다. |
kanban | kanban_block, kanban_comment, kanban_complete, kanban_create, kanban_heartbeat, kanban_link, kanban_show | multi-agent 조정 도구입니다. 에이전트가 Kanban dispatcher에 의해 생성되고 HERMES_KANBAN_TASK 환경 변수가 설정된 경우에만 등록됩니다. worker는 구조화된 handoff로 작업 완료를 표시하고, 사용자 입력을 기다리며, 긴 작업 중 heartbeat를 보내고, thread에 comment를 남길 수 있습니다. orchestrator는 child task로 fan-out할 수 있습니다. |
memory | memory | 세션을 넘나드는 영구 메모리를 관리합니다. |
messaging | send_message | 세션 안에서 Telegram, Discord 등 다른 플랫폼으로 메시지를 보냅니다. |
moa | mixture_of_agents | Mixture of Agents를 통한 multi-model consensus입니다. |
safe | image_generate, vision_analyze, web_extract, web_search(includes를 통해) | 읽기 전용 리서치와 미디어 생성 묶음입니다. 파일 쓰기, 터미널, 코드 실행은 포함하지 않습니다. |
search | web_search | extract 없이 웹 검색만 제공합니다. |
session_search | session_search | 과거 대화 세션을 검색합니다. |
skills | skill_manage, skill_view, skills_list | 스킬 CRUD와 탐색입니다. |
spotify | spotify_albums, spotify_devices, spotify_library, spotify_playback, spotify_playlists, spotify_queue, spotify_search | Spotify 네이티브 제어입니다. playback, queue, search, playlist, album, library를 다룹니다. 번들 spotify 플러그인이 등록합니다. |
terminal | process, terminal | 셸 명령 실행과 백그라운드 프로세스 관리입니다. |
todo | todo | 세션 안의 작업 목록을 관리합니다. |
tts | text_to_speech | text-to-speech 오디오 생성입니다. |
vision | vision_analyze | vision-capable 모델을 통한 이미지 분석입니다. |
video | video_analyze | 비디오 분석과 이해 도구입니다. 기본 툴셋에는 포함되지 않는 옵트인 도구이므로 --toolsets로 명시적으로 추가해야 합니다. |
web | web_extract, web_search | 웹 검색과 페이지 콘텐츠 추출입니다. |
yuanbao | yb_query_group_info, yb_query_group_members, yb_search_sticker, yb_send_dm, yb_send_sticker | Yuanbao DM/group 작업과 스티커 검색입니다. hermes-yuanbao에서만 등록됩니다. |
Platform 툴셋
Platform 툴셋은 배포 대상별 전체 도구 구성을 정의합니다. 대부분의 메시징 플랫폼은 hermes-cli와 같은 구성을 사용합니다.
| 툴셋 | hermes-cli와의 차이 |
|---|---|
hermes-cli | 전체 툴셋입니다. 대화형 CLI 세션의 기본값입니다. file, terminal, web, browser, memory, skills, vision, image_gen, todo, tts, delegation, code_execution, cronjob, session_search, clarify, safe(읽기 전용) 묶음, 표준 messaging 도구를 포함합니다. |
hermes-acp | clarify, cronjob, image_generate, send_message, text_to_speech, Home Assistant 도구 4개를 제외합니다. IDE 맥락의 코딩 작업에 집중합니다. |
hermes-api-server | clarify, send_message, text_to_speech를 제외합니다. 나머지는 유지합니다. 사용자 상호작용이 불가능한 프로그래밍 방식 접근에 적합합니다. |
hermes-cron | hermes-cli와 동일합니다. |
hermes-telegram | hermes-cli와 동일합니다. |
hermes-discord | hermes-cli에 discord, discord_admin을 추가합니다. |
hermes-slack | hermes-cli와 동일합니다. |
hermes-whatsapp | hermes-cli와 동일합니다. |
hermes-signal | hermes-cli와 동일합니다. |
hermes-matrix | hermes-cli와 동일합니다. |
hermes-mattermost | hermes-cli와 동일합니다. |
hermes-email | hermes-cli와 동일합니다. |
hermes-sms | hermes-cli와 동일합니다. |
hermes-bluebubbles | hermes-cli와 동일합니다. |
hermes-dingtalk | hermes-cli와 동일합니다. |
hermes-feishu | feishu_doc_* / feishu_drive_* 도구 5개를 추가합니다. 일반 채팅 어댑터가 아니라 문서 댓글 핸들러에서만 사용됩니다. |
hermes-qqbot | hermes-cli와 동일합니다. |
hermes-wecom | hermes-cli와 동일합니다. |
hermes-wecom-callback | hermes-cli와 동일합니다. |
hermes-weixin | hermes-cli와 동일합니다. |
hermes-yuanbao | hermes-cli에 DM/group/sticker용 yb_* 도구 5개를 추가합니다. |
hermes-homeassistant | hermes-cli와 동일합니다. Home Assistant 도구는 기본적으로 존재하며, HASS_TOKEN이 설정되면 활성화됩니다. |
hermes-webhook | hermes-cli와 동일합니다. |
hermes-gateway | 내부 게이트웨이 오케스트레이터 툴셋입니다. 모든 hermes-<platform> 툴셋의 합집합이며, 게이트웨이가 어떤 메시지 소스든 받을 수 있어야 할 때 사용됩니다. |
Dynamic 툴셋
MCP 서버 툴셋
설정된 각 MCP 서버는 런타임에 mcp-<server> 툴셋을 생성합니다. 예를 들어 github MCP 서버를 설정하면 해당 서버가 노출하는 모든 도구를 담은 mcp-github 툴셋이 만들어집니다.
# config.yaml
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
이렇게 만들어진 mcp-github 툴셋은 --toolsets나 플랫폼 설정에서 참조할 수 있습니다.
플러그인 툴셋
플러그인은 초기화 중 ctx.register_tool()을 통해 자체 툴셋을 등록할 수 있습니다. 이렇게 등록된 툴셋은 내장 툴셋과 함께 표시되며 같은 방식으로 활성화하거나 비활성화할 수 있습니다.
사용자 정의 툴셋
프로젝트별 묶음이 필요하면 config.yaml에 사용자 정의 툴셋을 정의합니다.
toolsets:
- hermes-cli
custom_toolsets:
data-science:
- file
- terminal
- code_execution
- web
- vision
와일드카드
all또는*- 등록된 모든 툴셋으로 확장됩니다. 내장, 동적, 플러그인 툴셋을 모두 포함합니다.
hermes tools와의 관계
hermes tools 명령은 플랫폼별로 개별 도구를 켜고 끄는 curses 기반 UI를 제공합니다. 이 기능은 툴셋보다 더 세밀한 도구 단위에서 작동하며, 결과를 config.yaml에 저장합니다. 어떤 도구를 비활성화하면 그 도구의 툴셋이 활성화되어 있어도 에이전트에는 제공되지 않습니다.
개별 도구와 매개변수의 전체 목록은 도구 참조를 참고하세요.