Utiliser des threads avec l’API REST des Agents Cortex¶

Ce guide explique comment créer, poursuivre et gérer des conversations en fil de discussion à l’aide de l’API REST des Agents Cortex.

Le flux d’utilisation des threads comprend les étapes suivantes :

Créer un nouveau thread et l’utiliser dans le cadre d’une requête agent:run à l’API REST des Agents Cortex.
Lire les IDs de message pour le thread.
Choisir un message pour poursuivre le thread.

Démarrer un nouveau thread et l’utiliser avec l’exécution d’agent¶

Vous devez créer un nouveau thread, puis le transmettre dans le cadre d’une requête à agent:run.

Créez un nouveau thread en utilisant Créer un thread.
Transmettez l’ID du thread nouvellement créé dans le cadre d’une requête vers l’un des points de terminaison agent:run de l’API REST.

agent:run avec un objet Agent :
/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run
Copy
agent:run sans objet Agent :
/api/v2/cortex/agent:run
Copy
Dans le cadre de la requête, transmettez ce qui suit :

parent_message_id doit être 0. Cela indique que cette requête est le début du thread.

Exactement un message utilisateur dans 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

Lire les IDs de message renvoyées¶

L’API Agent renvoie les événements de métadonnées pour chaque message de la conversation. La sortie suivante montre la structure des métadonnées. Soyez toujours à l’écoute des événements de métadonnées de l’utilisateur et de l’assistant.

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

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

Dans cette sortie, les IDs de message correspondent aux éléments suivants dans la conversation :

123 : l’ID de message utilisateur persistant
456 : l’ID de message assistant persistant

Ensemble, ces IDs forment le thread suivant :

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

Copy

Poursuivre la conversation¶

Pour la prochaine étape de la conversation, définissez parent_message_id à l’ID du dernier message assistant réussi et transmettez de nouvelles valeurs dans messages. Dans cet exemple, l’ID de message parent est 456.

Note

Vous devez transmettre un ID de message assistant comme parent_message_id pour garantir les fonctions LLM comme prévu. Vous ne pouvez pas transmettre un ID de message utilisateur. Si vous avez perdu la trace de l’ID du dernier message, utilisez Créer un thread pour lister tous les messages du thread.

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

}

Copy

Continuer d’utiliser l’ID du dernier message assistant réussi comme parent_message_id dans les demandes suivantes.

Diverger une conversation¶

Vous pouvez également diverger la conversation en poursuivant à partir de n’importe quel message assistant précédent. Pour diverger la conversation, transmettez l’ID de message assistant souhaité comme parent_message_id dans une nouvelle requête. Dans l’exemple suivant, 3 (user) -> 4 (assistant) et 5 (user) -> 6 (assistant) représentent deux forks différents de la même réponse assistant.

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

Copy

Résolution des problèmes¶

Dans de rares cas, l’API Agent peut ne pas réussir à stocker le message assistant. Si les métadonnées de l’assistant sont absentes de la réponse, ignorez le tour ayant échoué et continuez à partir du dernier message assistant réussi.

Par exemple, considérez le thread suivant :

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

Copy

Pour poursuivre la conversation, transmettez l’ID 2 de message dans le cadre d’une nouvelle requête, car il s’agit du dernier message assistant réussi.

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

Copy