Cortex Agents

Cortex Agents는 정형 데이터 소스와 비정형 데이터 소스 모두를 조정하여 인사이트를 제공합니다. 작업을 계획하고, 도구를 사용하여 작업을 실행하고, 응답을 생성합니다. Agent는 Cortex Analyst (정형) 및 Cortex Search(비정형)와 함께 LLMs 을 도구로 사용하여 데이터를 분석합니다. Cortex Search는 비정형 소스에서 인사이트를 추출하는 반면, Cortex Analyst 는 정형 데이터를 처리하기 위해 SQL 을 생성합니다. 도구 식별 및 도구 실행을 포괄적으로 지원하여 엔터프라이즈 데이터에 기반한 정교한 애플리케이션을 제공할 수 있습니다.

워크플로에는 네 가지 핵심 구성 요소가 포함됩니다.

  1. 계획: 애플리케이션은 정형 소스와 비정형 소스의 데이터 처리 간에 변환하는 경우가 많습니다. 예를 들어, 사용자의 쿼리에 응답하도록 설계된 대화형 앱을 생각해 보십시오. 비즈니스 사용자는 먼저 매출(정형) 기준 상위 유통업체를 조회한 다음 계약(비정형)에 대한 조회로 변환할 수 있습니다. Cortex Agents는 요청을 구문 분석하여 계획을 조율하고 솔루션 또는 응답에 도달할 수 있습니다.

    1. 옵션 탐색: 사용자가 모호한 질문(예: “Acme Supplies에 대해 알려주십시오”)을 하면 에이전트은 제품, 위치, 영업 담당자 등 다양한 순열을 고려하여 모호함을 없애고 정확도를 높입니다.

    2. 하위 작업으로 분할: Cortex Agent는 보다 정확한 응답을 위해 작업이나 요청(예: “What are the differences between contract terms for Acme Supplies and Acme Stationery?”)을 여러 부분으로 분할할 수 있습니다.

    3. 도구 간 라우팅: 에이전트가 적합한 도구(Cortex Analyst 또는 Cortex Search)를 선택하여 관리되는 액세스를 보장하고 기업 정책을 준수합니다.

  2. 도구 사용: 계획을 세우면 에이전트가 효율적으로 데이터를 검색합니다. Cortex Search는 비정형 소스에서 인사이트를 추출하고, Cortex Analyst는 정형 데이터를 처리하기 위해 SQL 을 생성합니다. 도구 식별 및 도구 실행을 포괄적으로 지원하여 엔터프라이즈 데이터에 기반한 정교한 애플리케이션을 제공할 수 있습니다.

  3. 반영: 각 도구 사용 후 에이전트은 결과를 평가하여 다음 단계(설명 요청, 반복 또는 최종 응답 생성)를 결정합니다. 이 오케스트레이션을 통해 복잡한 데이터 쿼리를 처리하는 동시에 Snowflake의 보안 경계 내에서 정확성과 규정 준수를 보장할 수 있습니다.

  4. 모니터링 및 반복: 배포 후 고객은 메트릭을 추적하고, 성능을 분석하고, 동작을 개선하여 지속적으로 개선할 수 있습니다. 클라이언트 애플리케이션 개발자는 TruLens 를 사용하여 Agent 상호 작용을 모니터링할 수 있습니다. 거버넌스 제어를 지속적으로 모니터링하고 개선함으로써 기업은 보안 및 규정 준수를 유지하면서 AI 에이전트를 자신 있게 확장할 수 있습니다.

시작하는 데 도움이 되는 자습서는 Cortex Agents 자습서 섹션을 참조하십시오.

참고

Snowflake는 고품질의 응답을 제공하기 위해 노력하지만, LLM 응답의 정확성이나 제공된 인용이 보장되지는 않습니다. 사용자에게 답변을 제공하기 전에 Agents API 의 모든 답변을 검토해야 합니다.

액세스 제어 요구 사항

쿼리하는 사용자가 있어야 합니다.

  • 쿼리에서 참조한 Cortex Search Service의 USAGE.

  • Cortex Analyst 의미 체계 모델에서 참조되는 데이터베이스, 스키마 및 테이블에 대한 USAGE

  • CORTEX_USER 데이터베이스 역할이 부여된 역할입니다. 자세한 내용은 필수 권한 섹션을 참조하십시오.

Agent API 사용 방법

이 섹션에서는 Agent API 를 사용하여 Agent를 만드는 단계를 보여줍니다.

REST API 인증 구성

Snowflake REST APIs 는 프로그래밍 방식의 액세스 토큰(PATs), JSON 웹 토큰(JWTs)을 사용한 키 페어 인증, OAuth 를 통한 인증을 지원합니다. 자세한 내용은 Snowflake를 사용하여 Snowflake REST APIs 인증하기 섹션을 참조하십시오.

Cortex Analyst용 의미 체계 모델 만들기

Cortex Analyst를 사용하여 자연어에서 SQL 쿼리를 만들 수 있습니다. Cortex Analyst를 사용하려면 의미 체계 모델을 만들어야 합니다. 자세한 내용은 의미 체계 모델 만들기 섹션을 참조하십시오.

Cortex Search Service 만들기

Cortex Search를 사용하여 데이터를 검색하십시오. 자세한 내용은 CREATE CORTEX SEARCH SERVICE 섹션을 참조하십시오.

참고

쿼리하는 사용자의 DEFAULT_ROLE 에는 Cortex Search Service와 해당 데이터베이스 및 스키마에 대한 USAGE 권한이 있어야 합니다.

API 호출하기

먼저, Snowflake 계정 URL 을 찾습니다. URL 및 PAT 가 있으면 다음 구문을 사용하여 명령줄에서 cURL 을 사용하여 Agent API 를 쿼리할 수 있습니다.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/agent:run" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "model": "llama3.1-70b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "what are the top 3 customers by revenue"
                }
            ]
        }
    ],
    "tools": [
        {
            "tool_spec": {
                "type": "cortex_search",
                "name": "transcript_search"
            }
        },
        {
            "tool_spec": {
                "type": "cortex_analyst_text_to_sql",
                "name": "data_model"
            }
        }
    ],
    "tool_resources": {
        "transcript_search": {"name": "testdb.testschema.transcript_search_service"},
        "data_model": {"semantic_model_file": "@testdb.testschema.stage/sample_data_model.yaml"}
    }
}'
Copy

응답은 클라이언트에 점진적으로 스트림됩니다.

지원 모델

Cortex Agents와 함께 다음 모델을 사용하여 응답을 생성할 수 있습니다. 이 모델은 오케스트레이션에 사용되지 않는다는 점에 유의하십시오.

  • llama3.1-70b

  • llama3.3-70b

  • mistral-large2

  • claude-3-5-sonnet

응답 지침을 지정하여 에이전트의 응답을 사용자 지정할 수도 있습니다.

{
    "response_instruction": "You will always maintain a friendly tone and provide concise response"
}
Copy

중요

Cortex Agents는 일부 리전에서는 가용성이 제한될 수 있는 모델을 사용합니다. 자세한 내용은 가용성 섹션을 참조하십시오.

리전 가용성

Cortex Agents 기능은 다음 리전에서 사용할 수 있습니다.

함수
(모델)
AWS US 서부 2
(오리건)
AWS US 동부 1
(북부 버지니아)
AWS 유럽 중부 1
(프랑크푸르트)
AWS 유럽 서부 1
(아일랜드)
AWS AP 동남부 2
(시드니)
AWS AP 북동부 1
(도쿄)
Azure 동부 US 2
(버지니아)
Azure 서유럽
(네덜란드)
AWS
(리전 간)
COMPLETE
(claude-3-5-sonnet)

✔

✔

✔
COMPLETE
(llama3.2-1b)

✔

✔
COMPLETE
(llama3.2-3b)

✔

✔
COMPLETE
(llama3.1-8b)

✔

✔

✔

✔

✔

✔

✔

✔
llama3.1-70b

✔

✔

✔

✔

✔

✔

✔

✔

✔
llama3.3-70b

✔

✔

✔
snowflake-llama-3.3-70b

✔

✔
llama3.1-405b

✔

✔

✔

✔
snowflake-llama-3.1-405b

✔

✔
snowflake-arctic

✔

✔

✔
deepseek-r1

✔
reka-core

✔

✔
reka-flash

✔

✔

✔

✔
mistral-large2

✔

✔

✔

✔

✔

✔

✔

✔

✔
mixtral-8x7b

✔

✔

✔

✔

✔

✔

✔

✔

✔
mistral-7b

✔

✔

✔

✔

✔

✔

✔

✔

✔
jamba-instruct

✔

✔

✔

✔
jamba-1.5-mini

✔

✔

✔

✔
jamba-1.5-large

✔

✔
gemma-7b

✔

✔

✔

✔

✔

✔
e5-base-v2

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-m

✔

✔

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-m-v1.5

✔

✔

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-l-v2.0

✔

✔

✔

✔

✔

✔

✔

✔

✔
nv-embed-qa-4

✔

✔
multilingual-e5-large

✔

✔

✔

✔

✔

✔

✔

✔

✔

voyage-multilingual-2

✔

✔

✔

✔

✔

✔

✔

✔

✔

비용 고려 사항

미리 보기에서, Cortex Search Service는 Snowflake Service Consumption Table 에 나열된 세부 정보에 따라 비용이 발생합니다.

Cortex Agent 구축

Cortex Agents를 사용하여 계약 조건에 관한 비즈니스 사용자의 질문에 답변하는 대화형 애플리케이션을 구현해 보겠습니다. 주요 구성 요소를 살펴보겠습니다. (전체 자습서는 Cortex Agents 시작하기 를 참조하십시오).

1단계. 요청에 사용할 도구를 지정합니다

{
    "tools": [
        {
            "tool_spec": {
                "name": "data_model",
                "type": "cortex_analyst_text_to_sql"
            }
        },
        {
            "tool_spec": {
                "name": "transcript_search",
                "type": "cortex_search"
            }
        },
        {
            "tool_spec": {
                "type": "sql_exec",
                "name": "sql_exec"
            }
        },
        {
            "tool_spec": {
                "type": "data_to_chart",
                "name": "data_to_chart"
            }
        }
    ]
}
Copy

2단계. Cortex Agent가 도구 호출에 사용할 수 있는 도구에 정적 인자(리소스)를 제공합니다.

{
    "tool_resources": {
        "data_model": {
            "semantic_model_file": "@cortex_tutorial_db.public.revenue_semantic_model.yaml"
        },
        "transcript_search": {
            "name": "cortex_tutorial_db.public.contract_terms",
            "max_results": 5,
            "title_column": "TRANSCRIPT_TITLE",
            "id_column": "TRANSCRIPT_ID",
            "filter": {"@eq": {"TRANSCRIPT_TYPE": "ENTERPRISE"} }
        }
    }
}
Copy

3단계. 이제 응답을 생성할 모델과 시스템 프롬프트를 지정하겠습니다

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": {
                "type": "text",
                "text": "You’re a friendly assistant to answer questions."
            }
        }
    ]
}
Copy

4단계. 분석가 도구에서 정형 데이터에 액세스하는 데 사용할 의미 체계 모델 파일을 생성합니다

이 가이드의 1~3단계에 따라 Cortex Analyst 의미 체계 모델을 구축합니다. Cortex Agents 시작하기

5단계. 다음으로, 비정형 데이터에 접근하기 위한 검색 도구의 검색 서비스를 설정합니다

이 가이드의 4~5단계에 따라 Cortex Search Service를 구축합니다. Cortex Agents 시작하기

6단계. 이제 Agent와 상호작용할 준비가 되었습니다. 메시지 필드를 사용하여 요청을 보내고 응답을 받습니다

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "You’re a friendly assistant to answer questions"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "hello"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "hi there!"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "..."
                }
            ]
        }
    ]
}
Copy

7단계. 상호작용이 진행됨에 따라 Agent는 도구를 식별하고 작업을 수행하기 위해 (서비스 측에서) 실행합니다. 아래 예제에서 Agent는 Text2SQL 을 도구로 식별하고 실행하여 SQL 쿼리를 가져옵니다. 상호작용하는 동안 Agent는 클라이언트 애플리케이션(클라이언트 측)에 도구 사용을 요청할 수 있습니다. 예를 들어, Agent는 실행해야 할 SQL 쿼리를 지정합니다.

{
    "role": "assistant",
    "content": [
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_001",
                "name": "cortex_analyst_text_to_sql",
                "input": {
                    "query": "...",
                    "semantic_model_file": "..."
                }
            }
        },
        {
            "type": "tool_results",
            "tool_results": {
                "status": "success",
                "tool_use_id": "tool_001",
                "content": [
                    {
                        "type": "json",
                        "json": {
                            "sql": "select * from table"
                        }
                    }
                ]
            }
        },
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_002",
                "name": "sql_exec",
                "input": {
                    "sql": "select * from table"
                }
            }
        }
    ]
}
Copy
언어: 한국어