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

AGENT_RUN(SNOWFLAKE.CORTEX)¶

에이전트 오브젝트 없이 :doc:`Cortex Agent </user-guide/snowflake-cortex/cortex-agents>`를 실행하고 응답을 JSON으로 반환합니다.

이 함수를 사용하면 먼저 에이전트 오브젝트를 생성하지 않고도 Cortex Agent와 직접 상호 작용할 수 있습니다. 요청 본문에 오케스트레이션 모델 및 도구를 포함한 구성을 제공합니다.

참고

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

구문¶

SNOWFLAKE.CORTEX.AGENT_RUN( <request_body> )

Copy

인자¶

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	에이전트가 상호 작용 중에 도구를 선택하고 사용하는 방법을 구성합니다. 도구 사용이 자동인지, 필수인지 또는 특정 도구를 사용해야 하는지를 제어합니다.
`models`	ModelConfig	에이전트의 모델 구성입니다. 오케스트레이션 모델을 포함합니다(예: clade-4-sonnet). 입력하지 않으면 모델이 자동으로 선택됩니다. 현재 `오케스트레이션` 단계에만 사용 가능합니다.
`instructions`	AgentInstructions	응답, 오케스트레이션, 시스템, 샘플 질문 등 에이전트의 동작에 대한 지침입니다.
`orchestration`	OrchestrationConfig	예산 제약 조건(예: 초, 토큰)을 포함한 오케스트레이션 구성입니다.
`tools`	:ref:`label_snowflake_agent_run_Tool`의 배열	에이전트가 사용할 수 있는 도구 목록입니다. 각 도구에는 유형, 이름, 설명, 입력 스키마가 있는 tool_spec이 포함됩니다. 도구의 tool_resources에 해당 구성이 있을 수 있습니다.
`tool_resources`	:ref:`label_snowflake_agent_run_ToolResource`의 맵	도구 배열에서 참조되는 각 도구에 대한 구성입니다. 키는 해당 도구의 이름과 일치해야 합니다.

예

{
  "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"
    ]
  },
  "models": {
    "orchestration": "claude-4-sonnet"
  },
  "instructions": {
    "response": "You will respond in a friendly but concise manner",
    "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
    "system": "You are a friendly agent ..."
  },
  "orchestration": {
    "budget": {
      "seconds": 30,
      "tokens": 16000
    }
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "get_revenue",
        "description": "Fetch the delivery revenue for a location.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
  "tool_resources": {
    "get_revenue": {
      "type": "function",
      "execution_environment": {
        "type": "warehouse",
        "warehouse": "MY_WH"
      },
      "identifier": "DB.SCHEMA.UDF"
    }
  }
}

Copy

중요

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

반환¶

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

액세스 제어 요구 사항¶

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

사용법 노트¶

이 함수는 JSON 문자열을 반환합니다. 이 문자열을 :doc:`try_parse_json`에 전달하여 응답을 VARIANT 값으로 변환합니다.
:doc:`data_agent_run-snowflake-cortex`와 달리, 이 함수에서는 에이전트 오브젝트를 먼저 생성할 필요가 없습니다. 대신 요청 본문에 직접 구성을 제공합니다.

예¶

에이전트 실행 및 응답 JSON 구문 분석:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.AGENT_RUN(
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "What is the total revenue for 2025?"
              }
            ]
          }
        ],
        "models": {
          "orchestration": "claude-4-sonnet"
        }
      }$$
    )
  ) AS resp;

Copy

반환 값 샘플:

{
  "content": [
    {
      "text": "The total revenue for 2025 was $100,000.",
      "type": "text"
    }
  ],
  "metadata": {
    "usage": {
      "tokens_consumed": [
        {
          "context_window": 200000,
          "input_tokens": {
            "cache_read": 0,
            "cache_write": 0,
            "total": 67,
            "uncached": 67
          },
          "model_name": "claude-4-sonnet",
          "output_tokens": {
            "total": 38
          }
        }
      ]
    }
  },
  "role": "assistant"
}

Copy