도구 카테고리
CapiBot 에이전트는 25개 이상의 도구에 접근할 수 있으며, 카테고리별로 구성되어 있습니다. 사용 가능한 도구를 이해하면 작업을 효과적으로 위임하는 데 도움이 됩니다.
에이전트가 도구를 사용하는 방법
에이전트는 무엇을 해야 하는지에 따라 자동으로 도구를 선택합니다:
사용자: 상위 5개 경쟁사를 조사해줘
Scout (연구 분석가):
1. 요청 분석
2. web_search 도구 사용 결정
3. "상위 SaaS 분석 경쟁사" 검색
4. 결과 읽기
5. 파일에 결과 작성
6. 보고
어떤 도구를 사용할지 에이전트에게 말할 필요가 없습니다 — 에이전트는 자신의 기능을 알고 작업에 맞는 올바른 도구를 선택합니다.
파일 작업
파일을 읽고, 쓰고, 관리합니다.
사용 가능한 도구
read_file
- 모든 파일의 콘텐츠 읽기
- 큰 파일의 경우 줄 오프셋과 한계 지정
- 모든 텍스트 형식 지원
write_file
- 새 파일 생성
- 기존 파일 덮어쓰기
- 상위 디렉토리를 자동으로 생성
edit_file
- 정밀한 라인 수준 편집
- 파일 내 찾기 및 바꾸기
- 특정 줄 삽입 또는 삭제
list_dir
- 디렉토리 콘텐츠 나열
- 파일과 하위 디렉토리 보기
- 패턴으로 필터
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| 지침 읽기 | read_file |
| 완료된 작업 저장 | write_file |
| 코드 버그 수정 | edit_file |
| 프로젝트 구조 탐색 | list_dir |
| 문서 업데이트 | edit_file |
예시
사용자: CSV 데이터를 분석하는 Python 스크립트를 작성해줘
Nova: 그 스크립트를 만들어 드리겠습니다.
[analyze_csv.py를 write_file로 생성]
완료! 데이터 로딩, 통계 계산 및
차트 생성을 위한 함수가 있는 analyze_csv.py를
만들었습니다.
웹 및 검색
인터넷을 검색하고 웹 콘텐츠를 가져옵니다.
사용 가능한 도구
web_search
- Google 기반 검색
- 제목, URL, 요약 반환
- 기본적으로 상위 10개 결과
web_fetch
- 모든 웹페이지 다운로드 및 구문 분석
- 메인 콘텐츠 추출
- 다양한 형식 처리
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| 경쟁사 연구 | web_search |
| 문서 읽기 | web_fetch |
| 최신 뉴스 확인 | web_search |
| 참조 자료 수집 | web_fetch |
| 예시 찾기 | web_search |
예시
사용자: 2024년 최신 AI 트렌드는 무엇인가요?
Scout: 현재 AI 트렌드를 검색하겠습니다.
[web_search: "AI trends 2024" 사용]
2024년 상위 5개 AI 트렌드:
1. 멀티모달 AI 모델
2. AI 에이전트 및 자동화
3. 엣지 AI 배포
4. AI 규제 및 규정 준수
5. 지속 가능한 AI
더 자세히 알고 싶은 것이 있나요?
브라우저 자동화
프로그래밍 방식으로 웹 브라우저를 제어합니다.
사용 가능한 도구
browser_navigate — URL로 이동
browser_click — 요소 클릭
browser_type — 입력에 텍스트 입력
browser_scroll — 페이지 스크롤
browser_screenshot — 스크린샷 캡처
browser_extract — 페이지 콘텐츠 추출
browser_wait — 요소 대기
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| 웹 애플리케이션 테스트 | navigate, click, type, screenshot |
| 양식 작성 | navigate, type, click |
| 웹사이트에서 데이터 스크랩 | navigate, extract, scroll |
| 웹사이트 스크린샷 찍기 | navigate, screenshot |
| 시각적 모양 확인 | navigate, screenshot |
예시
사용자: 랜딩 페이지 스크린샷을 찍어줘
Nova: 사이트의 스크린샷을 캡처하겠습니다.
[browser_navigate + browser_screenshot 사용]
스크린샷 저장: /workspace/screenshots/landing-page-20241215.png
연락처 양식도 테스트할 수 있습니다.
셸 및 시스템
명령을 실행하고 프로세스를 관리합니다.
사용 가능한 도구
exec
- 셸 명령 실행
- 위험한 패턴은 자동으로 차단
- 구성 가능한 시간 초과 (기본값 30초)
- 호출당 출력은 ~10KB로 제한
spawn
- 백그라운드 프로세스 시작
- 오래 실행되는 작업
- 프로세스 관리
보안 기능
차단된 명령:
# 다음은 자동으로 차단됨:
rm -rf /
mkfs.*
dd if=/dev/zero
fork 폭탄
네트워크 스캔
권한 상승
기본적으로 안전:
- 작업 공간 제한
- 시간 초과 한계
- 출력 한계
- 명령 로깅
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| Python 스크립트 실행 | exec: python script.py |
| 종속성 설치 | exec: npm install |
| Git 작업 | exec: git commit -m "..." |
| 프로젝트 빌드 | exec: npm run build |
| 데이터베이스 마이그레이션 | exec: migrate up |
예시
사용자: 테스트 스위트를 실행해줘
Nova: 지금 테스트를 실행하겠습니다.
[exec: npm test 사용]
✅ 45개 테스트 통과
⚠️ 2개 테스트 건과
❌ 0개 테스트 실패
모든 테스트가 통과했습니다! 빌드가 배포 준비되었습니다.
예약
반복 작업을 생성하고 관리합니다.
사용 가능한 도구
cron
- 미래 작업 예약
- 일회성 또는 반복
- Cron 표현식 구문
- 대화 내에서
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| 일일 보고서 예약 | cron: every day at 9am |
| 마감일 미리 알림 설정 | cron: at 2024-12-20 5pm |
| 반복 상태 확인 | cron: every 5 minutes |
| 주간 요약 | cron: every monday at 10am |
예시
사용자: 내일 블로그 포스트를 검토하라는
미리 알림을 본문해줘
Echo: 미리 알림을 예약하겠습니다.
[cron: 내일 오전 9:00 사용]
✅ 내일 오전 9:00에 미리 알림이 예약되었습니다.
블로그 포스트를 검토하라는 알림을 받게 됩니다.
에이전트 및 작업 관리
다른 에이전트와 작업을 관리합니다.
사용 가능한 도구
sessions_send — 다른 에이전트에게 메시지
sessions_list — 사용 가능한 에이전트 보기
task_create — 새 작업 생성
task_update — 작업 상태 업데이트
task_list — 작업 보기
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| 팀원에게 도움 요청 | sessions_send |
| 작업 위임 | task_create + assign |
| 진행 상황 업데이트 | task_update |
| 팀 워크로드 확인 | task_list |
| 에이전트와 조정 | sessions_send |
예시
사용자: 디자이너에게 랜딩 페이지 검토를
요청해줘
Nova: Pixel에게 검토에 대해 메시지하겠습니다.
[Pixel에게 sessions_send로 메시지]
Pixel이 확인했습니다! 지금 검토 중이며
완료되면 작업을 업데이트할 것입니다.
커뮤니케이션
메시지와 알림을 본문합니다.
사용 가능한 도구
message — 채널에 본문
message_owner — 직접 사용자에게 본문
agent_notify — 특정 에이전트에게 알림
채널
- Telegram
- Slack
- Web Chat (Mission Control)
- 이메일 (구성된 경우)
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| 완료 보고 | message_owner |
| 명확화 질문하기 | message_owner |
| 파일 본문 | message + attachment |
| 긴급 알림 | agent_notify |
예시
Scout: 경쟁사 연구가 완료되었습니다!
[Telegram을 통해 message_owner 사용]
5개 경쟁사를 분석하고
/workspace/competitor-analysis.pdf에
보고서를 저장했습니다.
주요 발견:
• 경쟁사 A는 엔터프라이즈에 집중
• 경쟁사 B는 더 나은 가격
• 중간 시장 부분의 격차
메모리 및 지식
정보를 저장하고 검색합니다.
사용 가능한 도구
write_file — 에이전트 메모리에 저장
read_file — 메모리에서 읽기
company_docs — 기업 지식 베이스 읽기
에이전트가 이를 사용하는 시기
| 작업 | 사용 도구 |
|---|---|
| 선호도 기억하기 | write_file to memory |
| 피드백으로부터 학습 | write_file to memory |
| 기업 가이드라인 읽기 | company_docs |
| 이전 결정 확인 | company_docs |
예시
사용자: 기본 버튼에는 항상 파란색을
사용한다는 것을 기억해줘
Pixel: 알겠습니다! 그 선호도를 저장하겠습니다.
[write_file로 메모리에 저장]
✅ 선호도 저장: "사용자 선호도에 따라
기본 버튼은 파란색(#0066CC)을 사용해야 함"
향후 모든 디자인에 이를 적용하겠습니다.
도구 보안
에이전트가 할 수 없는 것
자동으로 차단됨:
- 파괴적인 시스템 명령
- 작업 공간 외부 접근
- 시간 초과를 초과하는 명령
- 알려진 위험한 셸 패턴
사용자가 제어할 수 있는 것
에이전트별 설정:
- 특정 도구 활성화/비활성화
- 파일 시스템 접근 제한
- 명령 시간 초과 설정
- 출력 크기 제한
전역 설정:
- 작업 공간 제한
- 위험한 패턴 차단
- 명령 로깅
- 감사 추적
모범 사례
사용자의 경우
- 에이전트 신뢰 — 어떤 도구를 사용할지 알고 있음
- 산출물 검토 — 생성한 파일 확인
- 설명 요청 — "어떻게 했나요?"
- 필요할 때 경계 설정 — 필요할 때 제한
에이전트의 경우
- 올바른 도구 사용 — 작업에 맞는 도구
- 오류 처리 — 우아한 실패
- 작업 보고 — 한 일을 사용자에게 알림
- 한계 존중 — 제약 내에서 작업
문제 해결
에이전트가 "그런 일을 할 수 없다"고 함:
- 도구가 비활성화되었을 수 있음
- 능력 외의 일
- 보안 제한
- 에이전트의 허용된 도구 확인
명령 실패:
- 오류 메시지 확인
- 다른 접근 방식이 필요할 수 있음
- 권한 문제일 수 있음
- 더 작은 단계로 나누기 시도
파일을 찾을 수 없음:
- 경로가 올바른지 확인
- 상위 디렉토리를 생성해야 할 수 있음
- 파일이 존재하는지 확인
- 권한 확인