콘텐츠로 이동

앱 제어 도구 레퍼런스

이 페이지는 도구 호출에 옵트인한 플러그인에 호스트가 노출하는 애플리케이션 제어 도구의 도구별 레퍼런스이며, 데이터 허브 문서 도구 다섯 개를 다루는 별도의 Data 카테고리도 함께 담고 있습니다. 플러그인이 어떻게 옵트인하고 루프를 렌더링하는지는 먼저 플러그인 개발 가이드의 도구 호출 절을 읽으세요. 이 페이지는 그것을 읽었다고 가정합니다.

아래 도구들은 하나의 Rust 도구 카테고리 AppControl을 공유하며, 한 가지 속성을 공유합니다: 모든 도구가 새롭거나 플랫폼 특정적인 코드 경로가 아니라 기존 내부 서비스(추론 풀, 모델 관리자, 다운로드 관리자, 통계 관리자, Hugging Face 검색, autonomous 프로바이더, Hermes 설정, 스쿼드 스토리지)를 거칩니다. 이들은 실행 중인 애플리케이션을 관찰하고 조작합니다.

카탈로그

아래 모든 도구의 카테고리는 AppControl입니다. "승인"은 도구 정의가 requires_approval: true(상태 변경 도구)를 설정하면 필요이고, 읽기 전용 도구는 없음입니다. 모델 계열 백엔드 도구는 데스크톱 전용입니다(런타임 가용성 참고). autonomous-agent 도구와 스쿼드 도구는 두 런타임 모두에서 동작하고, navigate_to_page는 WebView에서 실행됩니다.

도구 승인 용도
list_models 없음 이 애플리케이션이 아는 모델 목록: 다운로드된 로컬 모델과 로드 상태, 추천 등급 메타데이터와 기기 적합도 라벨.
get_inference_status 없음 로컬 추론 서버 풀의 라이브 상태: 어떤 모델이 로드되었는지, 서빙 별칭, 포트, 상태(health).
list_downloads 없음 진행 중이거나 최근 완료된 모델 다운로드와 진행률 목록.
get_token_usage_stats 없음 토큰 사용량과 요청 통계: 총합, 일자별 분석, 모델별 사용량.
search_huggingface_models 없음 Hugging Face에서 다운로드 가능한 모델을 검색하고, 각 모델이 이 기기의 메모리와 가속기에 맞는지 보고합니다. 네트워크 필요.
list_autonomous_providers 없음 이 런타임이 아는 autonomous-agent 프로바이더와 가용성, 사용할 수 없는 이유, 기능, 설치 상태, 게이트웨이 상태를 나열합니다.
get_autonomous_gateway 없음 autonomous-agent 프로바이더 하나의 최신 캐시된 게이트웨이 상태를 반환합니다.
list_autonomous_channels 없음 autonomous-agent 프로바이더의 메시징 채널을 최대 50개 나열합니다.
list_autonomous_channel_messages 없음 프로바이더 채널 하나의 최근 메시지를 최대 50개 나열합니다.
send_autonomous_message 필요 프로바이더 채널 하나로 메시지를 보냅니다. 헤드리스 호출자는 autonomous_message_send 또는 Admin도 필요합니다.
list_hermes_pending_approvals 없음 운영자 결정을 기다리는 Hermes 거버넌스 요청을 나열합니다.
decide_hermes_approval 필요 대기 중인 Hermes 거버넌스 요청 하나를 승인하거나 거부합니다. 헤드리스 호출자는 container_write 또는 Admin도 필요합니다.
list_squads 없음 기존 스쿼드의 이름, 설명, 에이전트 수, 상태 목록.
get_squad 없음 스쿼드 하나의 설정: 상태, 워크스페이스 경로, 플래너 에이전트, 에이전트 명단(id, 이름, 역할, 모델).
list_squad_templates 없음 설치된 스쿼드 템플릿(기본 제공 및 사용자 생성) 목록.
list_squad_tasks 없음 스쿼드의 관리 태스크와 제목, 담당자, 상태, 선행 태스크. 상태로 필터링 가능.
get_squad_execution 없음 실행 하나의 단계, 웨이브 진행도, 계획 태스크, 최종 결과, 토큰 사용량.
list_squad_executions 없음 스쿼드의 기록된 실행 이력(최신순).
load_model 필요 다운로드된 로컬 모델을 추론 서버에 로드합니다. 로드를 시작하고 즉시 반환합니다.
unload_model 필요 현재 로드된 모델을 추론 서버에서 언로드합니다.
download_model 필요 Hugging Face에서 모델을 로컬 모델 저장소로 다운로드합니다. 한 번의 호출로 선택한 모델에 필요한 파일을 모두 가져옵니다: 분할 모델의 모든 샤드, safetensors 모델의 경우 config와 tokenizer 파일까지. 다운로드를 시작하고 즉시 반환합니다. 네트워크 필요.
create_squad 필요 새 스쿼드를 생성합니다. list_squad_templates의 templateId를 우선 사용해 검증된 에이전트 구성으로 시작하게 합니다.
submit_squad_request 필요 스쿼드에 요청을 제출해 실행을 생성합니다.
approve_squad_plan 필요 승인 대기 중인 계획을 승인하고 실행을 시작합니다. 데스크톱과 헤드리스 서버에서 동일합니다.
reject_squad_plan 필요 계획을 반려합니다. 피드백이 플래너에 전달되어 같은 실행을 다시 계획하며, 수정된 계획은 승인 대기 상태로 남고 결과에 새 작업 수와 웨이브 수가 담깁니다.
cancel_squad_execution 필요 아직 끝나지 않은 실행을 취소합니다.
steer_squad_execution 필요 실행 중이거나 일시 정지 또는 미승인 상태인 실행에 상시 지시를 전달합니다. 이후 조건이 맞는 모든 턴에 적용되며, 이미 진행 중인 작업은 중단되지 않습니다.
send_squad_agent_message 필요 스쿼드 에이전트 한 명에게 메시지를 보내고 턴을 실행합니다. 응답은 도구 결과가 아니라 스쿼드 채팅 세션으로 스트리밍됩니다.
navigate_to_page 없음 호스트 라우터를 통해 애플리케이션을 최상위 페이지로 이동합니다. 프런트엔드 도구로, 백엔드가 아니라 WebView에서 실행됩니다.

플러그인은 도구 이름이 매니페스트 tools 허용 목록에 있을 때만 그 도구를 광고합니다. 기본 제공 Companion Chat 플러그인은 그중 열두 개를 허용 목록에 넣습니다. 이슈 #4581에서 추가된 스쿼드 도구와 이슈 #4608에서 추가된 autonomous-agent 도구는 그 목록에 없으므로, 필요한 플러그인은 자체 매니페스트에 이름을 추가하면 됩니다.

승인과 프롬프트 인젝션 태세

상태 변경 도구(load_model, unload_model, download_model, send_autonomous_message, decide_hermes_approval과 상태를 바꾸는 모든 스쿼드 도구: create_squad, submit_squad_request, approve_squad_plan, reject_squad_plan, cancel_squad_execution, steer_squad_execution, send_squad_agent_message)는 requires_approval: true를 가집니다. SDK는 호출별 명시적 사용자 승인 없이 절대 그것을 실행하지 않으며, 플러그인이 승인 콜백을 제공하지 않으면 기본적으로 거부합니다. 이는 간접 프롬프트 인젝션에 대한 주요 방어입니다: Memory Bank 콘텐츠를 시스템 프롬프트에 주입하는 컴패니언은 공격자가 영향을 줄 수 있는 텍스트를 주입하는 것이므로, 상태를 변경하는 동작은 절대 자동 실행되어서는 안 됩니다. 기본 거부 승인을 참고하세요.

읽기 전용 도구는 자동 승인 가능하며 프롬프트 없이 실행되지만, 그 활동은 여전히 onToolCallStart / onToolResult 콜백을 통해 드러납니다.

장시간 실행 동작의 시작-후-폴링

load_model과 download_model은 동작이 끝날 때까지 도구 결과를 블록하지 않습니다. 요청을 검증하고, 동작을 백그라운드에서 시작한 뒤 즉시 반환합니다. 이는 도구 턴을 빠르게 유지하고, 몇 분짜리 다운로드에서 모델이나 HTTP 타임아웃이 발생하는 것을 피합니다. 모델은 읽기 전용 상태 도구를 폴링해 진행을 관찰합니다:

  • get_inference_status는 모델이 로드 상태로 전환되는 것을 반영합니다.
  • list_downloads는 다운로드 진행과 완료를 보고합니다.

download_model은 파일 단위가 아니라 모델 단위입니다. 한 번의 호출이 선택한 변형의 전체 파일 집합을 한 요청으로 등록하므로, 호출 한 번에 list_downloads 항목이 여러 개 보이고 분할 모델의 샤드 하나만 지정해도 전부 내려받습니다. 파일마다 호출하는 것은 불필요할 뿐 아니라 해롭습니다: 두 호출 사이에는 다운로드 목록이 부분 집합만 담고, 완료 알림이 이를 끝난 모델로 읽어 가중치가 도착하기 전에 완료를 알립니다(이슈 #4493).

기본 제공 컴패니언의 시스템 프롬프트는 이 동작을 인코딩하여, 모델이 기다리는 대신 동작이 시작되었다고 보고하고 폴링하게 합니다.

로컬 우선 모델 추천

전용 "모델 추천" 도구는 없습니다. 추천은 두 도구가 제공하는, 근거 있고 적합도가 주석된 후보들에 대해 모델이 수행하는 창발적 동작입니다:

  • list_models는 이미 다운로드된 각 모델에 대해 기기 적합도 라벨을 담습니다.
  • search_huggingface_models는 아직 다운로드되지 않은 모델을 다루며, 각 모델에 이 기기의 메모리와 가속기에 맞는지를 주석으로 답니다.

컴패니언의 시스템 프롬프트는 로컬 우선 순서를 인코딩합니다: 먼저 list_models로 다운로드된 모델을 확인하고, 적합도가 "too large"가 아닌 적절한 모델을 추천하며, 로컬에 맞는 것이 없을 때만 search_huggingface_models를 호출합니다. 제안된 Hugging Face 모델은 로드하기 전에 다운로드되어야 하며, 모델에게 그렇게 말하도록 지시됩니다.

오프라인 및 에어갭 배포

두 도구는 네트워크 접근이 필요합니다: search_huggingface_models와 download_model. 에어갭 엔터프라이즈 배포는 별도 모드 없이 지원됩니다. 엔터프라이즈 도구 정책은 이 두 도구를 개별적으로 거부할 수 있고, 광고되는 도구 집합은 매니페스트 허용 목록, 호스트 카탈로그, 엔터프라이즈 정책의 교집합(매 턴 다시 계산됨)이므로, 이들을 거부한 배포는 플러그인이 로컬 도구만 광고하게 됩니다. 추천과 로드는 그러면 전적으로 이미 다운로드된 모델에서만 동작하고, 다운로드는 절대 제안되거나 시도되지 않습니다. 단순 네트워크 실패 시 네트워크가 필요한 도구는 멈추는 대신 설명이 담긴 도구 오류로 실패합니다. 두 경우 모두 플러그인 코드 변경이 필요 없습니다.

엔터프라이즈 도구 정책

모든 도구는 호스트의 기본 제공 실행 경로를 거치며, 이 경로는 모든 호출에서 엔터프라이즈 도구 정책 게이트를 실행합니다(Tauri, REST, 레지스트리 폴백 경로 모두). 관리자가 거부한 도구는 광고 집합에서 걸러지고, 그 이름을 대는 모델조차 실행 대신 구조화된 정책 거부 결과를 받습니다. 플러그인이 시작한 호출도 동일한 실행 경로를 타므로 이를 자동으로 상속하며, 플러그인 측 정책 로직은 존재하지도 필요하지도 않습니다.

런타임 가용성

모델 계열 백엔드 도구(list_models, get_inference_status, list_downloads, get_token_usage_stats, load_model, unload_model, download_model, search_huggingface_models)는 Tauri 애플리케이션 핸들이나 프로세스 전역 데스크톱 상태(추론 풀, 다운로드 관리자, 통계 관리자)가 필요합니다. 이들은 호스트의 단일 헤드리스 기능 게이트에 나열되어 available_in_headless: false로 설정됩니다. SDK 루프는 라이브 카탈로그에서 그 플래그를 읽으므로, 헤드리스나 브라우저 컨텍스트에서는 이 도구들이 모델에 아예 광고되지 않으며, 다른 것이 없으면 턴은 평문 채팅으로 저하됩니다. navigate_to_page는 WebView에서 실행되는 프런트엔드 도구로 마찬가지로 비헤드리스로 표시됩니다.

스쿼드 도구는 예외이며, 처음부터 그랬던 것은 아닙니다. 이슈 #4581 이전에는 이들도 애플리케이션 핸들을 통해 스쿼드 스토리지에 접근했습니다. 지금은 데스크톱 앱과 헤드리스 Management API가 시작 시 각각 설치하는 프로세스 전역 핸들을 통해 스쿼드 서브시스템에 접근합니다. 데이터 허브 도구와 같은 구조이며, 그래서 13개 모두 available_in_headless가 true이고 POST /api/v1/tools/execute와 MCP 엔드포인트에서 동작합니다.

이슈 #4954 이후로 두 런타임은 같은 일을 합니다. submit_squad_request는 플래너를 실행하고 autoApprove가 켜져 있으면 run_squad_execution을 스폰하며, approve_squad_plan은 승인을 기다리던 계획에 대해 이를 스폰합니다. 각 도구 결과는 무엇이 일어났는지를 plannerStarted와 executorStarted로 여전히 보고하므로, 호출자가 작업 시작 여부를 짐작할 필요가 없습니다. plannerStarted는 런타임이 제출 경로를 호출했는지가 아니라 플래너가 실제로 요청을 분해했는지를 답합니다. 라우터가 꺼져 있거나 플래너 에이전트에 쓸 수 있는 모델이 없거나 플래너 응답이 태스크를 하나도 만들지 않으면 run_planner_decomposition은 에이전트마다 태스크 하나씩인 폴백으로 내려앉고, 그 폴백에 안착한 제출은 plannerStarted: false와 함께 원인을 담은 plannerDegradedReason을 보고합니다(이슈 #4966). 이 사유는 실행에 남아 있으므로 이후의 모든 get_squad_execution 폴링에서도 함께 읽힙니다.

autonomous-agent 도구도 데스크톱과 헤드리스 부트스트랩이 설치하는 프로세스 전역 런타임 핸들을 사용합니다. 읽기 전용 프로바이더, 게이트웨이, 채널, 메시지, Hermes 승인 목록 도구는 헤드리스에서도 사용할 수 있습니다. 쓰기 성격의 두 도구는 헤드리스 트랜스포트에서 런타임 scope 검사를 추가로 수행합니다: send_autonomous_message는 autonomous_message_send 또는 Admin이 필요하고, decide_hermes_approval은 container_write 또는 Admin이 필요합니다. 도구는 MCP와 POST /api/v1/tools/execute에서 계속 광고됩니다. 추가 scope가 없는 호출자는 감사가 기록된 policy-denied 도구 결과를 받습니다.

데이터 허브 도구 (Data 카테고리)

데이터 허브 도구 다섯 개는 AppControl 도구가 아니지만, 플러그인이 접근하는 방식은 같습니다. 매니페스트 tools 허용 목록에 이름을 넣고 호스트 관리 루프를 쓰면 됩니다. 별도의 플러그인 원시 기능은 없습니다.

도구 승인 용도
search_data 없음 사용자가 정리해 둔 문서 저장소를 검색해 스니펫과 문서 핸들(D42)을 관련도 순으로 반환합니다.
read_data 없음 핸들로 문서 하나를 읽습니다. 기본값은 정리된 카드이며, 본문 전체나 섹션 단위로도 읽습니다.
list_data 없음 문서 목록을 반환하고, 필터 없이 호출하면 사용할 수 있는 컬렉션도 함께 반환합니다.
write_data 필요 노트를 만들거나 기존 문서의 주석 카드를 수정합니다. 모든 쓰기는 리비전으로 기록됩니다.
delete_data 필요 문서를 휴지통으로 옮깁니다. 소프트 삭제이므로 데이터 페이지에서 복원할 수 있습니다.

AppControl 카탈로그와 다른 점이 세 가지 있습니다.

  • 헤드리스에서도 동작합니다. 데스크톱 앱과 헤드리스 Management API가 시작할 때 공개하는 프로세스 전역 핸들로 저장소에 접근하므로 available_in_headless가 true이고 POST /api/v1/tools/execute로도 실행됩니다.
  • 범위는 서버에서 강제합니다. 모델 인자에 담긴 컬렉션 이름은 저장소가 해석하며, 반환되는 모든 문서는 해석된 범위로 걸러집니다. 민감(sensitive) 으로 표시된 컬렉션은 모델이 이름을 명시해도 도구 호출로는 절대 닿을 수 없고, 그 이름은 list_data 출력에서도 빠집니다. 에이전트 프로필은 실행을 특정 컬렉션에 고정할 수 있으며, 이 고정은 범위를 좁히기만 하고 넓히지 않습니다.
  • 기존 문서의 본문은 다시 쓸 수 없습니다. 본문은 변경 불가능한 원본에서 변환 파이프라인이 다시 만들어 내므로, 도구로 수정해 봐야 조용히 사라집니다. 대신 카드에 쓰거나 새 노트를 만드세요.

write_data와 delete_data가 requires_approval: true인 이유는 변경성 AppControl 도구와 같습니다. 문서 텍스트는 신뢰할 수 없는 모델 입력이므로, 그 텍스트가 저장소를 조용히 고쳐 쓰거나 지우게 해서는 안 됩니다.

함께 보기