CLI 및 Snowsight의 CoCo 자동화

CLI 및 Snowsight의 CoCo 자동화 (Preview)

Preview 기능 — 공개

AWS, Azure, Google Cloud의 모든 상용 리전에서 사용할 수 있어요. 정부, FedRAMP, DoD, VPS, China 배포에서는 사용할 수 없어요.

출처: CoCo automations in CLI and Snowsight

본문

개요

CoCo 자동화는 프롬프트를 반복적이고 무인(unattended) CoCo 실행으로 바꿔요. 각 자동화는 터미널이나 브라우저가 닫혀 있어도 Snowflake 관리 샌드박스의 일정에 따라 실행돼요. 각 실행은 에이전트의 메시지, 도구 호출, 결과, 최종 응답을 검사할 수 있는 Cortex 스레드를 만들어요.

CoCo CLI와 Snowsight의 CoCo에서 만든 자동화는 동일한 Snowflake 객체예요. 한 표면에서 자동화를 만들고 다른 표면에서 모니터링하거나 관리할 수 있어요.

중요 이 페이지는 CoCo CLI와 Snowsight의 CoCo가 공유하는 Snowflake 호스팅 자동화를 설명해요. CoCo Desktop도 로컬 자동화를 지원하지만, 이는 귀하의 컴퓨터에서 실행되며 별도의 수명 주기와 권한 모델을 가져요. 자세한 내용은 CoCo Desktop 자동화 문서를 참고하세요.

자동화는 다음과 같은 반복 작업에 유용해요.

일일 성능 요약 생성.
이상 징후에 대한 메트릭 확인.
웨어하우스 사용량과 비용 모니터링.
데이터 신선도 확인.
주기적인 데이터 품질 또는 리포지토리 유지 관리 워크플로 실행.
연결된 MCP 서버에서 예약된 다이제스트 생성.

자동화의 동작 방식

각 자동화는 개인 데이터베이스의 USER$.PUBLIC 아래에 Snowflake AGENT TASK로 저장돼요. CoCo는 내부 태스크 이름에 COCO_ROUTINE_ 접두사를 할당해요.

일정이 트리거되면 Snowflake는 다음을 수행해요.

자동화를 만든 사용자로서 저장된 프롬프트를 실행.
/workspace를 작업 디렉터리로 사용해 Snowflake 관리 샌드박스에서 CoCo를 시작.
CoCo의 기본 제공 샌드박스 도구를 실행에 사용할 수 있게 함.
실행을 위한 Cortex 스레드를 만들고 상위 에이전트 태스크와 연결.
태스크 상태, 타이밍, 쿼리 ID, 오류를 태스크 기록에 기록.

자동화는 웨어하우스를 요구하지 않아요. 에이전트 태스크는 역할이 아니라 만든 사용자가 소유하며, 각 실행은 그 사용자로 실행돼요. 다른 실행 사용자나 역할을 구성하는 옵션은 없어요.

중요 실행은 자동화를 만들 때 CoCo 세션에서 활성이었던 역할을 사용하지 않아요. 그 역할은 에이전트 태스크에 기록되지 않아요. 각 실행은 기본 역할이 귀하의 사용자 기본 역할이고 기본 보조 역할이 활성화된 태스크 세션을 시작해요. 자세한 내용은 사용자 권한으로 태스크 실행을 참고하세요.

자동화에 의존하기 전에 기본 역할이 프롬프트가 필요로 하는 모든 객체에 도달할 수 있는지 확인하세요. 다른 역할에서 대화형으로 작동하는 프롬프트는 일정으로 실행될 때 실패하거나 불완전한 결과를 반환할 수 있어요.

CoCo CLI에서 자동화를 만들 때 CoCo는 기본적으로 사용자의 USER$.PUBLIC.DEFAULT$ 워크스페이스 스테이지를 /workspace에 마운트하므로 거기에 기록된 파일은 실행 간에 유지돼요. 다른 스테이지를 마운트하려면 --workspace <stage_fqn>을, 마운트를 건너뛰려면 --no-workspace를 전달해요. 마운트를 건너뛰면 /workspace는 임시이며 내용은 각 실행 후 폐기돼요.

요구 사항 및 접근 제어

자동화를 사용하기 전에 다음 요구 사항이 충족되어야 해요.

사용하는 CoCo 표면에 대한 표준 접근 요구 사항을 충족해야 해요. Snowsight 요구 사항은 접근 제어 요구 사항을 참고하세요.
사용자의 역할을 통해 EXECUTE AGENT TASK 계정 권한이 있어야 해요. 이 권한은 기본적으로 PUBLIC 역할에 부여되므로 관리자가 grant를 변경하지 않는 한 계정의 모든 사용자가 이를 가져요.
MCP 서버, 워크스페이스 스테이지 또는 Snowflake 시크릿을 연결하려면 역할에 해당 객체를 사용하는 데 필요한 권한도 있어야 해요.

EXECUTE AGENT TASK가 기본적으로 PUBLIC에 부여되므로, 자동화를 선택된 역할로 제한하려는 관리자는 먼저 PUBLIC에서 권한을 회수한 뒤 해당 역할에 부여해야 해요.

REVOKE EXECUTE AGENT TASK ON ACCOUNT FROM ROLE PUBLIC;
GRANT EXECUTE AGENT TASK ON ACCOUNT TO ROLE automation_user;

EXECUTE AGENT TASK를 회수하면 영향받는 사용자가 자동화를 만들거나 실행하지 못해요. 기존 실행 기록은 만료될 때까지 계속 사용할 수 있어요. 관리자가 나중에 접근을 복원하면 기존 자동화를 재개할 수 있어요.

기본 PUBLIC grant에 대한 배경은 Snowflake CoWork Automations: EXECUTE AGENT TASK 권한이 기본적으로 PUBLIC에 부여됨을 참고하세요.

비용

공개 프리뷰 기간 동안 사용자가 만든 자동화는 각 실행에 대한 CoCo 토큰 소비 외에 표준 Snowflake 태스크 청구가 발생해요. 시스템이 시작한 분석에는 요금이 부과되지 않아요.

태스크 비용에 대한 자세한 내용은 태스크 비용 모니터링을 참고하세요. CoCo 가격 세부 정보는 Snowflake Service Consumption Table을 참고하세요.

Snowsight에서 자동화 만들기

자동화 인터페이스에서 또는 CoCo 채팅에서 대화식으로 자동화를 만들 수 있어요.

인터페이스에서 자동화를 만들려면:

Snowsight에서 CoCo를 연 다음 Automations를 열어요. 진입점은 프리뷰 빌드에 따라 다를 수 있어요.
Create automation을 선택해요. 사용 가능한 템플릿에서 시작하거나 처음부터 자동화를 만들 수 있어요.
제목과, 매 실행마다 CoCo가 무엇을 해야 하는지 설명하는 자족형 지침을 입력해요.
모델을 선택해요.
빈도, 요일, 시간, 시간대를 구성해요.
사람이 읽을 수 있는 일정을 검토한 뒤 자동화를 만들어요.

또한 CoCo에게 자연어로 자동화를 만들도록 요청할 수 있어요. 예를 들어:

매주 평일 오전 9시(태평양 시간)에 어제의 파이프라인 실패를 확인하고 짧은 요약을 만들어줘.

CoCo는 자동화를 만들기 전에 누락된 세부 정보를 수집해요.

CoCo CLI로 자동화 만들기

cortex automation create 명령을 사용해 자동화를 만들어요. 다음 예시는 시간당 자동화를 만들어요.

cortex automation create \
  --name pipeline_health \
  --prompt "Check pipeline failures from the last hour and summarize the likely causes." \
  --schedule "every 60 minutes"

시간 기반 일정의 경우 IANA 시간대를 지정해요.

cortex automation create \
  --name daily_performance_recap \
  --prompt-file daily-performance-recap.md \
  --schedule "daily at 9am" \
  --timezone America/Los_Angeles

CLI는 다음 일정 형식을 지원해요.

간격, 예: every 60 minutes, every 4 hours 또는 daily.
일일 시간, 예: daily at 9am.
주간 시간, 예: every Tuesday at 1:15pm.
여러 주간 시간, 예: every Tuesday at 9am and every Friday at 2pm.

자연어 일정에 여러 주간 시간이 포함되면 CLI는 하나 이상의 기본 에이전트 태스크를 만들 수 있어요. 일치하는 모든 태스크를 대상으로 하는 명령은 --all 옵션을 요구해요.

고급 워크플로에는 다음 옵션을 사용할 수 있어요.

--workspace <stage_fqn>: 특정 스테이지를 /workspace에 마운트.
--no-workspace: 각 실행에 대해 임시 워크스페이스 사용.
--mcp <database.schema.name>: Snowflake 관리 또는 고객 제공 MCP 서버 연결. 옵션을 반복해 둘 이상의 서버를 연결할 수 있어요.
--model <model_id>: 기본 auto 모델 선택을 재정의.
--github <secret_fqn>: 인증된 GitHub 이그레스를 위해 GitHub 개인용 액세스 토큰을 포함하는 Snowflake 시크릿 사용.
--pre-run-hook <command> 및 --post-run-hook <command>: 각 실행 전후에 샌드박스 내부에서 고정 설정 또는 정리 명령 실행. 실행 설정 및 정리 훅을 참고하세요.
--dry-run: 자동화를 만들지 않고 생성된 태스크 정보와 SQL을 출력.

전체 명령 참조는 cortex automation --help를 실행해요.

실행 설정 및 정리 훅

훅은 샌드박스가 각 자동화 실행 전후(에이전트 루프 전과 후)에 실행하는 bash 명령이에요. 훅은 지침이 아닌 순수한 bash이므로 매 실행마다 같은 일을 하고 에이전트 턴을 소비하지 않아요. 고정 설정과 해체에는 훅을 사용하고, 실행마다 달라지는 작업은 프롬프트에 남겨두세요.

훅은 자동화의 최상위 실행에만 실행돼요. 실행이 시작한 서브에이전트에는 다시 실행되지 않아요.

훅을 구성하려면 다음 옵션을 사용해요.

옵션	설명
`--pre-run-hook <command>`	에이전트 루프가 시작되기 전 샌드박스 설정 중 실행할 bash. 0이 아닌 종료 상태는 나머지 실행 동안 샌드박스를 사용할 수 없게 해요.
`--post-run-hook <command>`	에이전트가 최종 응답을 생성한 후 실행할 bash. 0이 아닌 종료 상태는 기록되지만 실행을 실패시키지 않아요.
`--pre-run-timeout <seconds>`	사전 실행 훅의 시간 제한. 기본값 60초, 최대 300초.
`--post-run-timeout <seconds>`	사후 실행 훅의 시간 제한. 기본값 30초, 최대 300초.
`--hooks-config-path <path>`	명령줄 대신 마운트된 워크스페이스의 JSON 파일에서 훅을 읽어요. 경로는 `/workspace`에 상대적이어야 해요. 인라인 훅 옵션과 결합할 수 없어요.

경고 실패한 훅은 실행을 실패시키지 않아요. 태스크 기록은 다음 두 경우 모두 실행을 성공으로 보고하므로, 깨진 훅은 실행의 스레드를 열 때까지 눈치채지 못할 수 있어요.

사전 실행 훅이 0이 아닌 상태로 종료되면 샌드박스는 사용할 수 없게 유지돼요. 에이전트는 여전히 시작되고 최종 응답을 여전히 생성하지만 도구 호출이 실패하므로, 작업을 수행하는 대신 할 수 없다고 보고해요.

사후 실행 훅이 0이 아닌 상태로 종료되면 에이전트의 결과는 영향받지 않아요. 사후 실행 훅이 git push 같은 실행의 유일한 출력을 게시한다면 실행이 여전히 성공을 보고하는 동안 출력은 손실돼요.

훅이 기대한 대로 되었는지 확인하려면 스레드 기록을 검사하세요. 태스크 상태에만 의존하지 마세요.

훅은 권한이 없는 사용자로 실행되며 작업 디렉터리는 /workspace가 아니므로 절대 경로를 사용하거나 명시적으로 디렉터리를 변경하세요.

마운트된 워크스페이스 스테이지는 이미 존재하는 파일에 추가하는 것을 지원하지 않아요. 파일을 만들고 덮어쓸 수는 있지만 echo done >> /workspace/log.txt 같은 셸 추가는 대상 파일이 존재할 때 Operation not supported로 실패하며, 결과적인 0이 아닌 종료 상태가 훅의 나머지를 중지시켜요. 전체 파일을 덮어쓰거나, 각 실행마다 새 파일을 쓰거나, 마운트된 워크스페이스 밖의 경로를 사용하세요.

중요 같은 제한이 Git에도 적용돼요. Git은 참조 로그에 추가하므로 마운트된 워크스페이스 스테이지에 사는 리포지토리는 첫 번째 커밋은 허용하지만 이후 모든 커밋은 unable to append to '.git/logs/HEAD': Operation not supported로 실패해요. 훅이 커밋해야 한다면 /tmp 같은 마운트된 워크스페이스 밖의 경로로 클론해요. 클론은 각 실행에 재생성돼요.

다음 예시는 실행 전에 리포지토리를 클론하고 그 후 에이전트의 변경 사항을 게시해요. --github 옵션은 훅과 에이전트 모두에 GitHub에 대한 인증 접근을 제공해요.

cortex automation create \
  --name repo_janitor \
  --prompt-file repo-janitor.md \
  --schedule "daily at 2am" \
  --github 'USER$YOU.PUBLIC.GITHUB_PAT' \
  --pre-run-hook "git clone --depth 1 https://github.com/my-org/my-repo /tmp/repo" \
  --post-run-hook "cd /tmp/repo && git add -A && git commit -m 'automated update' && git push"

다음 예시는 사전 실행 훅을 가드로 사용해요. 예상 입력 파일이 없으면 훅이 0이 아닌 상태로 종료되어 에이전트가 오래된 데이터에 대해 작업할 수 없게 해요.

cortex automation create \
  --name metrics_digest \
  --prompt-file metrics-digest.md \
  --schedule "every 60 minutes" \
  --pre-run-hook "test -s /workspace/input/latest.csv" \
  --pre-run-timeout 15

자동화를 다시 만들지 않고 훅을 변경하려면 마운트된 워크스페이스의 JSON 파일에 유지하고 워크스페이스 상대 경로로 참조해요. 샌드박스는 각 실행 시작 시 파일을 읽으므로 파일을 편집하면 이후 실행이 하는 일이 바뀌어요.

cortex automation create \
  --name nightly_build \
  --prompt-file nightly-build.md \
  --schedule "daily at 1am" \
  --hooks-config-path hooks/nightly.json

훅은 자동화의 나머지와 같은 접근으로 실행되고 대화형 승인 프롬프트 없이 실행되므로, 다른 무인 스크립트를 취급하듯 훅을 취급하세요.

자동화 모니터링 및 관리

Snowsight의 Automations 인터페이스는 귀하의 자동화와 현재 상태를 나열해요. 자동화를 선택해 일정, 다음 실행, 마지막 실행, 모델, 지침, 실행 기록을 볼 수 있어요.

Snowsight에서 자동화를 즉시 실행하거나, 일정을 일시중지·재개하거나, 구성을 편집하거나, 삭제할 수 있어요.

같은 자동화를 관리하려면 다음 CLI 명령을 사용해요.

작업	CLI 명령
자동화 나열	`cortex automation list`
구성 및 상태 보기	`cortex automation describe <name>`
최근 실행 및 스레드 ID 보기	`cortex automation doctor <name>`
즉시 실행	`cortex automation execute <name>`
즉시 실행하고 완료 대기	`cortex automation execute <name> --wait`
예약 실행 일시중지	`cortex automation suspend <name>`
예약 실행 재개	`cortex automation resume <name>`
자동화 삭제	`cortex automation drop <name>`

CoCo CLI 대화형 인터페이스에서 인수 없이 /automation(또는 /automations)을 입력해 자동화 목록을 열어요. 그 목록에서 화살표 키 또는 j와 k로 자동화를 선택하고, Enter로 실행 기록을 열고, r로 선택한 자동화를 즉시 실행하고, Esc로 종료해요. 같은 키가 실행 기록 뷰에서도 작동하며, Enter는 실행의 기록을 열어요.

자동화를 만들고, 검사하고, 일시중지하고, 재개하고, 삭제하려면 /automation 뒤에 자연어 요청을 입력해요.

실행이 생성한 전체 대화를 검사하려면 먼저 스레드 ID를 검색해요.

cortex automation doctor pipeline_health --limit 10

그런 다음 기록을 엽니다.

cortex conversations transcript <thread_id>

태스크 기록은 실행 상태와 오류 정보의 권위 있는 소스예요. 성공한 태스크도 전달되지 않은 메시지 같은 불완전한 비즈니스 결과를 만들 수 있어요. 에이전트의 도구 호출과 최종 응답을 확인하려면 스레드 기록을 검사하세요.

최근 자동화 스레드를 직접 나열할 수도 있어요.

cortex conversations list --origin sql_function

무인 실행을 위한 프롬프트 작성

각 실행은 저장된 지침에서 시작해요. 후속 질문에 답하거나, 작업을 승인하거나, 모호한 이름을 명확히 할 사람이 없어요.

다음을 하는 프롬프트를 작성하세요.

실행이 무인이며 자율적으로 완료해야 함을 명시.
CoCo에게 후속 질문을 하지 말라고 지시.
실행이 사용해야 하는 정확한 데이터 객체, 리포지토리, 문서 ID, 채널 ID 또는 사용자 ID를 포함.
예상 출력과 목적지를 정의.
필수 데이터가 없거나 도구가 실패했을 때 실행이 해야 할 일을 정의.
기록에서 쉽게 식별할 수 있는 간결한 성공 또는 실패 상태로 끝맺음.

반복 일정에 의존하기 전에 수동으로 실행을 트리거하고 기록과 부작용을 검사하세요.

보안 고려 사항

자동화는 호출자 권한(caller's-rights) 모델을 사용해요. 각 실행은 자동화를 만든 사용자로 실행되며 Snowflake 역할 기반 접근 제어, 행 접근 정책, 마스킹 정책을 존중해요. 사용자가 객체에 대한 접근을 잃으면 이후 실행은 그 객체에 더 이상 접근할 수 없어요.

실행은 자동화를 만들 때 활성이었던 역할이 아니라 만든 사용자의 기본 역할과 기본 보조 역할로 범위가 지정돼요. 사용자의 기본 보조 역할이 사용자에게 부여된 모든 역할을 포함한다면, 실행은 사용자가 역할 중 하나를 통해 도달할 수 있는 모든 객체에 도달할 수 있어요. 자동화를 만드는 사용자를 결정할 때 이를 고려하세요.

경고 자동화 실행은 무인이므로 대화형 도구 권한 프롬프트가 비활성화돼요. 실행에 사용할 수 있는 도구는 승인을 기다리지 않고 실행될 수 있어요. 프롬프트, 역할 권한, 연결된 도구, 대상 객체가 의도적으로 그 동작을 위해 구성되지 않는 한 파괴적이거나 되돌릴 수 없는 작업을 예약하지 마세요.

최소 권한을 적용하려면 자동화를 만들기 전에 역할을 전환하는 대신 자동화를 소유한 사용자의 기본 역할과 기본 보조 역할을 좁혀요. 워크플로에 필요한 MCP 서버, 스테이지, 시크릿만 연결해요. 의도하지 않은 객체에 작용할 수 있는 광범위하거나 모호한 프롬프트를 피하세요.

자동화 샌드박스는 로컬 파일 시스템이나 로컬로 구성된 MCP 서버에 접근할 수 없어요. Snowflake에서 마운트된 파일과 자동화에 명시적으로 연결된 MCP 서버만 사용할 수 있어요.

한도 및 프리뷰 동작

공개 프리뷰 기간 동안 다음 한도와 동작이 적용돼요.

지원되는 최소 스케줄링 빈도는 시간당 한 번이에요. CLI 일정 파서는 더 짧은 간격을 허용할 수 있지만, 1시간 미만의 간격은 이 프리뷰에서 지원되지 않아요.
자동화 스레드와 실행 기록은 두 달간 보존돼요.
자동화는 고정 시간 기반 일정을 사용해요. 이벤트 기반 트리거는 지원되지 않아요.
Snowflake가 관리 샌드박스를 프로비저닝하는 동안 실행이 시작되는 데 추가 시간이 걸릴 수 있어요.
진행 중인 실행에 연결하거나 대화형으로 실행을 재개할 수 없어요. 실행은 태스크 기록과 스레드 기록을 통해 읽기 전용으로 검사돼요.
사용 가능한 템플릿, 일정 컨트롤, 인터페이스 레이블은 프리뷰 기간에 변경될 수 있어요.
실행 기록은 실행이 시작되는 동안 또는 스레드 메타데이터가 기록되는 동안 스레드 링크 없이 태스크 정보를 일시적으로 표시할 수 있어요.

문제 해결

자동화 명령이나 인터페이스를 사용할 수 없음

계정이 지원되는 배포에 있고 사용하는 CoCo 표면에 대한 접근 요구 사항을 충족하는지 확인하세요. 기능이 여전히 사용할 수 없다면 Snowflake 계정 팀에 문의하세요.

자동화 생성 또는 실행이 접근 오류를 반환함

사용자의 역할을 통해 EXECUTE AGENT TASK 계정 권한이 있는지 확인하세요. 생성은 성공하지만 실행이 누락된 접근을 보고하면 자동화를 만들 때 활성이었던 역할이 아니라 사용자의 기본 역할과 기본 보조 역할의 권한을 확인하세요. 실행은 참조되는 모든 스테이지, MCP 서버, 시크릿, 데이터 객체에 접근해야 해요.

실행이 실패함

cortex automation doctor <name>을 사용해 태스크 상태, 오류 코드, 오류 메시지, 쿼리 ID를 검토해요. 실행이 스레드를 만들었다면 cortex conversations transcript <thread_id>로 검사해요.

실행이 성공했지만 예상 작업이 일어나지 않음

실행의 스레드를 열고 도구 호출과 결과를 검사해요. 태스크 성공은 에이전트 실행이 완료되었음을 의미하며, 모든 외부 부작용이 의도한 비즈니스 결과와 일치했음을 보장하지는 않아요.

실행이 로컬 파일이나 MCP 서버를 찾을 수 없음

Snowflake 호스팅 자동화는 로컬 컴퓨터의 리소스를 사용할 수 없어요. 영구 파일은 마운트된 Snowflake 스테이지에 두고, 자동화를 만들 때 필수 MCP 서버를 연결하세요.

CLI 및 Snowsight의 CoCo 자동화