AGENT_RUN

AGENT_RUN (SNOWFLAKE.CORTEX)

SNOWFLAKE.CORTEX.AGENT_RUN() 함수는 에이전트 객체 없이 Cortex Agent를 실행하고 응답을 JSON으로 반환해요. 이 함수를 사용하면 에이전트 객체를 먼저 만들 필요 없이 Cortex Agents와 직접 상호작용할 수 있어요. 오케스트레이션 모델과 도구를 포함한 구성을 요청 본문에서 제공하면 돼요.

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

출처: Snowflake SQL Reference

본문

문법

SNOWFLAKE.CORTEX.AGENT_RUN( <request_body> [, <create_thread_if_not_present> ] )

인자

request_body — 에이전트에 보낼 JSON 요청 본문이에요. 이 값은 문자열(예: $$...$$ 리터럴)이어야 해요.

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

예제:

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

create_thread_if_not_present — 요청 본문에 thread_id가 없을 때 새 스레드를 자동으로 만들지 지정하는 BOOLEAN 값이에요. 기본값: FALSE.

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

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

• 요청 본문에서 "background": true로 설정해 에이전트를 비동기로 실행할 수 있어요. 백그라운드 실행은 AWS와 Azure에서 일반적으로 사용 가능해요(GA). 이때:
  • 요청 본문에 thread_id가 필요해요.
  • 함수는 "status": "in_progress"와 run_id를 담은 응답으로 즉시 반환돼요.
  • 실행 완료 후 어시스턴트 응답을 가져오려면 스레드 ID로 THREAD_MESSAGES (SNOWFLAKE.CORTEX)를 폴링하세요.

반환

에이전트의 응답을 담은 JSON 문자열을 반환해요.

접근 제어 요구사항

에이전트를 실행하려면 Cortex Agents에 접근할 수 있는 역할을 사용해야 해요. 자세한 내용은 API 접근 역할을 참고하세요.

사용 노트

• 함수는 JSON 문자열을 반환해요. 이 문자열을 TRY_PARSE_JSON에 전달해 응답을 VARIANT 값으로 변환하세요.
• DATA_AGENT_RUN (SNOWFLAKE.CORTEX)과 달리 이 함수는 에이전트 객체를 먼저 만들 필요가 없어요. 대신 구성을 요청 본문에서 직접 제공하면 돼요.
• create_thread_if_not_present를 TRUE로 설정하면, 요청 본문에 thread_id가 없을 때 새 스레드가 자동으로 만들어져요. 응답에는 새로 만든 스레드의 thread_id가 포함되어, 이후 요청에서 대화를 계속하는 데 사용할 수 있어요.
• 에이전트를 비동기로 실행하려면 요청 본문에서 "background": true로 설정하고 thread_id를 포함하세요. 함수는 진행 중(in-progress) 상태와 run_id로 즉시 반환돼요. THREAD_MESSAGES (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-sonnet-4-6"
        }
      }$$
    )
  ) AS resp;

샘플 반환 값:

{
  "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-sonnet-4-6",
          "output_tokens": {
            "total": 38
          }
        }
      ]
    }
  },
  "role": "assistant"
}

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

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-sonnet-4-6"
        }
      }$$,
      TRUE
    )
  ) AS resp;

더 알아보기 (Learn more)

• THREAD_MESSAGES (SNOWFLAKE.CORTEX)
• DATA_AGENT_RUN (SNOWFLAKE.CORTEX)