CoCo CLI agent tools

CoCo CLI agent tools (에이전트 도구)

CoCo는 파일 작업, 셸 명령, 웹 접근 등을 위한 포괄적인 도구 집합에 접근할 수 있어요. 추가로 설치할 것은 없어요. 이 도구들은 CoCo CLI에 내장되어 사용할 준비가 돼 있어요. CoCo는 내 요청에 따라 적절한 도구를 자동으로 사용해요. 수동으로 호출할 필요 없이 원하는 것을 설명하면 돼요. 예:

출처: CoCo CLI agent tools

본문

Read the first 10 lines of the file src/main.py
Search for TODO comments in all Python files
Execute a bash command to list running processes

사용자 지정 스킬을 만들 때는 스킬이 사용할 수 있는 도구를 지정해야 해요. Skills 참고.

이 페이지의 섹션 제목은 표시 이름이에요. 스킬의 tools: 목록, 훅 매처 필드, 권한 규칙 같은 구성에서 도구 이름을 지정할 때는 소문자 런타임 도구 ID를 사용해요: read, write, edit, glob, grep, bash 등. 이 이름들은 대소문자 구분이고, 어떤 도구와도 일치하지 않는 이름은 오류 없이 무시돼요.

파일 도구

이 도구들은 CoCo가 로컬 파일 시스템의 파일을 읽고, 쓰고, 검색하고, 탐색하게 해줘요. 내 요청이 코드, 구성, 또는 문서 파일을 이해하거나 수정하는 것과 관련될 때 사용해요.

Read

로컬 파일 시스템에서 파일 내용을 읽어요. CoCo는 변경을 가하기 전에 기존 코드를 이해하고, 구성 파일을 검사하고, 내가 참조한 문서의 내용을 볼 필요가 있을 때 이 도구를 사용해요.

지원:

  • 줄 번호가 있는 텍스트 파일
  • 다중 모달 모델을 통해 시각적으로 표시되는 이미지(PNG, JPG 등)
  • 페이지별 텍스트·시각 추출이 있는 PDF
  • 셀과 출력이 있는 Jupyter 노트북
  • 대상 읽기를 위한 @file.py$10-20 구문을 사용한 줄 범위

Write

새 파일을 만들거나 기존 파일을 덮어써요. CoCo는 새 모듈 스캐폴딩, 구성 파일 생성, 스크립트 작성처럼 처음부터 새 파일을 만들 때 이 도구를 사용해요.

지원:

  • 자동 부모 디렉터리 생성
  • 세션 통계를 위한 줄 변경 추적
  • 전체 파일 덮어쓰기(부분 변경은 CoCo가 Edit를 사용해요)

Edit

기존 파일 내에서 대상 검색·대체 편집을 수행해요. CoCo는 파일의 나머지를 보존하면서 업데이트해야 하는 특정 줄만 바꾸기 때문에 기존 코드를 수정할 때 Write보다 이 도구를 선호해요.

지원:

  • 정확한 문자열 매칭·대체
  • 변경 적용 전 diff 미리 보기
  • 파일 전체에 걸친 변수 이름 바꾸기나 반복 패턴 업데이트를 위한 replace_all 모드

Glob

이름이나 경로 패턴으로 파일을 찾아요. CoCo는 파일을 읽거나 편집하기 전에 찾을 때, 특히 부분 이름으로 파일을 참조하거나 프로젝트에서 관련 파일을 발견해야 할 때 이 도구를 사용해요.

예시 패턴:

패턴 설명
**/*.py 모든 Python 파일
src/**/*.ts src/ 디렉터리의 TypeScript 파일
**/test_*.py Python 테스트 파일
!node_modules 제외 패턴

Grep

정규식으로 파일 내용을 검색해요. CoCo는 프로젝트 전반에서 특정 코드 패턴, 함수 정의, 오류 메시지, 구성 값을 찾을 때 이 도구를 사용해요.

지원:

  • 재귀 디렉터리 검색
  • 전체 정규식 패턴 구문
  • 바이너리 파일 감지·건너뛰기
  • 출력 모드: 일치 콘텐츠 줄, 파일 경로만, 또는 일치 수

셸 도구

이 도구들은 CoCo가 명령 실행, 패키지 설치, 테스트 실행, git·npm·docker 같은 개발자 도구와의 상호작용을 위해 터미널 환경에 접근하게 해줘요.

Bash

지속 세션에서 셸 명령을 실행해요. CoCo는 테스트 실행, 의존성 설치, 빌드 실행, 버전 관리 상호작용, 또는 파일 조작을 넘어서는 어떤 작업이라도 시스템 접근이 필요한 작업에 이 도구를 사용해요.

지원:

  • 긴 명령의 스트리밍 출력
  • 서버·감시자를 위한 run_in_background로 백그라운드 실행
  • 구성 가능한 타임아웃(기본 2분, 최대 10분)
  • 제한된 환경을 위한 샌드박스 모드

BashOutput

이전에 백그라운드에서 시작한 명령의 출력을 검색해요. CoCo는 개발 서버나 테스트 스위트 같은 긴 실행 프로세스의 상태를 확인할 때 이 도구를 사용해요.

지원:

  • 관련 출력 줄만 표시하는 정규식 필터링
  • 프로세스 상태 확인(running, completed, 또는 failed)
  • 증분 출력 검색(마지막 확인 이후 새 줄만)

KillShell

실행 중인 백그라운드 셸 프로세스를 종료해요. CoCo는 서버를 멈추고, 멈춘 명령을 취소하고, 더 이상 필요 없는 프로세스를 정리할 때 이 도구를 사용해요.

에이전트 도구

이 도구들은 CoCo가 전문화된 하위 에이전트에 작업을 위임하고, 실행 중 질문하고, 복잡한 다단계 워크플로를 조정하게 해줘요.

RunSubagent

특정 하위 작업을 처리하기 위해 자율 하위 에이전트를 실행해요. CoCo는 작업이 병렬 실행의 이점을 받거나 전문화된 에이전트 유형이 작업에 더 잘 맞을 때 이 도구를 사용해요. 각 하위 에이전트는 독립적으로 실행되고 끝나면 결과를 반환해요.

사용 가능한 하위 에이전트 유형:

  • general-purpose: 전체 도구 접근. 연구와 다단계 작업에 사용.
  • Explore: 빠른 코드베이스 탐색·검색에 최적화.
  • Plan: 아키텍처 결정과 구현 계획에 집중.
  • Custom agents: 프로젝트의 .cortex/agents/ 디렉터리에 정의.

AskUserQuestion

CoCo가 명확화나 결정이 필요할 때 입력을 요청해요. 의도가 모호하거나, 여러 유효한 접근 방식이 있거나, 결정에 내 판단이 필요할 때 추측하는 대신 CoCo가 이 도구를 사용해요.

지원:

  • 설명이 있는 객관식 질문
  • 제안된 기본값이 있는 자유 형식 텍스트 입력
  • 비배타적 선택을 위한 다중 선택 옵션

Review

품질 문제를 확인하기 위해 전문화된 검토 하위 에이전트를 실행해요. CoCo는 구현 작업을 완료한 뒤 정확성을 검증하기 위해 이 도구를 사용할 수 있어요.

웹 도구

이 도구들은 CoCo가 인터넷을 검색하고 웹 페이지 콘텐츠를 가져오게 해서, 현재 문서, API 참조, 다른 온라인 리소스에 접근하게 해줘요.

WebSearch

현재 정보를 위해 웹을 검색해요. 내 질문이 최근 사건, 외부 문서, 또는 훈련 데이터를 넘어선 정보와 관련될 때 CoCo가 이 도구를 사용해요.

지원:

  • 안정성을 위한 여러 검색 엔진 폴백
  • 검색 결과에서 스니펫 추출
  • 중복 검색을 피하기 위한 결과 캐싱
  • 검색당 30초 타임아웃

참고

WebSearch는 Snowsight의 CoCo 설정에서 웹 검색을 켜야 해요. Web search 참고.

WebFetch

특정 URL에서 텍스트 콘텐츠를 검색·추출해요. 내가 링크를 공유하거나, 알려진 URL의 문서를 읽어야 하거나, 검색 결과가 관련 페이지를 가리킬 때 CoCo가 이 도구를 사용해요.

지원:

  • 자동 HTML-to-text 변환
  • 콘텐츠 추출·정리
  • 가져오기당 최대 10,000자
  • 30초 타임아웃

Snowflake 도구

이 도구들은 CoCo를 내 Snowflake 계정에 직접 연결해, SQL 실행, 데이터베이스 객체 검색, 문서 쿼리, Cortex AI 기능 작업을 가능하게 해요.

SnowflakeSqlExecute

Snowflake 계정에 SQL 쿼리와 DDL 문장을 실행해요. CoCo는 데이터 탐색, 스키마 변경, 쿼리 디버깅, 그리고 Snowflake 데이터와 상호작용이 필요한 어떤 작업에 이 도구를 사용해요.

지원:

  • 실행 전 권한 수준 확인
  • 동일 쿼리 재실행을 피하기 위한 결과 캐싱
  • 긴 세션을 위한 자동 토큰 새로고침
  • 많은 행을 반환하는 쿼리를 위한 큰 결과 오프로딩

SnowflakeObjectSearch

Snowflake 데이터베이스 객체 전체에서 시맨틱 검색을 수행해요. CoCo는 정확한 객체 이름을 몰라도 내 의도와 일치하는 테이블, 뷰, 함수를 발견할 때 이 도구를 사용해요.

| 검색 | tables, views, schemas, databases, functions | | 반환 | names, columns, descriptions |

SnowflakeProductDocs

공식 Snowflake 문서를 검색해요. CoCo는 Snowflake 기능에 대한 질문에 답할 때 정확한 구문 참조, 기능 설명, 모범 사례를 찾을 때 이 도구를 사용해요.

지원되는 카테고리:

  • User guide
  • SQL reference
  • Developer guide
  • CoCo topics

ReflectSemanticModel

Cortex Analyst 시맨틱 모델 YAML 파일을 검증해요. CoCo는 배포 전에 시맨틱 모델에 오류가 있는지 확인하고 각 검증 단계에서 문제를 잡을 때 이 도구를 사용해요.

검증 단계:

  • 파일 존재 확인
  • YAML 구문 검증
  • 스키마 구조 검증
  • 서버 측 시맨틱 검증

SnowflakeMultiCortexAnalyst

Cortex Analyst를 통해 자연어 쿼리를 실행해요. CoCo는 SQL을 직접 쓰기보다 시맨틱 모델로 답해야 하는 데이터 질문을 할 때 이 도구를 사용해요.

지원:

  • 자연어에서 SQL로 번역
  • 시맨틱 모델 컨텍스트 인지
  • 신뢰된 답변을 위한 Verified Query Retrieval

데이터 도구

이 도구들은 데이터 비교와 노트북 워크플로를 지원해, CoCo가 구조화 데이터와 대화형 컴퓨팅 환경으로 작업하게 해줘요.

DataDiff

차이를 찾기 위해 데이터베이스나 테이블 간 데이터를 비교해요. 마이그레이션, 변환, 또는 복제가 일관된 결과를 냈는지 확인해야 할 때 CoCo가 이 도구를 사용해요.

지원:

  • 크로스 데이터베이스 비교를 위한 Snowflake 연결 처리
  • 계정 식별자 도출
  • 큰 비교를 위한 300초 타임아웃

NotebookExecute

Jupyter 노트북 셀을 프로그래밍 방식으로 실행해요. CoCo는 노트북 코드를 실행하고, 출력을 검증하고, 데이터 분석 워크플로를 실행할 때 이 도구를 사용해요.

지원:

  • 셀당 구성 가능한 타임아웃
  • 커널 관리(start, restart, interrupt)
  • 파라미터화된 노트북을 위한 파라미터 주입
  • 사용자 지정 Python 환경 지원

NotebookEdit

실행하지 않고 Jupyter 노트북 셀을 편집해요. CoCo는 코드를 업데이트하고, 문서 셀을 추가하고, 노트북을 재구성하라고 요청할 때 노트북 콘텐츠를 수정할 때 이 도구를 사용해요.

지원 모드:

  • replace: 기존 셀의 내용 교체
  • insert: 특정 위치에 새 셀 추가
  • delete: 노트북에서 셀 제거

계획 모드 도구

이 도구들은 CoCo의 계획 워크플로를 관리해요. 구현 전 구조화된 사고의 이점을 받는 복잡한 작업에 사용돼요.

EnterPlanMode

복잡한 다단계 작업을 위해 CoCo를 계획 모드로 전환해요. 계획 모드에서 CoCo는 즉각적인 변경보다 접근 방식 설계에 집중해요. CoCo는 중요한 아키텍처 결정이나 여러 유효한 접근 방식이 있는 작업에 자동으로 계획 모드로 들어가요.

ExitPlanMode

완료된 계획을 내 승인을 위해 제시하고 구현 모드로 돌아가요. 계획을 검토하고 승인하면 CoCo가 실행을 진행해요.

메모리 도구

Memory

CoCo 세션 간 지속 정보를 저장·검색해요. CoCo는 내 선호, 프로젝트 맥락, 결정을 기억해 미래 세션이 처음부터 시작하지 않고 이전 작업 위에 쌓을 수 있게 할 때 이 도구를 사용해요.

지원 명령:

  • view: 저장된 메모리 파일 읽기
  • create: 새 정보 저장
  • str_replace: 기존 메모리 내용 업데이트
  • insert: 특정 위치에 콘텐츠 추가
  • delete: 메모리 파일 제거
  • rename: 메모리 파일 이름 바꾸기·이동

참고

Memory 도구는 CORTEX_ENABLE_MEMORY 환경 변수를 설정해 켜야 해요.

권한 수준

도구는 잠재적 영향에 따라 다른 권한 요구사항이 있어요. CoCo의 3단계 승인 시스템(Auto, Confirm, Deny)이 각 도구가 어떻게 처리되는지 결정해요.

수준 도구 동작
Safe Read, Glob, Grep 자동 승인
Low Write(새 파일) 보통 자동 승인
Medium Edit, Bash(안전) Confirm 모드에서 프롬프트
High Bash(위험), SQL 쓰기 항상 프롬프트
Critical rm -rf, sudo 추가 확인

자세한 내용은 Security를 참고해요.

더 알아보기

  • Security — 권한 수준
  • Skills — 커스텀 스킬의 도구 지정