使用 Cortex Agent REST API 管理线程¶

本指南说明如何使用 Cortex Agent REST API 创建、继续和管理线程对话。

使用线程的工作流程包括以下步骤：

创建一个新线程，并在向 Cortex Agent REST API 的 agent:run 请求中使用它。
阅读线程中的消息 IDs。
选择一个消息作为继续线程的起点。

启动一个新线程并与 Agent Run 配合使用¶

您必须创建一个新话题，然后将其作为请求的一部分传递给 agent:run。

使用 Create thread 创建新话题。
将新创建线程的 ID 作为请求的一部分传递给 agent:run REST API 端点。

使用代理对象调用 agent:run：
/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run
不使用代理对象调用 agent:run：
/api/v2/cortex/agent:run
作为请求的一部分，传递以下参数：

parent_message_id 必须是 0。这表明该请求是线程的起点。

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¶

Agent 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)

继续对话¶

在对话的下一轮中，将 parent_message_id 设置为最后成功的助手消息 ID，并在 messages 中传入新值。在此示例中，父消息 ID 是 456。

备注

您必须将助手消息 ID 作为 parent_message_id 传递，以确保 LLM 正常工作。您不能传递用户消息 ID。如果您不记得最后一条消息 ID，可使用 Create thread 列出线程中的所有消息。

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

}

在后续请求中，继续使用最新成功的助手消息 ID 作为 parent_message_id。

分支对话¶

您还可以从任意早期助手消息继续对话，从而创建分叉。要分叉对话，请在新请求中将所需的助手消息 ID 作为 parent_message_id 传递。在以下示例中，3 (user) -> 4 (assistant) 和 5 (user) -> 6 (assistant) 表示同一助手响应的两个不同分叉。

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

故障排除¶

在极少数情况下，Agent API 可能无法存储助手消息。如果响应中缺少助手元数据，请忽略失败的回合，从最后成功的助手消息继续。

例如，考虑以下线程：

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

要继续对话，请将消息 ID 2 作为新请求的一部分传递，因为它是最后成功的助手消息。

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