Cortex Agent REST API에서 스레드 사용¶

이 가이드에서는 Cortex Agent REST API를 사용하여 스레드 대화를 생성, 지속 및 관리하는 방법을 설명합니다.

스레드를 사용하기 위한 워크플로에는 다음 단계가 포함됩니다.

새 스레드를 만들고 Cortex Agent REST API에 대한 agent:run 요청의 일부로 사용합니다.
스레드의 메시지 IDs를 읽습니다.
스레드를 계속할 메시지를 선택합니다.

새 스레드를 시작하고 Agent Run과 함께 사용¶

새 스레드를 생성한 다음, 요청의 일부로 :code:`agent:run`에 전달해야 합니다.

:ref:`label-cortex-agents-threads_rest_api_create`를 사용하여 새 스레드를 만듭니다.
새로 생성된 스레드의 ID를 agent:run REST API 엔드포인트 중 하나에 대한 요청의 일부로 전달합니다.

:code:`agent:run`(에이전트 오브젝트 포함):
/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run
:code:`agent:run`(에이전트 오브젝트 제외):
/api/v2/cortex/agent:run
요청의 일부로 다음을 전달합니다.

:code:`parent_message_id`는 :code:`0`이어야 합니다. 이는 이 요청이 스레드의 시작임을 나타냅니다.

:code:`messages`에 정확히 하나의 사용자 메시지가 있습니다.
POST <agent run endpoint>
{
  "thread_id": 1234,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2025?"
        }
      ]
    }
  ],
}

반환된 메시지 IDs 읽기¶

에이전트 API는 대화의 각 메시지에 대한 메타데이터 이벤트를 다시 스트리밍합니다. 다음 출력은 메타데이터의 구조를 보여줍니다. 항상 사용자 및 어시스턴트 메타데이터 이벤트를 모두 수신 대기합니다.

event: metadata
data: {"metadata": {"role":"user","message_id":123}}

event: metadata
data: {"metadata": {"role":"assistant","message_id":456}}

이 출력에서 메시지 IDs는 대화에서 다음에 해당합니다.

123: 지속형 사용자 메시지 ID
456: 지속형 어시스턴트 메시지 ID

이러한 IDs가 함께 다음 스레드를 형성합니다.

0 -> 123 (user) -> 456 (assistant)

대화 이어가기¶

대화의 다음 차례를 위해 :code:`parent_message_id`를 마지막으로 성공한 어시스턴트 메시지 ID로 설정하고 :code:`messages`에 새 값을 전달합니다. 이 예에서 상위 메시지 ID는 :code:`456`입니다.

참고

LLM 함수가 예상대로 작동하도록 하려면 어시스턴트 메시지 ID를 :code:`parent_message_id`로 전달해야 합니다. 사용자 메시지 ID는 전달할 수 없습니다. 마지막 메시지 ID를 잊어버린 경우 :ref:`label-cortex-agents-threads_rest_api_create`를 사용하여 스레드의 모든 메시지를 나열합니다.

{
  "thread_id": 1234,
  "parent_message_id": 456,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What about last year?"
        }
      ]
    }
  ],

}

후속 요청에서 성공한 최신 어시스턴트 메시지 ID를 계속 :code:`parent_message_id`로 사용합니다.

대화 분기¶

이전 어시스턴트 메시지에서 계속 진행하여 대화를 분기할 수도 있습니다. 대화를 분기하려면 새 요청에서 원하는 어시스턴트 메시지 ID를 parent_message_id`로 전달합니다. 다음 예에서 :code:`3 (user) -> 4 (assistant) 및 :code:`5 (user) -> 6 (assistant)`는 동일한 어시스턴트 응답의 두 개의 서로 다른 분기를 나타냅니다.

0 -> 1 (user) -> 2 (assistant) -> 3 (user) -> 4 (assistant)
0 -> 1 (user) -> 2 (assistant) -> 5 (user) -> 6 (assistant)

문제 해결하기¶

드문 경우지만 에이전트 API가 어시스턴트 메시지를 저장하지 못할 수 있습니다. 응답에서 어시스턴트 메타데이터가 누락된 경우 실패한 대화 차례를 무시하고 마지막으로 성공한 어시스턴트 메시지부터 계속 진행합니다.

예를 들어 다음 스레드를 고려해 보세요.

0 -> 1 (user) -> 2 (assistant) -> 3 (user) -> [assistant failed]

해당 메시지가 마지막으로 성공한 어시스턴트 메시지이므로 대화를 계속하려면 메시지 ID를 새 요청의 일부로 전달하세요.

0 -> 1 (user) -> 2 (assistant) -> 5 (user) -> 6 (assistant)