콘텐츠로 이동

12.6. 앱 제어 도구 레퍼런스

이 페이지는 도구 호출에 옵트인한 플러그인에 호스트가 노출하는 애플리케이션 제어 도구의 도구별 레퍼런스입니다. 플러그인이 어떻게 옵트인하고 루프를 렌더링하는지는 먼저 플러그인 개발 가이드의 도구 호출 절을 읽으세요. 이 페이지는 그것을 읽었다고 가정합니다.

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

카탈로그

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

도구 승인 용도
list_models 없음 이 애플리케이션이 아는 모델 목록: 다운로드된 로컬 모델과 로드 상태, 추천 등급 메타데이터와 기기 적합도 라벨.
get_inference_status 없음 로컬 추론 서버 풀의 라이브 상태: 어떤 모델이 로드되었는지, 서빙 별칭, 포트, 상태(health).
list_downloads 없음 진행 중이거나 최근 완료된 모델 다운로드와 진행률 목록.
get_token_usage_stats 없음 토큰 사용량과 요청 통계: 총합, 일자별 분석, 모델별 사용량.
search_huggingface_models 없음 Hugging Face에서 다운로드 가능한 모델을 검색하고, 각 모델이 이 기기의 메모리와 가속기에 맞는지 보고합니다. 네트워크 필요.
list_squads 없음 기존 스쿼드의 이름, 설명, 에이전트 수, 상태 목록.
list_squad_templates 없음 설치된 스쿼드 템플릿(기본 제공 및 사용자 생성) 목록.
load_model 필요 다운로드된 로컬 모델을 추론 서버에 로드합니다. 로드를 시작하고 즉시 반환합니다.
unload_model 필요 현재 로드된 모델을 추론 서버에서 언로드합니다.
download_model 필요 Hugging Face에서 모델 파일을 로컬 모델 저장소로 다운로드합니다. 다운로드를 시작하고 즉시 반환합니다. 네트워크 필요.
create_squad 필요 새 스쿼드를 생성합니다. list_squad_templates의 templateId를 우선 사용해 검증된 에이전트 구성으로 시작하게 합니다.
navigate_to_page 없음 호스트 라우터를 통해 애플리케이션을 최상위 페이지로 이동합니다. 프런트엔드 도구로, 백엔드가 아니라 WebView에서 실행됩니다.

플러그인은 도구 이름이 매니페스트 tools 허용 목록에 있을 때만 그 도구를 광고합니다. 기본 제공 Companion Chat 플러그인은 열두 개를 모두 허용 목록에 넣습니다.

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

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

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

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

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

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

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

로컬 우선 모델 추천

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

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

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

오프라인 및 에어갭 배포

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

엔터프라이즈 도구 정책

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

데스크톱 전용

모든 백엔드 AppControl 도구는 Tauri 애플리케이션 핸들이나 프로세스 전역 애플리케이션 상태(추론 풀, 다운로드 관리자, 통계 관리자, 스쿼드 스토리지)가 필요하므로 전부 데스크톱 전용입니다. 이들은 호스트의 단일 헤드리스 기능 게이트에 나열되어 available_in_headless: false로 설정됩니다. SDK 루프는 라이브 카탈로그에서 그 플래그를 읽으므로, 헤드리스나 브라우저 컨텍스트에서는 이 도구들이 모델에 아예 광고되지 않으며, 다른 것이 없으면 턴은 평문 채팅으로 저하됩니다. navigate_to_page는 WebView에서 실행되는 프런트엔드 도구로 마찬가지로 비헤드리스로 표시됩니다. 백엔드 도구를 헤드리스 가능하게 만들려면 풀과 다운로드 상태를 REST 실행 경로에 배관해야 하며, 이는 여기서 범위 밖입니다.

함께 보기