Verwenden von Threads mit der Cortex Agent REST API

Diese Anleitung erklärt, wie Sie mit der Cortex Agent REST API Thread-Konversationen erstellen, fortsetzen und verwalten.

Der Workflow für die Verwendung von Threads umfasst die folgenden Schritte:

  1. Erstellen Sie einen neuen Thread, und verwenden Sie ihn als Teil einer agent:run-Anfrage an die Cortex Agent REST API.

  2. Lesen Sie die Nachrichten-IDs für den Thread.

  3. Wählen Sie eine Nachricht aus, um den Thread von da aus fortzusetzen.

Starten Sie einen neuen Thread, und verwenden Sie ihn mit Agent Run

Sie müssen einen neuen Thread erstellen und ihn dann als Teil einer Anforderung an agent:run übergeben.

  1. Erstellen Sie einen neuen Thread mit Thread erstellen.

  2. Übergeben Sie die ID des neu erstellten Threads als Teil einer Anforderung an einen der agent:run REST API-Endpunkte

  • agent:run mit Agentenobjekt:

    /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run
    Copy

  • agent:run ohne Agentenobjekt:

    /api/v2/cortex/agent:run
    Copy

Übergeben Sie als Teil der Anforderung Folgendes:

  • parent_message_id muss 0 sein. Dies zeigt an, dass diese Anfrage der Anfang des Threads ist.

  • Genau eine Benutzernachricht in 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?"
        }
      ]
    }
  ],
}
Copy

Lesen der zurückgegebenen Nachrichten-IDs

Die Agent API streamt Metadaten-Ereignisse für jede Nachricht in der Konversation zurück. Die folgende Ausgabe zeigt die Struktur der Metadaten. Achten Sie immer auf Metadatenereignisse von Benutzern und Assistenten.

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

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

In dieser Ausgabe entsprechen die Nachrichten-IDs den folgenden Punkten in der Konversation:

  • 123: die persistente Benutzernachricht-ID

  • 456: die persistente Assistentennachricht-ID

Zusammen bilden diese IDs den folgenden Thread:

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

Konversation fortsetzen

Für die nächste Runde in der Konversation setzen Sie parent_message_id auf die letzte erfolgreiche Assistentennachricht-ID und übergeben neue Werte an messages. In diesem Beispiel ist die übergeordnete Nachrichten-ID 456.

Bemerkung

Sie müssen eine Assistentennachricht-ID als parent_message_id übergeben, um sicherzustellen, dass das LLM wie erwartet funktioniert. Sie können keine Benutzernachricht-ID übergeben. Wenn Sie den Überblick über die letzte Nachrichten-ID verloren haben, verwenden Sie Thread erstellen, um alle Meldungen im Thread aufzulisten.

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

}
Copy

Verwenden Sie weiterhin die letzte erfolgreiche Assistentennachricht-ID als parent_message_id in nachfolgenden Anfragen.

Eine Konversation aufspalten

Sie können die Konversation auch aufspalten, indem Sie von einer früheren Assistentennachricht fortfahren. Um die Konversation aufzuspalten, übergeben Sie die gewünschte Assistentennachricht-ID als parent_message_id in einer neuen Anfrage. Im folgenden Beispiel repräsentieren 3 (user) -> 4 (assistant) und 5 (user) -> 6 (assistant) zwei verschiedene Abspaltungen aus derselben Assistentenantwort.

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

Problembehandlung

In seltenen Fällen kann die Agenten-API die Assistentennachricht möglicherweise nicht speichern. Wenn Assistenten-Metadaten in der Antwort fehlen, ignorieren Sie die fehlgeschlagene Runde und fahren Sie mit der letzten erfolgreichen Assistentennachricht fort.

Betrachten Sie beispielsweise die folgende Tabelle:

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

Um die Konversation fortzusetzen, übergeben Sie die Nachrichten-ID 2 als Teil einer neuen Anfrage, da dies die letzte erfolgreiche Assistentennachricht ist.

0 -> 1 (user) -> 2 (assistant) -> 5 (user) -> 6 (assistant)
Copy
Sprache: Deutsch