DATA_AGENT_RUN

DATA_AGENT_RUN (SNOWFLAKE.CORTEX)

SNOWFLAKE.CORTEX.DATA_AGENT_RUN 함수는 Cortex Agent를 실행하고 응답을 JSON으로 반환해요.

출처: DATA_AGENT_RUN (SNOWFLAKE.CORTEX)

본문

이 함수를 사용해 Cortex Agent를 실행할 수 있어요. Cortex Agent는 정형(structured) 및 비정형(unstructured) 데이터 소스 모두를 오케스트레이션하여 인사이트를 제공해요. 여기에는 작업 계획, 이러한 작업을 실행하기 위한 도구 사용, 응답 생성이 포함돼요.

참고: SNOWFLAKE.CORTEX.DATA_AGENT_RUN은 Cortex Agents Run API의 유틸리티 래퍼에요. 대부분의 애플리케이션 통합에서는 Snowflake가 스트리밍 REST API를 직접 호출하는 것을 권장해요.

함께 보기: CREATE AGENT, SHOW AGENTS, DESCRIBE AGENT, DROP AGENT

구문 (Syntax)

SNOWFLAKE.CORTEX.DATA_AGENT_RUN( '<agent_name>[!<version>]', <request_body> [, <create_thread_if_not_present> ] )

인자 (Arguments)

• 'agent_name[!version]' — 실행할 에이전트의 정규화된 이름으로, database.schema.agent_name 형식이에요. 특정 에이전트 버전을 대상으로 하려면 선택적으로 !<version>을 추가할 수 있어요. 버전 접미사를 지정하지 않으면 에이전트의 DEFAULT 버전이 사용돼요(명시적 기본값이 설정되지 않은 경우 LIVE 버전으로 폴백). 지원되는 버전 값은 다음과 같아요: !LIVE(현재 LIVE 초안 버전 실행), !DEFAULT(DEFAULT 버전 실행), !VERSION$N(특정 커밋 버전 실행, 예: !VERSION$2), !LAST(가장 최근에 커밋된 버전 실행), !FIRST(첫 번째 커밋 버전 실행). 에이전트 이름에 ! 문자가 포함되어 있으면 버전 구분자로 처리되지 않도록 해당 부분을 큰따옴표로 묶어요. 예를 들어 'db.schema."my!agent"!LIVE'는 my!agent라는 에이전트의 LIVE 버전을 대상으로 해요.
• request_body — 에이전트로 보낼 JSON 요청 본문이에요. 이 값은 문자열(예: $$...$$ 리터럴)이어야 해요. 요청 본문에서 지원되는 필드는 다음과 같아요:

예제 (Example):

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ],
      "status": "completed",
      "error": {
        "code": "399504",
        "message": "Error during execution"
      }
    }
  ],
  "background": false,
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": ["analyst_tool", "search_tool"]
  }
}

• create_thread_if_not_present — 요청 본문에 thread_id가 포함되지 않을 때 새 스레드를 자동으로 생성할지 지정하는 BOOLEAN 값이에요. 기본값: FALSE.

중요: 요청 본문에서 stream을 true로 설정하는 것은 지원되지 않아요. "stream": true를 포함하면 함수는 오류를 반환해요. 항상 비스트리밍 응답이 반환돼요.

비동기(백그라운드) 실행

요청 본문에서 "background": true를 설정하여 에이전트를 비동기로 실행할 수 있어요. 백그라운드 실행은 AWS와 Azure에서 일반적으로 사용 가능해요(Generally Available). 이 경우:

• 요청 본문에 thread_id가 필요해요.
• 함수는 "status": "in_progress"와 run_id가 포함된 응답과 함께 즉시 반환돼요.
• 실행 완료 후 스레드 ID로 THREAD_MESSAGES (SNOWFLAKE.CORTEX)를 폴링하여 어시스턴트 응답을 검색해요.

반환 (Returns)

에이전트의 응답이 포함된 JSON 문자열을 반환해요.

함수는 Cortex Agents Run API가 생성하는 개별 SSE 이벤트가 아닌 최종 집계된 응답을 반환해요. 치명적이지 않은 경고가 발생하면 응답에 최상위 warnings 배열이 포함돼요. 예를 들어 경고 코드 399569는 호출자의 역할이 명명된 도구에 접근할 수 없어 에이전트가 나머지 도구로 계속 진행했음을 의미해요.

접근 제어 요구 사항 (Access control requirements)

에이전트를 실행하려면 Cortex Agents와 호출하는 에이전트 객체에 접근할 수 있는 역할을 사용해야 해요. 자세한 내용은 API access roles를 참조해요.

사용 메모 (Usage notes)

• 함수는 JSON 문자열을 반환해요. 이 문자열을 TRY_PARSE_JSON에 전달하여 VARIANT 값으로 변환해요.
• 파싱된 응답의 최상위 warnings 배열을 검토하고 관련 경고를 사용자에게 표시해요. 접근 불가 도구 경고 동작은 관련 문서를 참조해요.
• create_thread_if_not_present를 TRUE로 설정하면 요청 본문에 thread_id가 없을 때 새 스레드가 자동으로 생성돼요. 응답에는 새로 생성된 스레드의 thread_id가 포함되며, 이후 요청에서 이 스레드를 사용해 대화를 계속할 수 있어요.
• 에이전트를 비동기로 실행하려면 요청 본문에 "background": true를 설정하고 thread_id를 포함해요. 함수는 진행 중 상태와 run_id와 함께 즉시 반환돼요. 완료된 응답을 위해 THREAD_MESSAGES (SNOWFLAKE.CORTEX)를 폴링해요.

예제 (Examples)

에이전트를 실행하고 응답 JSON을 파싱해요:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT',
      $${
        "parent_message_id": 1234,
        "thread_id": 5678,
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS resp;

샘플 반환 값:

{
  "role": "assistant",
  "content": [
    {
      "thinking": {
        "text": "\n...\n"
      },
      "type": "thinking"
    },
    {
      "tool_use": {
        "input": {
          "...": "..."
        },
        "name": "<tool_name>",
        "tool_use_id": "<tool_use_id>",
        "type": "<tool_type>"
      },
      "type": "tool_use"
    },
    {
      "text": "Based on the data available, there are two main types of products...",
      "type": "text"
    }
  ],
  "warnings": [
    {
      "code": "399569",
      "message": "TOOL_NOT_ACCESSIBLE: Search1 (cortex_search) - The Cortex Search Service does not exist or access is not authorized for the current role: db.schema.css1"
    }
  ],
  "metadata": {
    "run_id": "<run_id>"
  }
}

동기 실행에서 접근 불가 도구 경고만 반환하려면:

WITH agent_response AS (
  SELECT TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT',
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS response
)
SELECT warning.value
  FROM agent_response,
    LATERAL FLATTEN(input => response:warnings) AS warning
  WHERE warning.value:code::STRING = '399569';

자동 스레드 생성을 사용해 에이전트를 실행해요:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT',
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$,
      TRUE
    )
  ) AS resp;

Personal Database의 에이전트를 실행하고 스레드를 자동으로 생성해요:

SELECT TRY_PARSE_JSON(
  SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
    '"USER$JSMITH".PUBLIC.MY_AGENT',
    $${
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "What are some types of products?" }
          ]
        }
      ]
    }$$,
    TRUE
  )
) AS resp;

에이전트의 특정 커밋 버전을 실행해요:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT!VERSION$2',
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS resp;

에이전트의 LIVE(초안) 버전을 실행해요:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT!LIVE',
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS resp;

더 알아보기 (Learn more)

• CREATE AGENT, SHOW AGENTS, DESCRIBE AGENT, DROP AGENT
• THREAD_MESSAGES (SNOWFLAKE.CORTEX)
• TRY_PARSE_JSON
• 문자열 및 이진 함수 (String & binary functions)
• AI 함수 (AI Functions)