도구 개요
도구가 등록되고, 설정으로 활성화되며, 에이전트 레지스트리에 조합되는 방식과 i18n 설명에 대해 설명합니다.
도구란 Revka가 에이전틱 루프 중에 LLM에 제공하는 호출 가능한 기능입니다 — 셸 실행, 파일 편집, 웹 fetch, 크론 스케줄링, 코드 에이전트 위임, MCP 브리징 등 약 90여 가지가 있습니다. 이 페이지에서는 도구가 등록되는 방식, 시작 시 레지스트리가 구성되는 방식, 개별 도구가 설정에 의해 활성화되는 방식, 그리고 도구 설명이 현지화되는 방식을 설명합니다.
특정 도구가 에이전트에서 사용 가능하거나 그렇지 않은 이유, 혹은 도구를 활성화하는 방법을 이해하려면 이 페이지를 참고하세요. 개별 도구의 동작 및 파라미터는 하단에 링크된 도구 레퍼런스 페이지를 참조하세요.
도구 레지스트리 모델
섹션 제목: “도구 레지스트리 모델”모든 도구는 세 가지 안정적인 구성 요소를 가진 공통 Tool 트레이트를 구현합니다:
- 이름 (예:
shell,web_fetch) — 모델이 호출할 때 사용하는 식별자, - 인수를 설명하는 JSON 파라미터 스키마, 그리고
- 도구를 실행하고 결과를 반환하는 비동기
execute메서드.
시작 시 Revka는 박스형 도구의 Vec인 레지스트리를 구성하고 에이전트 루프에 전달합니다. 모델은 각 도구의 이름, 설명, 파라미터 스키마를 확인하며, 도구 호출을 emit하면 루프가 해당 도구의 execute로 디스패치합니다. 보안 정책 적용은 각 도구의 생성 시점에 주입되므로 자율성 수준, 명령어 허용 목록, 경로 경계가 호출 위치마다 재확인되지 않고 일관되게 적용됩니다.
두 가지 레지스트리 빌더가 있습니다:
default_tools— 최소 레지스트리 (설정 및 런타임 통합 없음).all_tools_with_runtime— 프로덕션에서 사용하는 전체 레지스트리로, 항상 활성화된 코어에서 시작해 설정에 따라 도구를 조건부로 추가합니다.
최소 레지스트리 vs 전체 레지스트리
섹션 제목: “최소 레지스트리 vs 전체 레지스트리”최소 레지스트리
섹션 제목: “최소 레지스트리”최소 레지스트리에는 파일시스템 및 코드 관련 기본 도구 7가지가 정확히 포함됩니다:
| 도구 | 용도 |
|---|---|
shell | 워크스페이스에서 셸 명령어 실행 |
file_read | 줄 번호와 함께 파일 읽기 (오프셋/제한, 인라인 PDF 텍스트) |
file_write | 워크스페이스의 파일 쓰기 (덮어쓰기) |
file_edit | 파일에서 첫 번째로 정확히 일치하는 문자열 교체 |
glob_search | glob 패턴과 일치하는 파일 목록 조회 |
content_search | 정규식으로 파일 내용 검색 (ripgrep, grep 폴백) |
semantic_code_search | 토큰 효율적인 코드 검색 (Semble → ripgrep → 리터럴) |
이 세트는 통합이 활성화되지 않은 경우 제공되는 기본값이며, 전체 레지스트리의 기반이 됩니다.
전체 레지스트리
섹션 제목: “전체 레지스트리”all_tools_with_runtime은 Revka가 실제로 실행하는 레지스트리입니다. 항상 등록되는 코어 — 7개의 최소 도구와 활성화 플래그가 없는 도구들 — 로 시작하고, 그 외 모든 것은 조건부로 추가됩니다. 항상 활성화되는 코어에는 크론 도구(cron_add, cron_list, cron_remove, cron_update, cron_run, cron_runs), schedule, git_operations, pushover, calculator, weather, canvas, model_routing_config, model_switch, proxy_config, 그리고 프로바이더가 설정된 경우 등록되는 llm_task도 포함됩니다.
그 코어를 넘어서는 브라우저, HTTP, 웹 검색, SOP 실행, 코드 에이전트 위임, 스웜, 생산성 통합, 하드웨어, MCP 브리징 등은 모두 설정으로 활성화됩니다: 해당 기능을 켰을 때만 레지스트리에 등록됩니다.
설정 기반 활성화
섹션 제목: “설정 기반 활성화”설정 기반 활성화는 전체 레지스트리가 무엇을 포함할지 결정하는 방식입니다. 각 선택적 도구에 대해 빌더는 플래그(및 필요한 자격 증명)를 확인한 후 도구를 레지스트리에 추가합니다. 일반적인 패턴은 도구의 설정 섹션 아래에 enabled 불리언을 사용하는 것입니다:
[browser]enabled = trueallowed_domains = ["docs.example.com"]
[http_request]enabled = trueallowed_domains = ["api.example.com"]
[web_fetch]enabled = true
[web_search]enabled = trueprovider = "brave"이렇게 설정하면 browser/browser_open, http_request, web_fetch, web_search_tool이 등록됩니다. 섹션을 생략하거나 enabled = false로 설정하면 해당 도구는 레지스트리에 등록되지 않으며 — 레지스트리에 없는 도구는 모델이 호출할 수 없습니다.
활성화 방식에는 몇 가지 중요한 예외가 있습니다:
- 자격 증명도 활성화 조건입니다. 일부 도구는 활성화 플래그 외에도 키가 필요합니다. 예를 들어,
notion.enabled = true로 설정해도notion.api_key나NOTION_API_KEY환경 변수가 없으면 경고와 함께 등록이 건너뛰어집니다.jira도 마찬가지로 토큰,base_url,email이 모두 필요합니다. - 런타임 기능도 활성화 조건입니다.
browser_delegate처럼 셸을 사용하는 도구는enabled = true로 설정해도, 활성 런타임이 셸 접근을 허용하지 않으면 경고와 함께 건너뛰어집니다. - 설정은 단순한 on/off가 아닌 변형을 선택합니다. 플래그에 따라 등록되는 도구가 달라질 수 있습니다.
skills.prompt_injection_mode = "compact"이면 모델이 필요 시 전체 스킬 텍스트를 가져올 수 있도록read_skill도구가 추가되지만,full모드에서는 추가되지 않습니다. - 존재 기반 활성화. 일부 도구는
enabled플래그 대신 설정 블록의 존재 여부로 활성화됩니다 —delegate는[agents.<name>]블록이 하나 이상 있을 때,swarm은[swarms.<name>]블록이 하나 이상 있을 때 등록됩니다.
주요 활성화 조건 요약표 (전체 목록은 개별 도구 페이지를 참조):
| 도구 | 활성화 조건 |
|---|---|
browser, browser_open | browser.enabled = true |
browser_delegate | browser_delegate.enabled = true + 셸 접근 |
text_browser | text_browser.enabled = true |
http_request | http_request.enabled = true |
web_fetch | web_fetch.enabled = true |
web_search_tool | web_search.enabled = true |
notion, jira, linkedin 등 | 섹션 enabled = true + 자격 증명 |
cloud_ops, cloud_patterns | cloud_ops.enabled = true |
sop_* | sop.sops_dir 설정됨 |
delegate | [agents.<name>] 하나 이상 |
swarm | [swarms.<name>] 하나 이상 |
read_skill | skills.prompt_injection_mode = "compact" |
| 외부 MCP 도구 | [mcp] enabled = true + [[mcp.servers]] |
[shell_tool] 설정
섹션 제목: “[shell_tool] 설정”shell 도구는 항상 존재하지만, [shell_tool] 섹션을 통해 실행 동작을 조정할 수 있습니다:
[shell_tool]timeout_secs = 60| 키 | 타입 | 기본값 | 설명 |
|---|---|---|---|
timeout_secs | integer | 60 | 단일 셸 명령어가 종료되기 전까지 실행될 수 있는 최대 실제 경과 시간 |
[shell_tool] 외에도, shell 도구의 출력은 1 MB로 제한되며, 환경은 안전한 허용 목록(PATH, HOME, TERM 등)으로 정제됩니다. 커스텀 환경 변수에 의존하는 스크립트는 security.shell_env_passthrough에 추가하거나 명령어에 인라인으로 전달해야 합니다. command 인수는 명령어를 실행하며, 선택적 approved 불리언(기본값 false)은 감독 모드에서 중간/고위험 명령어를 명시적으로 승인합니다.
셸 도구가 허용하는 작업 — 명령어 허용 목록, 경로 경계, 위험 수준 제어, 승인 — 은 [shell_tool]이 아닌 [autonomy] 보안 정책이 별도로 관장합니다. 정책, 명령어 및 샌드박싱과 보안 모델을 참조하세요.
도구 설명 로케일 (i18n)
섹션 제목: “도구 설명 로케일 (i18n)”도구 설명 — 모델이 도구를 언제 사용할지 결정하기 위해 읽는 텍스트 — 은 현지화할 수 있습니다. 로케일별 설명은 tool_descriptions/ 아래에 로케일당 하나의 TOML 파일(en.toml, de.toml, fr.toml, ja.toml, ko.toml, zh-CN.toml 등)로 저장됩니다. 각 파일에는 도구 이름을 키로 하는 [tools] 테이블이 있습니다:
[tools]file_read = "Read file contents with line numbers. Supports partial reading via offset and limit."glob_search = "Search for files matching a glob pattern within the workspace."로케일 결정 순서
섹션 제목: “로케일 결정 순서”Revka는 다음 순서로 활성 로케일을 선택합니다:
-
locale설정 필드 —config.locale이 설정되어 있고 비어 있지 않으면 해당 값을 직접 사용합니다. -
환경 감지 — 그렇지 않으면
REVKA_LOCALE, 이후LANG, 이후LC_ALL순서로 로케일을 감지합니다. 값은 정규화되며(예:zh_CN.UTF-8→zh-CN),C/POSIX는 무시됩니다. -
영어 기본값 — 아무것도 해석되지 않으면 로케일은
en으로 설정됩니다.
키 단위 영어 폴백
섹션 제목: “키 단위 영어 폴백”로딩은 파일 수준이 아닌 키 수준에서 복원력을 갖습니다:
- 해석된 로케일 파일에서 도구 이름을 조회합니다.
- 해당 파일에 키가 없거나(또는 파일 자체가 없는 경우),
en.toml로 폴백합니다.
따라서 일부만 번역된 로케일도 정상 동작합니다 — 번역된 도구는 현지화된 설명을 사용하고, 아직 번역되지 않은 도구는 빈 값 대신 영어로 폴백됩니다.
로케일 파일 검색 위치
섹션 제목: “로케일 파일 검색 위치”Revka는 다음 순서로 여러 디렉터리에서 tool_descriptions/<locale>.toml을 검색합니다:
- 워크스페이스 디렉터리 (프로젝트 로컬 재정의용),
- 바이너리의 상위 디렉터리 (설치된 배포판용), 그리고
- 프로젝트 루트 (개발 시간 폴백).
워크스페이스가 먼저 검색되므로, 워크스페이스에 커스터마이징된 tool_descriptions/<locale>.toml을 추가하면 배포에 포함된 기본 설명을 재정의할 수 있습니다.