Main Quest - Snowflake/Cortex Agent
Cortex Agent DDL, 주요 아키텍처 & 개념
포스 삼촌
2026. 7. 25. 00:08
주요 섹션:
- Agent 아키텍처 & 개념
- CREATE AGENT DDL 구문
- Specification YAML 구조 (models, instructions, tools, tool_resources)
- Tool 종류 (Cortex Search, Cortex Analyst, SQL Exec, Python, API 등)
- DATA_AGENT_RUN 호출 방법
- ALTER AGENT / 버전 관리
- 예산 제어 (budget)
- 제한사항 & 시험 포인트
- UI vs DDL 매핑 (마지막 섹션 — UI로 만들어본 경험이랑 연결됨!)
-- UI로 한땀한땀 만들어왔으니, 이제 DDL로 정확히 재현할 수 있어야 한다.
-- 시험: CREATE AGENT 구문, YAML 스펙 구조, tool 타입별 설정, 권한 체계
-- =============================================================
-- 1. CREATE AGENT (기본 구문) ★시험 암기 필수★
-- =============================================================
-- ★★★ 공식 구문 ★★★
-- CREATE [ OR REPLACE ] AGENT [ IF NOT EXISTS ] <name>
-- [ COMMENT = '<comment>' ]
-- [ PROFILE = '<profile_object>' ]
-- FROM SPECIFICATION
-- $$
-- <specification_yaml>
-- $$;
-- Specification 최대 크기: 100,000 bytes
-- PROFILE 형식: '{"display_name": "...", "avatar": "...", "color": "..."}'섹션 1: CREATE AGENT 기본 구문
DDL 뼈대 — 이것만 외우세요:
sql
CREATE [ OR REPLACE ] AGENT <name>
[ COMMENT = '...' ]
[ PROFILE = '{"display_name": "...", "color": "..."}' ]
FROM SPECIFICATION
$$
<YAML>
$$;시험 핵심:
- FROM SPECIFICATION — 반드시 이 키워드 뒤에 YAML이 옴 ($$..$$로 감싸기)
- YAML 최대 100,000 bytes — 초과하면 에러
- OR REPLACE와 IF NOT EXISTS 동시 사용 불가 — 시험 함정!
- PROFILE — UI의 Display Name/Color/Avatar에 해당, JSON 문자열
UI 경험과 연결:
- UI에서 이름 짓고, 아이콘 색 고르고, 설명 쓴 것 = COMMENT + PROFILE
- UI에서 모델 선택하고, 도구 추가하고, 지시문 쓴 것 = YAML $$...$$ 안에 전부 들어감
-- =============================================================
-- 2. Specification YAML 전체 구조 ★핵심★
-- =============================================================
-- ┌─────────────────────────────────────────────────────────┐
-- │ YAML 최상위 키 (순서 무관, 모두 optional) │
-- ├─────────────────────────────────────────────────────────┤
-- │ models: → 오케스트레이션 모델 지정 │
-- │ orchestration: → budget (시간/토큰 제한) │
-- │ instructions: → response, orchestration, sample_questions │
-- │ tools: → tool_spec 배열 (type, name, desc) │
-- │ tool_resources: → tool별 리소스 설정 (name 매칭) │
-- └─────────────────────────────────────────────────────────┘
Specification YAML 구조
YAML 5대 최상위 키 — 전부 optional, 순서 무관:
| 키 | 역할 | UI 대응 |
| models | 오케스트레이션 모델 | Model 드롭다운 |
| orchestration | budget (시간/토큰 제한) | Budget 슬라이더 |
| instructions | 응답/오케스트레이션 지시문 | Instructions 텍스트박스 |
| tools | 도구 목록 (type, name, desc) | "Add Tool" 버튼 |
| tool_resources | 도구별 세부 설정 | Tool 설정 패널 |
instructions 3가지 하위 키:
- response — 응답 스타일 (한국어로, 숫자에 쉼표 등)
- orchestration — 어떤 상황에 어떤 도구를 쓸지 가이드
- sample_questions — UI에 보이는 예시 질문
시험 함정:
text
Q: instructions.orchestration과 instructions.response의 차이는?
A: orchestration = Agent가 도구 선택 시 참조하는 내부 로직
response = 최종 답변 포맷/톤 지시tools 배열 구조:
yaml
tools:
- tool_spec:
type: "cortex_analyst_text_to_sql" # 타입 (7종)
name: "SalesAnalyst" # 고유 이름
description: "매출 분석" # Agent가 도구 선택 시 참조name이 tool_resources와 매칭되는 키입니다. 이름이 안 맞으면 연결 안 됨
-- =============================================================
-- 3. 실전 예시: 모든 Tool 타입을 포함한 Agent
-- =============================================================
-- =============================================================
-- 3. 실전 예시: 모든 Tool 타입을 포함한 Agent
-- =============================================================
CREATE OR REPLACE AGENT my_db.my_schema.full_agent
COMMENT = 'All tool types demonstration agent'
PROFILE = '{"display_name": "업무 도우미", "avatar": "assistant.png", "color": "blue"}'
FROM SPECIFICATION
$$
models:
orchestration: claude-sonnet-4-6
orchestration:
budget:
seconds: 60
tokens: 50000
instructions:
response: |
Always respond in Korean.
Format numbers with commas.
Include source citations when using search results.
orchestration: |
For revenue/sales questions, use SalesAnalyst.
For policy/HR questions, use PolicySearch.
For calculations or data processing, use code execution.
When showing data trends, generate a chart.
sample_questions:
- question: "지난 분기 매출 Top 5 고객은?"
- question: "재택근무 정책이 뭐야?"
- question: "월별 매출 트렌드를 차트로 보여줘"
tools:
# --- Built-in Tool 1: Cortex Analyst ---
- tool_spec:
type: "cortex_analyst_text_to_sql"
name: "SalesAnalyst"
description: "매출, 주문, 고객 데이터를 SQL로 분석합니다"
# --- Built-in Tool 2: Cortex Search ---
- tool_spec:
type: "cortex_search"
name: "PolicySearch"
description: "회사 정책, 규정, 매뉴얼을 검색합니다"
# --- Built-in Tool 3: Data to Chart ---
- tool_spec:
type: "data_to_chart"
name: "ChartGenerator"
description: "데이터를 시각화 차트로 변환합니다"
# --- Built-in Tool 4: Code Execution (Python) ---
- tool_spec:
type: "code_execution"
name: "PythonExecutor"
description: "Python 코드를 실행하여 데이터 처리 및 계산을 수행합니다"
# --- Built-in Tool 5: Web Search ---
- tool_spec:
type: "web_search"
name: "WebSearch"
description: "인터넷에서 최신 정보를 검색합니다"
# --- Custom Tool: Stored Procedure ---
- tool_spec:
type: "function"
name: "SendAlert"
description: "중요 알림을 슬랙 채널로 전송합니다"
input_schema:
type: "object"
properties:
channel:
type: "string"
description: "슬랙 채널명 (예: #alerts)"
message:
type: "string"
description: "전송할 메시지 내용"
required:
- channel
- message
# --- Custom Tool: UDF ---
- tool_spec:
type: "function"
name: "CalcDiscount"
description: "고객 등급별 할인율을 계산합니다"
input_schema:
type: "object"
properties:
customer_tier:
type: "string"
description: "고객 등급 (Gold, Silver, Bronze)"
order_amount:
type: "number"
description: "주문 금액"
required:
- customer_tier
- order_amount
# --- MCP Connector ---
- tool_spec:
type: "mcp"
name: "JiraConnector"
description: "Jira에서 이슈를 조회하고 생성합니다"
tool_resources:
SalesAnalyst:
semantic_view: "MY_DB.ANALYTICS.SALES_SEMANTIC_VIEW"
PolicySearch:
name: "MY_DB.DOCS.POLICY_SEARCH_SVC"
max_results: "5"
title_column: "doc_title"
id_column: "doc_id"
columns_and_descriptions:
- name: "doc_title"
description: "Document title"
- name: "content"
description: "Document content"
- name: "category"
description: "Document category: policy, guide, manual"
SendAlert:
procedure: "MY_DB.MY_SCHEMA.SEND_SLACK_ALERT"
warehouse: "WH_ENGINEER"
CalcDiscount:
function: "MY_DB.MY_SCHEMA.CALCULATE_DISCOUNT"
JiraConnector:
mcp_connection: "MY_DB.MY_SCHEMA.JIRA_MCP_CONNECTION"
$$;
Tool 7종 총정리 — 시험 암기표
| # | type | 용도 | tool_resources 필수 키 |
| 1 | cortex_analyst_text_to_sql | 자연어→SQL | semantic_view (FQN) |
| 2 | cortex_search | 문서/지식 검색 | name(서비스FQN), max_results |
| 3 | data_to_chart | 데이터 → Vega-Lite 시각화 | 없음 (설정 불필요) |
| 4 | code_execution | Python 샌드박스 실행 (Preview) | 없음 |
| 5 | web_search | 인터넷 검색 (계정 레벨 활성화 필요) | 없음 |
| 6 | function | SP/UDF 호출 | procedure + warehouse |
| 7 | mcp | 외부 시스템 연결 (Remote MCP Server 연결) | MCP 서버 설정 |
시험 핵심 구분:
Built-in (1~5): 설정 간단, Agent가 알아서 호출
Custom function (6): input_schema로 파라미터 정의 필수! (JSON Schema 형태)
MCP (7): 외부 API 연결 (Jira, Slack 등)
tool_resources 매칭 규칙:
yaml
tools:
- tool_spec:
name: "SalesAnalyst" # ← 이 이름이
tool_resources:
SalesAnalyst: # ← 여기랑 정확히 일치해야 함
semantic_view: "..."시험 함정:
text
Q: data_to_chart, code_execution, web_search의 tool_resources는?
A: 없다! 이 3개는 tool_resources 설정 불필요text
Q: function 타입과 나머지의 차이점은?
A: input_schema가 필요 (Agent가 파라미터를 어떻게 넘길지 알아야 하니까)
차트와 파이썬 코드 실행은 기본으로 가능한 거구나. 설정이 불필요해도 툴에 지정은 해줘야 차트를 그려주겠지?
설정 불필요 ≠ 선언 불필요
yaml
# tools에 선언 안 하면 → Agent가 그 기능을 아예 모름 (사용 불가)
# tools에 선언하되, tool_resources는 안 써도 됨
tools:
- tool_spec:
type: "data_to_chart" # ← 이거 선언해야 차트 그려줌
name: "ChartGenerator"
description: "데이터를 차트로 시각화"
- tool_spec:
type: "code_execution" # ← 이거 선언해야 Python 실행함
name: "PythonExecutor"
description: "Python 코드 실행"
# tool_resources에는 위 두 개를 안 넣어도 OK정리:
- tools에 선언 = "이 도구 쓸 수 있어" (Agent에게 권한 부여)
- tool_resources에 설정 = "이 도구의 세부 연결 정보" (필요한 것만)
시험 관점:
text
Q: Agent가 차트를 생성하려면 무엇이 필요한가?
A: tools에 data_to_chart를 선언해야 함 (tool_resources는 불필요)
Q: tools에 아무것도 선언 안 하면?
A: 대화만 가능한 순수 LLM 챗봇 (도구 사용 불가)MCP는 최근 추가라 시험 비중이 낮을 수 있지만, 존재는 알아두시면 됩니다
-- =============================================================
-- 5. cortex_search tool_resources 상세 옵션
-- =============================================================
-- tool_resources:
-- SearchTool:
-- name: "DB.SCHEMA.SEARCH_SVC" ← FQN (필수)
-- max_results: "10" ← 최대 결과 수 (문자열!)
-- title_column: "doc_title" ← 제목으로 사용할 컬럼
-- id_column: "doc_id" ← 고유 식별자 컬럼
-- filter: ← 정적 필터 (항상 적용)
-- "@eq":
-- region: "APAC"
-- columns_and_descriptions: ← Agent가 검색 전략에 활용
-- - name: "content"
-- description: "Full document text"
-- - name: "category"
-- description: "Document category: policy, guide, faq"
-- ★ Agent는 동적으로 filter, columns, limit을 조정할 수 있음
-- ★ columns_and_descriptions는 Agent가 "어떤 컬럼을 반환받을지" 결정하는 데 사용
-- ★ Analytical Search: 복잡한 분석 질문 시 자동 활성화 (별도 설정 불필요), 섹션 5가 시험 포인트 있습니다.
cortex_search tool_resources 핵심:
yaml
tool_resources:
SearchTool:
name: "DB.SCHEMA.SEARCH_SVC" # 필수! (FQN)
max_results: "10" # ⚠️ 문자열! (숫자 아님)
title_column: "doc_title" # 결과에서 제목으로 쓸 컬럼
id_column: "doc_id" # 고유 식별자
filter: # 정적 필터 (항상 적용)
"@eq":
region: "APAC"
columns_and_descriptions: # Agent가 검색 전략 결정에 활용
- name: "content"
description: "Full document text"시험 함정:
text
Q: max_results 값의 타입은?
A: 문자열! "10" (따옴표 필수) — 숫자 10이 아님
Q: filter는 언제 적용되는가?
A: 항상 적용 (정적). Agent가 추가로 동적 필터를 걸 수도 있음
Q: columns_and_descriptions의 역할은?
A: Agent가 "어떤 컬럼을 검색 결과로 받을지" 판단하는 힌트섹션 6: ALTER AGENT
핵심 한 줄:
MODIFY LIVE VERSION SET SPECIFICATION = 전체 교체 (부분 수정 불가!)
도구 하나만 추가하고 싶어도 → YAML 전체를 다시 써야 함. UI에서는 버튼 하나지만 DDL에서는 전체 YAML 재작성입니다.
-- =============================================================
-- 6. ALTER AGENT (Specification 업데이트)
-- =============================================================
-- ★ MODIFY LIVE VERSION SET SPECIFICATION: 전체 교체! (부분 수정 불가)
ALTER AGENT my_db.my_schema.full_agent
MODIFY LIVE VERSION SET SPECIFICATION =
$$
models:
orchestration: claude-sonnet-4-6
orchestration:
budget:
seconds: 45
tokens: 80000
instructions:
response: "Always respond in Korean. Be concise."
orchestration: "Use SalesAnalyst for all data questions."
tools:
- tool_spec:
type: "cortex_analyst_text_to_sql"
name: "SalesAnalyst"
description: "Sales data analysis"
tool_resources:
SalesAnalyst:
semantic_view: "MY_DB.ANALYTICS.SALES_SEMANTIC_VIEW"
$$;
-- ★★★ 시험 포인트 ★★★
-- MODIFY LIVE VERSION SET SPECIFICATION은 전체 교체 (Full Replacement)
-- → 포함하지 않은 필드는 삭제됨!
-- → tools에 Search가 빠지면 Agent에서 Search 사용 불가
-- Comment / Profile만 변경 (Spec 건드리지 않음)
ALTER AGENT my_db.my_schema.full_agent SET
COMMENT = 'Updated description',
PROFILE = '{"display_name": "새 이름", "color": "green"}';alter는 늘 전체 교체라는 것이군. 그럼 create or replace 랑 똑같은거 아녀?
비슷해 보이지만 차이가 있습니다.
CREATE OR REPLACE vs ALTER AGENT MODIFY LIVE VERSION:
CREATE OR REPLACEALTER ... MODIFY LIVE VERSION
| 객체 | 삭제 후 재생성 | 기존 객체 유지 |
| 권한(GRANT) | 초기화됨! | 유지됨 |
| COMMENT/PROFILE | 재지정 필요 | 유지 (SPEC만 교체) |
| thread(대화 이력) | 끊김 (새 객체니까) | 유지됨 |
| 버전 히스토리 | 리셋 | 이어짐 |
실무 판단:
- 개발 중, 처음 만들 때 → CREATE OR REPLACE
- 운영 중 스펙만 바꿀 때 → ALTER ... MODIFY LIVE VERSION (권한/이력 보존)
시험 함정:
text
Q: 운영 중인 Agent의 instructions만 변경하고 싶다. 어떻게?
A: ALTER AGENT ... MODIFY LIVE VERSION SET SPECIFICATION
(전체 YAML을 다시 쓰되, 나머지는 그대로 유지하면서 instructions만 수정)
CREATE OR REPLACE 쓰면 → 기존 GRANT 날아감!핵심: ALTER = 안전한 업데이트 (운영 환경), CREATE OR REPLACE = 깨끗한 재생성 (개발 환경)
권한!을 유지하는 것 매우 중요.