도구 사용 및 권한¶

도구(Tools)는 에이전트의 "손"과 같습니다. AI가 외부 세계와 상호작용하고 실질적인 행동을 취할 수 있게 해줍니다.

기본 제공 도구¶

Backend.AI GO는 카테고리별로 정리된 기본 도구들을 제공합니다:

파일 시스템 도구¶

• read_file: 로컬 파일의 내용을 확인합니다.
• write_file: 로컬 파일을 생성하거나 수정합니다.
• list_directory: 폴더 안에 어떤 파일들이 있는지 메타데이터(크기, 수정 시간)와 함께 확인합니다.
• create_directory: 지정된 경로에 새 디렉토리를 생성합니다. 재귀적 생성 옵션을 지원합니다.
• delete_file: 파일 시스템에서 파일을 제거합니다.
• move_file: 파일을 이동하거나 이름을 변경합니다.

코드 실행 도구¶

• run_command: 코드 실행 샌드박스 폴더 안에서 호출마다 명령어 하나를 실행합니다 (플랫폼 인식).
• run_python: 관리된 환경에서 Python 코드를 실행합니다.

웹 도구¶

• fetch_url: 특정 웹페이지의 내용을 직접 읽어옵니다.
• web_search: Brave Search를 사용하여 인터넷을 검색합니다.

검색 도구¶

• search_files: 특정 글로브 패턴과 일치하는 파일을 찾습니다.
• search_content: 정규 표현식 패턴으로 파일 내용을 검색합니다. 컨텍스트 라인 표시를 지원합니다.

데이터 도구¶

• json_query: 경로 표현식을 사용하여 JSON 데이터를 쿼리하고 변환합니다.
• csv_reader: 필터링 및 열 선택 기능으로 CSV 파일을 읽고 파싱합니다.

유틸리티 도구¶

• calculator: 복잡한 수학 연산을 정확하게 수행합니다.
• getcurrenttime: 현재 날짜와 시간을 가져옵니다.
• getsysteminfo: CPU, 메모리, 하드웨어 상태를 확인합니다.

크로스 플랫폼 셸 실행¶

run_command 및 run_python 도구는 지원되는 모든 플랫폼(Windows, macOS, Linux)에서 플랫폼별 자동 처리와 함께 작동합니다:

• 프로세스 트리 관리: 명령이 시간 초과되면 메인 프로세스뿐만 아니라 모든 하위 프로세스가 적절하게 종료됩니다.
  • Unix: 프로세스 그룹(killpg) 사용
  • Windows: 완전한 정리를 위한 Job Objects 사용
• 환경 변수: 필수 시스템 변수가 자동으로 하위 프로세스에 전달됩니다:
  • Unix: HOME, PATH, LANG, LC_ALL
  • Windows: USERPROFILE, PATH, SYSTEMROOT, COMSPEC, TEMP, TMP
• 인코딩: 일관된 텍스트 처리를 위해 모든 플랫폼에서 PYTHONIOENCODING=utf-8이 설정됩니다.

파일과 명령이 실행되는 위치¶

에이전트 실행에서 파일 도구와 코드 실행 도구는 같은 폴더에서 시작합니다.

• 작업 디렉토리 없이 시작한 실행에 파일 도구나 코드 실행 도구가 하나라도 켜져 있으면, 코드 실행 샌드박스 폴더 안에 전용 폴더 runs/<실행 ID>가 만들어집니다. 샌드박스 폴더는 설정 > 도구 및 확장 > Python 샌드박스에서 지정하고, 비워 두면 애플리케이션 데이터 디렉토리(헤드리스 서버라면 서버 계정의 데이터 디렉토리) 아래의 code-exec-sandbox를 사용합니다. write_file, read_file, create_directory 같은 파일 도구의 상대 경로는 해당 실행 폴더를 기준으로 해석되고, run_command와 run_python도 이 폴더에서 시작하죠. 그래서 실행 하나가 디렉토리를 지정하지 않고도 main.c를 쓰고, gcc main.c -o main으로 컴파일한 다음 ./main을 실행할 수 있습니다.
• 세션에 허용된 폴더가 있으면 첫 번째 폴더가 작업 디렉토리가 됩니다. 파일 도구는 해당 폴더를 사용하지만 run_command와 run_python은 샌드박스 폴더 밖에서는 실행되지 않으므로, 이때는 샌드박스 폴더의 최상위에서 시작합니다.

실행 폴더는 실행이 끝난 뒤에도 남아 있어서 결과물을 계속 사용할 수 있고, 실행 상세 화면의 작업 디렉토리 항목에서 경로를 확인할 수 있습니다. 오래된 실행 폴더는 자동으로 지워지지 않으니 필요 없어지면 직접 삭제하세요.

run_command는 호출마다 프로그램 하나를 셸 없이 실행합니다. 파이프(|), 리다이렉트(>, <), &&, ;, 명령 치환은 거부되므로 두 단계가 필요한 빌드라면 호출도 두 번 나눠야 합니다. 권한을 바꾸거나 셸·인터프리터를 띄우는 명령(chmod, sh, bash, python 등)은 차단되며, Python 코드는 run_python으로 실행합니다. 샌드박스 폴더 밖의 working_directory는 거부되고, 실행 단계에 working directory '/var/lib/aigo' is outside the sandbox root (...)처럼 이유가 표시됩니다.

코워크 설정 창의 도구 사용 권한 옆 ? 아이콘에서도 이 규칙을 요약해 볼 수 있습니다.

도구 권한 관리¶

사용자의 보안을 위해 Backend.AI GO는 도구 실행을 권한 시스템으로 통제합니다. 도구들은 위험 수준에 따라 다음과 같이 분류됩니다:

낮은 위험 — 항상 허용¶

시간 확인이나 문서 검색과 같은 읽기 전용 작업입니다. 사용자에게 묻지 않고 바로 실행됩니다.

중간 위험 — 한 번 묻기¶

외부 데이터에 접근하거나 임시 위치에 파일을 쓰는 작업입니다. 대화 내에서 처음 사용할 때 사용자에게 승인을 요청합니다.

높은 위험 — 항상 묻기¶

사용자 승인 폴더에 대한 쓰기 작업입니다. 에이전트가 매번 사용자의 명시적 승인을 요청합니다.

치명적 위험 — 항상 묻기¶

파일 삭제와 같은 파괴적인 작업이나 셸 명령어 실행과 같은 시스템 수준의 접근입니다. 에이전트는 이 작업을 수행하기 전에 항상 사용자의 명시적인 승인을 기다립니다.

병렬 도구 실행¶

LLM이 여러 개의 독립적인 도구를 동시에 요청하면, Backend.AI GO는 순차적으로 실행하는 대신 병렬로 실행합니다. 이를 통해 여러 소스에서 정보를 수집해야 하는 복잡한 작업의 성능이 크게 향상됩니다.

작동 방식¶

• 에이전트가 여러 도구 호출이 동시에 요청되었음을 감지합니다.
• 모든 독립적인 도구들이 병렬 처리를 통해 동시에 실행됩니다.
• 결과는 원래 요청 순서대로 수집되어 LLM에 반환됩니다.
• 병렬 실행 중에는 UI에 모든 도구가 "진행 중"으로 표시됩니다.

장점¶

• 더 빠른 결과: 각각 1초씩 걸리는 5개의 도구가 필요한 작업이 ~5초 대신 ~1초 만에 완료됩니다.
• 효율적인 리소스 활용: 최신 멀티코어 프로세서의 성능을 활용합니다.
• 부분 실패 처리: 하나의 도구가 실패하더라도 다른 도구들은 계속 실행되어 성공합니다.

병렬 실행 중 승인 처리¶

병렬 실행 중인 도구가 승인을 필요로 할 때:

• 해당 도구만 승인을 기다리고, 다른 도구들은 계속 실행됩니다.
• 각 도구를 독립적으로 승인하거나 거부할 수 있습니다.
• "이 도구를 항상 허용" 옵션은 병렬 실행 전반에 걸쳐 적용됩니다.

승인 요청 처리하기¶

에이전트가 민감한 도구를 사용해야 할 때:

1. 에이전트의 실행이 일시정지됩니다.
2. 도구 실행 승인 대화상자가 나타납니다.
3. 에이전트가 어떤 도구를 어떤 인자(arguments)와 함께 사용하려는지 정확히 확인할 수 있습니다.
4. 계속하려면 예, 허용을, 차단하려면 아니오, 거부를 클릭하세요.
5. "이 도구를 항상 허용"을 체크하면 현재 대화 동안에는 다시 묻지 않게 설정할 수 있습니다.