2.7. 도구 사용¶

도구 사용(Tool Calling)은 AI 모델을 수동적인 텍스트 생성기에서 능동적인 문제 해결사로 변모시키는 핵심 기능입니다. 이는 AI에게 파일 시스템, 인터넷, 그리고 컴퓨터의 내부 상태와 상호작용할 수 있는 "손"을 쥐어주는 것과 같습니다.

툴 콜링이란 무엇인가요?¶

일반적으로 LLM은 훈련된 데이터 내의 지식으로만 제한됩니다. 지금 몇 시인지, 내 바탕화면에 어떤 파일이 있는지, 오늘 뉴스 헤드라인이 무엇인지는 알 수 없습니다.

툴 콜링은 이러한 한계를 극복합니다. 모델은 답변을 지어내는 대신 이렇게 요청할 수 있습니다: "현재 애플 주가를 알기 위해 web_search 도구를 사용해야겠어."

Backend.AI GO는 이 요청을 가로채서 도구를 안전하게 실행한 뒤, 그 결과를 모델에게 돌려줍니다. 모델은 이 실제 데이터를 사용하여 사용자의 질문에 정확하게 답변합니다.

왜 중요한가요?¶

• 실시간 지식: 웹 검색을 통해 최신 뉴스, 날씨, 금융 정보에 접근할 수 있습니다.

• 시스템 상호작용: 채팅만으로 로그 파일을 읽거나, 폴더를 정리하거나, 시스템 상태를 점검할 수 있습니다.

• 정확성: 모델의 불안정한 암산 능력 대신 계산기 도구를 사용하여 정확한 수학 연산을 수행합니다.

• 에이전틱(Agentic) 행동: 이것은 AI 에이전트의 기반입니다. AI는 여러 도구 호출을 연쇄적으로 수행(검색 -> 읽기 -> 쓰기)하여 복잡한 워크플로우를 자율적으로 완수할 수 있습니다.

호환 모델¶

모든 모델이 툴 콜링을 지원하는 것은 아닙니다. 도구의 정의를 이해하고 구조화된 도구 요청을 출력하도록 미세 조정(Fine-tuned)된 모델이 필요합니다.

• "Tool" 태그 확인: Backend.AI GO 모델 라이브러리에서 Tool 또는 Function Calling 칩이 붙은 모델을 찾으세요.

• 추천 모델: Gemma 4, Qwen3.6, Llama 4, Mistral Large, 그리고 (클라우드 연동 시) GPT-5.4, Gemini 3 Pro, Claude Sonnet 4.6가 툴 콜링에 적합합니다.

보안 및 권한 시스템¶

도구는 파일을 읽거나 코드를 실행할 수 있으므로 보안이 무엇보다 중요합니다. Backend.AI GO는 위험도 기반 권한 시스템(Risk-Based Permission System)을 탑재하고 있습니다.

위험도 레벨 (Risk Levels)¶

모든 도구에는 위험도가 할당됩니다:

• 🟢 안전 (Safe / No Risk): 단순히 공개된 데이터를 읽거나 계산을 하는 작업입니다.

  • 예시: 계산기, 현재 시간 확인.
  • 동작: 사용자에게 묻지 않고 자동으로 실행됩니다.

• 🟡 주의 (Moderate / Read Access): 개인 파일을 읽거나 외부 웹사이트에 접속하는 작업입니다.

  • 예시: 파일 읽기, 웹 검색, 디렉토리 목록 조회.
  • 동작: 세션당 한 번의 승인이 필요합니다. 한 번 승인하면 대화가 끝날 때까지 자유롭게 사용할 수 있습니다.

• 🔴 위험 (Critical / Write & Execute): 데이터를 수정하거나 코드를 실행하는 작업입니다.

  • 예시: 파일 쓰기/삭제, 셸 명령어 실행.
  • 동작: 매 호출마다 사용자의 명시적인 승인이 필요합니다. 사용자가 "승인" 버튼을 누르지 않으면 AI는 절대 파일을 삭제할 수 없습니다.

내장 도구 (Built-in Tools)¶

Backend.AI GO는 8개 카테고리에 걸쳐 31개의 내장 도구를 제공합니다. 채팅 도구 선택기는 에이전트 런타임과 동일한 레지스트리에서 파생되므로, 두 환경에서 도구 정의와 동작이 동일합니다. 예전 이름인 execute_python, list_files, run_shell은 각각 run_python, list_directory, run_command의 하위 호환 별칭으로 동작하므로, 이전 이름으로 저장된 도구 선택도 계속 사용할 수 있습니다.

1. 파일 시스템 도구¶

2. 웹 도구¶

fetch_url 매개변수¶

3. 유틸리티 및 시스템 도구¶

4. 데이터 조회 도구¶

5. 코드 실행 도구¶

Python 샌드박스 설정¶

앱의 PATH에 Python 실행 파일이 없는 경우(Finder나 Windows 시작 메뉴에서 실행하는 데스크탑 앱, 또는 pyenv/conda 환경에서 흔히 발생), run_python 도구는 "Python 인터프리터를 찾을 수 없음" 오류를 반환합니다. 설정 → 도구 및 확장 → Python 샌드박스 → Python 인터프리터 경로에서 실행 파일 경로를 직접 지정하면 이 문제를 해결할 수 있습니다. 예를 들어 /usr/local/bin/python3이나 C:\Python312\python.exe처럼 입력합니다.

설정된 경로는 저장 시점이 아니라 코드를 실제로 실행할 때 검증합니다(인터프리터가 "Python 3" 버전 문자열을 출력해야 합니다).

제출한 코드 실행에 실패한 경우(문법 오류, 런타임 예외, 비정상 종료 코드, 타임아웃), 도구 실행 결과는 success: false와 분류된 오류 메시지를 포함하며, 오류 내용과 stderr 출력이 채팅 인터페이스의 도구 실행 결과 블록에 눈에 잘 띄게 표시됩니다.

코드 실행 파일 시스템 샌드박스¶

run_python과 run_command는 모델이 생성한 코드를 실제 하위 프로세스에서 실행합니다. 임포트 차단 목록은 코드가 어떤 모듈을 불러올 수 있는지 제한하지만, 그 자체로는 open 내장 함수나 일반 파일 입출력을 제한하지 않습니다. 도구 호출이 호스트의 임의 파일을 읽거나 쓰거나 삭제하지 못하도록, 이 도구들이 수행하는 모든 파일 접근은 하나의 샌드박스 폴더로 제한됩니다.

• run_python은 샌드박스 폴더를 작업 디렉터리로 사용하며, 인터프리터의 파일 기본 함수(open, io.open, os.open, 경로를 받는 os.* 함수)를 감싸서 .. 정리와 심볼릭 링크 추적 후 샌드박스 폴더 밖으로 해석되는 경로는 PermissionError를 발생시킵니다.
• run_command는 샌드박스 폴더를 작업 디렉터리로 사용하며, 폴더 밖으로 해석되는 경로 인자를 거부합니다(예: cat /etc/passwd는 차단됩니다).
• Python의 tempfile로 만든 임시 파일은 샌드박스 폴더로 리디렉션되므로, 정상적인 임시 파일 사용은 계속 동작합니다.

설정 → 도구 및 확장 → Python 샌드박스 → 코드 실행 샌드박스 폴더에서 폴더를 지정합니다. 절대 경로여야 합니다. 비워 두면 기본 폴더(애플리케이션 데이터 디렉터리 아래의 code-exec-sandbox)를 사용하며, 코드 실행 도구가 처음 실행될 때 자동으로 생성됩니다.

이 도구들을 실행하는 모든 경로, 즉 앱 내 채팅, 에이전트 런타임, REST POST /api/v1/tools/execute 엔드포인트는 모두 하나의 공유 구현을 거치므로 동일한 보호가 적용됩니다.

6. 오디오 도구¶

audio_transcribe는 /api/v1/tools에서 available_in_headless: false로 보고되며 /api/v1/tools/execute로 실행할 수 없습니다. 대신 전용 엔드포인트인 /api/v1/audio/transcriptions를 사용하세요.

audio_transcribe 매개변수¶

7. 이미지 생성 도구¶

generate_image는 /api/v1/tools에서 available_in_headless: false로 보고되며 /api/v1/tools/execute로 실행할 수 없습니다. 대신 전용 엔드포인트인 /api/v1/diffusion/generate를 사용하세요.

8. 데스크탑 통합 도구¶

이 도구들은 데스크탑 앱의 프로세스 컨텍스트(시스템 클립보드, 네이티브 알림, 에이전트 메모리 뱅크)가 필요하며, 헤드리스 서버 모드에서는 사용할 수 없습니다. REST /api/v1/tools 엔드포인트는 이 도구들을 여전히 목록에 포함하지만 각 항목을 available_in_headless: false로 표시하며, /api/v1/tools/execute는 설명이 담긴 오류와 함께 실행을 거부합니다. 헤드리스 클라이언트는 이 도구들을 정상 실행 가능한 도구로 받지 않고 이 플래그로 필터링합니다.

9. 대화형 도구 (에이전트 런타임 전용)¶

select_option은 채팅 도구 선택기에서 의도적으로 제외됩니다. 이 도구는 결과를 반환하기 위해 에이전트 루프의 대화형 승인 채널이 필요하므로, 채팅이나 REST 실행 경로에서는 동작할 수 없습니다. 에이전트 런타임에서는 완전히 사용 가능합니다.

에이전트는 컨텍스트에서 추론하기보다 사용자의 결정이 필요한 상황에서 select_option을 호출합니다. 도구가 실행되면 채팅 화면에 레이블이 있는 버튼 위젯이 표시되고, 버튼을 클릭하면 선택한 값과 함께 실행이 재개됩니다. 프롬프트를 취소하면 빈 결과가 반환되고 에이전트는 계속 진행합니다.

select_option 매개변수¶

LLM은 이미지 모델을 직접 선택하지 않으며, 모델은 항상 설정 → 모델 → 기본 이미지 모델에서 결정됩니다. 설정된 모델 id가 cloud:로 시작하는 경우(클라우드 Provider 이미지 모델), 요청은 로컬 sd-server 풀이 아닌 continuum-router를 통해 등록된 Provider로 전달됩니다. 로컬 디퓨전 모델은 메모리에 로드되어 있지 않으면 자동으로 풀에 로드됩니다. 기본 모델이 설정되어 있지 않으면 도구가 명시적인 오류 메시지를 반환하고, 모델이 이를 그대로 전달하여 설정을 요청합니다.

generate_image 매개변수¶

채팅 내 도구 실행 결과¶

도구 실행이 완료되면 결과가 채팅 대화에 인라인으로 표시됩니다. 결과 블록을 펼쳐 파일 목록, 검색 결과, 명령어 출력 등의 전체 데이터를 확인할 수 있습니다. 이러한 투명한 표시 방식을 통해 AI가 어떤 정보를 바탕으로 작업하고 있는지 항상 확인할 수 있습니다.