카테고리:: 문자열 및 이진 함수 (AI 함수)

DATA_AGENT_RUN(SNOWFLAKE.CORTEX)¶

:doc:`Cortex Agent </user-guide/snowflake-cortex/cortex-agents>`를 실행하고 응답을 JSON으로 반환합니다.

이 함수를 사용하여 정형 데이터 소스와 비정형 데이터 소스를 모두 오케스트레이션하는 Cortex Agent를 실행하여 인사이트를 제공할 수 있습니다. 여기에는 작업을 계획하고, 도구를 사용하여 이러한 태스크를 실행하고, 응답을 생성하는 작업이 포함됩니다.

참고

:code:`SNOWFLAKE.CORTEX.DATA_AGENT_RUN`은 :doc:`Cortex Agent 실행 API </user-guide/snowflake-cortex/cortex-agents-run>`를 둘러싼 유틸리티 래퍼입니다. 대부분의 애플리케이션 통합에서 Snowflake는 **스트리밍 REST API**를 직접 호출하는 것을 권장합니다.

참고 항목:: CREATE AGENT , SHOW AGENTS , DESCRIBE AGENT , DROP AGENT

구문¶

SNOWFLAKE.CORTEX.DATA_AGENT_RUN( '<agent_name>', <request_body> )

Copy

인자¶

'agent_name'

실행할 에이전트의 정규화된 이름(database.schema.agent_name 형식)입니다.

request_body

에이전트에 보낼 JSON 요청 본문입니다. 이 값은 문자열이어야 합니다(예: $$...$$ 리터럴).

요청 본문에서 지원되는 필드는 다음과 같습니다.

필드	타입	설명
`thread_id`	정수	대화의 스레드 ID입니다. thread_id가 사용되는 경우 parent_message_id도 전달해야 합니다.
`parent_message_id`	정수	스레드에 있는 상위 메시지의 ID입니다. 이것이 첫 번째 메시지인 경우 parent_message_id는 0이어야 합니다.
`messages`	:ref:`label_snowflake_agent_run_Message`의 배열	thread_id 및 parent_message_id가 요청에서 전달되는 경우 메시지의 대화에는 현재 사용자 메시지가 포함됩니다. 그렇지 않으면 메시지에는 대화 기록과 현재 메시지가 포함됩니다. 메시지에는 사용자 쿼리와 어시스턴트 응답이 모두 시간순으로 포함됩니다.
`stream`	boolean	스트리밍 응답(`text/event-stream`)을 반환할지 또는 비 스트리밍 JSON 응답(`application/json`)을 반환할지 여부입니다. True인 경우 응답은 서버 전송 이벤트로 스트리밍됩니다. False인 경우 응답은 JSON으로 반환됩니다.
`tool_choice`	ToolChoice	에이전트가 상호 작용 중에 도구를 선택하고 사용하는 방법을 구성합니다. 도구 사용이 자동인지, 필수인지 또는 특정 도구를 사용해야 하는지를 제어합니다.

예

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

Copy

중요

stream 필드는 무시됩니다. 비 스트리밍 응답은 항상 반환됩니다.

반환¶

에이전트의 응답이 포함된 JSON 문자열을 반환합니다.

액세스 제어 요구 사항¶

에이전트를 실행하려면 Cortex Agent 및 호출 중인 에이전트 오브젝트에 액세스할 수 있는 역할을 사용해야 합니다. 자세한 내용은 액세스 제어 요구 사항 섹션을 참조하십시오.

사용법 노트¶

이 함수는 JSON 문자열을 반환합니다. 이 문자열을 :doc:`try_parse_json`에 전달하여 응답을 VARIANT 값으로 변환합니다.

예¶

에이전트 실행 및 응답 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;

Copy

반환 값 샘플:

{
  "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"
    }
  ],
  "metadata": {
    "run_id": "<run_id>"
  }
}

Copy