THREAD_MESSAGES
THREAD_MESSAGES (SNOWFLAKE.CORTEX) (스레드 메시지)
Cortex Agent 스레드의 메시지를 JSON으로 반환해요.
출처: Snowflake SQL Reference - THREAD_MESSAGES (SNOWFLAKE.CORTEX)
본문
에이전트 실행이 완료된 후 스레드의 모든 메시지를 검색하는 데 이 함수를 사용할 수 있어요. 이는 특히 background: true로 시작한 비동기(백그라운드) 에이전트 실행의 결과를 폴링하는 데 유용해요.
참고: SNOWFLAKE.CORTEX.THREAD_MESSAGES는 Cortex Agents Threads REST API의 유틸리티 래퍼예요.
참고: DATA_AGENT_RUN (SNOWFLAKE.CORTEX), AGENT_RUN (SNOWFLAKE.CORTEX)
구문
SNOWFLAKE.CORTEX.THREAD_MESSAGES( <thread_id> [, <page_size>, <last_message_id> ] )
인자
thread_id
메시지를 검색할 스레드의 ID예요.
page_size (선택)
페이지당 반환할 최대 메시지 수예요. 페이지네이션을 위해 last_message_id와 함께 사용하세요.
last_message_id (선택)
이전 페이지의 마지막 메시지 ID예요. 반환되는 메시지는 이 메시지 ID 이후의 메시지들이에요. 페이지네이션을 위해 page_size와 함께 사용하세요.
반환 값
스레드의 메시지 배열을 담은 JSON 문자열을 반환해요. 각 메시지는 역할(role), 콘텐츠(content), 메시지 메타데이터를 포함해요.
접근 제어 요구 사항
스레드 메시지를 검색하려면 Cortex Agents에 접근할 수 있는 역할을 사용해야 해요. 자세한 내용은 API 접근 역할(API access roles)을 참고하세요.
사용 시 참고 사항
-
이 함수는 JSON 문자열을 반환해요. 이 문자열을 TRY_PARSE_JSON에 전달해 응답을 VARIANT 값으로 변환하세요.
-
이 함수는 요청 본문에서
background: true로 시작한 비동기 에이전트 실행의 결과를 폴링하는 데 흔히 사용돼요. 백그라운드 실행을 시작한 후 스레드 ID로THREAD_MESSAGES를 호출해 어시스턴트 응답이 기록되었는지 확인하세요. -
페이지네이션할 때는
page_size와last_message_id둘 다 제공하세요. 두 선택 인자를 모두 생략하면 스레드의 모든 메시지가 반환돼요.
예시
스레드의 모든 메시지를 검색해요.
SELECT
TRY_PARSE_JSON(
SNOWFLAKE.CORTEX.THREAD_MESSAGES(12345)
) AS messages;
페이지네이션으로 메시지를 검색해요.
SELECT
TRY_PARSE_JSON(
SNOWFLAKE.CORTEX.THREAD_MESSAGES(12345, 50, 67890)
) AS messages;
비동기 에이전트 실행과 함께 사용해요.
-- 1) Start an async agent run
SELECT
TRY_PARSE_JSON(
SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
'MY_DB.MY_SCHEMA.MY_AGENT',
$${
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "What were the top-selling products last month?" }
]
}
],
"thread_id": 12345,
"background": true
}$$
)
) AS resp;
-- 2) Poll thread messages for the assistant response
SELECT
TRY_PARSE_JSON(
SNOWFLAKE.CORTEX.THREAD_MESSAGES(12345)
) AS messages;