Cortex Agent REST API でスレッドを使用する

このガイドでは、Cortex Agent REST API を使用してスレッド化された会話を作成、継続、管理する方法を説明します。

スレッドを使用するワークフローには次のステップがあります。

  1. 新しいスレッドを作成し、Cortex Agent REST API への agent:run リクエストの一部として使用します。

  2. スレッドのメッセージ IDs を読みます。

  3. スレッドを継続するメッセージを選択します。

新しいスレッドを立ち上げ、Agent Runで使用します。

新しいスレッドを作成し、リクエストの一部として agent:run に渡す必要があります。

  1. スレッドを作成する を使用して新しいスレッドを作成します。

  2. agent:run REST API のいずれかのエンドポイントへのリクエストの一部として、新しく作成されたスレッドの ID を渡します。

  • エージェントオブジェクトを含む agent:run:

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

  • エージェントオブジェクトを含まない agent:run:

    /api/v2/cortex/agent:run
    Copy

リクエストの一部として、次を渡します。

  • parent_message_id は 0 である必要があります。これは、このリクエストがスレッドの開始であることを示します。

  • messages にユーザーメッセージが1件だけあります。

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

返ってきたメッセージ IDs を読む

Agent API は、会話の各メッセージのメタデータイベントをストリームバックします。次の出力は、メタデータの構造を示しています。常にユーザーとアシスタントの両方のメタデータイベントをリッスンします。

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

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

この出力では、メッセージ IDs は、会話中の次の部分に対応しています。

  • 123: 永続化されたユーザーメッセージ ID

  • 456: 永続化されたアシスタントメッセージ ID

これらの IDs を組み合わせると、次のスレッドが形成されます。

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

会話を続ける

会話の次のターンでは、 parent_message_id を最後に成功したアシスタントメッセージ ID にセットし、 messages に新しい値を渡します。この例では、親メッセージ ID は 456 です。

注釈

LLM が期待通りに機能するように、 parent_message_id としてアシスタントメッセージ ID を渡す必要があります。ユーザーメッセージ ID を渡すことはできません。最後のメッセージ ID がわからなくなった場合は、 スレッドを作成する を使ってスレッド内の全メッセージをリストアップしてください。

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

}
Copy

以降のリクエストでは、最新の成功したアシスタントメッセージ ID を parent_message_id として引き続き使用します。

会話を分岐する

以前のアシスタントメッセージから継続して会話を分岐することもできます。会話を分岐するには、新しいリクエストで希望するアシスタントメッセージ ID を parent_message_id として渡します。 以下の例では、 3 (user) -> 4 (assistant) と 5 (user) -> 6 (assistant) は同じアシスタント応答からの2つの異なる分岐を表しています。

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

トラブルシューティング

まれに、Agent API は、アシスタントメッセージの保存に失敗することがあります。アシスタントのメタデータが応答から欠落している場合、失敗したターンを無視し、最後に成功したアシスタントメッセージから続行します。

たとえば、次のスレッドを考慮します。

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

会話を続けるには、メッセージ ID 2を新しいリクエストの一部として渡します。これは、最後に成功したアシスタントメッセージであるためです。

0 -> 1 (user) -> 2 (assistant) -> 5 (user) -> 6 (assistant)
Copy
言語: 日本語