Usar threads com a API REST do Cortex Agent¶

Este guia explica como criar, continuar e gerenciar conversas encadeadas usando a API REST do Cortex Agent.

O fluxo de trabalho para usar threads inclui as seguintes etapas:

Criar um novo thread e usá-lo como parte de uma solicitação de agent:run à API REST do Cortex Agent.
Leia os IDs de mensagem do thread.
Escolha uma mensagem para continuar o thread.

Como iniciar um novo thread e usá-lo com o Agent Run¶

Você deve criar um novo thread e passá-lo como parte de uma solicitação para agent:run.

Criar um novo thread usando Criação de thread.
Como passar o ID do thread recém-criado como parte de uma solicitação para um dos oontos de extremidade da API REST agent:run.

agent:run com objeto do agente:
/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run
agent:run sem objeto do agente:
/api/v2/cortex/agent:run
Como parte da solicitação, passe o seguinte:

parent_message_id deve ser 0. Isso indica que esta solicitação é o início do thread.

Exatamente uma mensagem de usuário no 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?"
        }
      ]
    }
  ],
}

Ler os IDs da mensagem retornada¶

A API Agent transmite eventos de metadados para cada mensagem na conversa. A saída a seguir mostra a estrutura dos metadados. Sempre ouça eventos de metadados do usuário e do assistente.

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

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

Nesta saída, os IDs de mensagens correspondem ao seguinte na conversa:

123: o ID da mensagem do usuário persistente
456: o ID da mensagem do assistente persistente

Juntos, esses IDs formam o seguinte thread:

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

Continuar a conversa¶

Para a próxima vez da conversa, defina parent_message_id para o último ID de mensagem bem-sucedido do assistente e passam novos valores em messages. Neste exemplo, o ID da mensagem pai é 456.

Nota

Você deve passar um ID de mensagem de assistente como parent_message_id para garantir que o LLM funcione como esperado. Não é possível passar um ID de mensagem de usuário. Se você tiver perdido a conta do último ID de mensagem, use Criação de thread para listar todas as mensagens no thread.

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

}

Continue usando o ID de mensagem de assistente bem-sucedido mais recente como o parent_message_id em solicitações subsequentes.

Bifurcar uma conversa¶

Você também pode bifurcar a conversa continuando a partir de qualquer mensagem anterior do assistente. Para bifurcar a conversa, passe o ID da mensagem desejada do assistente como parent_message_id em uma nova solicitação. No exemplo a seguir, 3 (user) -> 4 (assistant) e 5 (user) -> 6 (assistant) representam duas bifurcações diferentes da mesma resposta do assistente.

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

Solução de problemas¶

Em casos raros, a API Agent pode falhar ao armazenar a mensagem do assistente. Se os metadados do assistente estiverem ausentes na resposta, ignore a vez com falha e continue a partir da última mensagem de assistente bem-sucedida.

Por exemplo, considere o seguinte thread :

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

Para continuar a conversa, passe o ID da mensagem 2 como parte de uma nova solicitação, pois essa é a última mensagem do assistente bem-sucedida.

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