カテゴリ：: :doc:`/sql-reference/functions-string`（AI 関数）

DATA_AGENT_RUN (SNOWFLAKE.CORTEX)¶

:doc:`Cortex Agent</user-guide/snowflake-cortex/cortex-agents>`を実行し、応答をJSONとして返します。

この関数を使用すると、構造化データと非構造化データの両方を横断的に処理してインサイトを導き出すCortex Agentを実行できます。Cortex Agentは、タスクの計画を立て、必要なツールを使いこなしてそのタスクを実行し、回答をまとめて提示してくれます。

注釈

:code:`SNOWFLAKE.CORTEX.DATA_AGENT_RUN`は、:doc:`Cortex Agents Run API</user-guide/snowflake-cortex/cortex-agents-run>`のユーティリティラッパーです。ほとんどのアプリケーション統合では、Snowflakeは**ストリーミングREST API**を直接呼び出すことを推奨しています。

こちらもご参照ください。: CREATE に AGENT、 SHOW AGENTS、 DESCRIBE AGENT、 DROP AGENT

構文¶

SNOWFLAKE.CORTEX.DATA_AGENT_RUN( '<agent_name>', <request_body> )

引数¶

'agent_name'

実行するエージェントの完全修飾名（:samp:`{database}.{schema}.{agent_name}`の形式）。

request_body

エージェントに送信するJSONリクエスト本文。この値は文字列（たとえば、:code:`$$...$$`リテラル）である必要があります。

リクエスト本文では、以下のフィールドがサポートされています。


フィールド	型	説明
`thread_id`	integer	会話のためのスレッド ID。thread_idを使用する場合、parent_message_idも渡す必要があります。
`parent_message_id`	integer	そのスレッドの親メッセージの ID。これが最初のメッセージである場合、parent_message_idは0である必要があります。
`messages`	Message の配列	リクエストでthread_idとparent_message_idを渡す場合、messagesには会話の現在のユーザーメッセージが含まれます。そうでない場合は、messagesには会話履歴と現在のメッセージが含まれます。messagesには、ユーザークエリとアシスタントの応答の両方が時系列で含まれます。
`stream`	boolean	ストリーミング応答（`テキスト/イベントストリーム`）を返すか、非ストリーミング JSON 応答（`アプリケーション/JSON`）を返すかを指定します。trueの場合、応答はサーバー送信イベントとしてストリーミングされます。falseの場合、応答は JSON として返されます。
`tool_choice`	ToolChoice	対話中にエージェントがどのようにツールを選択し、使用するかを構成します。ツールの使用が自動か、必須か、または特定のツールを使用すべきかを制御します。

例

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

重要

:code:`stream`フィールドは無視されます。常に非ストリーミング応答が返されます。

戻り値¶

エージェントの応答を含むJSON文字列を返します。

アクセス制御の要件¶

エージェントを実行するには、Cortex Agentsと呼び出し対象のエージェントオブジェクトにアクセスできるロールを使用する必要があります。詳細については、アクセス制御の要件をご参照ください。

使用上の注意¶

関数はJSON文字列を返します。この文字列を:doc:`try_parse_json`に渡し、応答をVARIANT値に変換します。

例¶

エージェントを実行し、応答JSONを解析します。

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT',
      $${
        "parent_message_id": 1234,
        "thread_id": 5678,
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS resp;

戻り値のサンプル:

{
  "role": "assistant",
  "content": [
    {
      "thinking": {
        "text": "\n...\n"
      },
      "type": "thinking"
    },
    {
      "tool_use": {
        "input": {
          "...": "..."
        },
        "name": "<tool_name>",
        "tool_use_id": "<tool_use_id>",
        "type": "<tool_type>"
      },
      "type": "tool_use"
    },
    {
      "text": "Based on the data available, there are two main types of products...",
      "type": "text"
    }
  ],
  "metadata": {
    "run_id": "<run_id>"
  }
}