类别：: :doc:`/sql-reference/functions-string`（AI 函数）

DATA_AGENT_RUN (SNOWFLAKE.CORTEX)¶

运行 Cortex Agent 并将响应返回为 JSON。

您可以使用此函数运行 Cortex Agent，该代理可以跨结构化和非结构化数据源进行编排以提供见解。这包括规划任务、使用工具执行这些任务以及生成响应。

备注

SNOWFLAKE.CORTEX.DATA_AGENT_RUN 是针对 Cortex Agents Run API 的实用程序包装器。对于大多数应用程序集成，Snowflake 建议直接调用 流式 REST API。

另请参阅：: CREATE AGENT、SHOW AGENTS、DESCRIBE AGENT、DROP AGENT

语法¶

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

实参¶

'agent_name'

要运行的代理的完全限定名称，格式为 database.schema.agent_name。

request_body

要发送给代理的 JSON 请求正文。此值必须是字符串（例如，$$...$$ 字面量）。

请求正文支持以下字段：


字段	类型	描述
`type`	整数	对话的线程 ID。如果使用了 thread_id，则还必须传递 parent_message_id。
`data.message`	整数	线程中的父消息的 ID。如果这是第一条消息，parent_message_id 应为 0。
`messages`	Message 的数组	如果在请求中传递了 thread_id 和 parent_message_id，则消息将包含对话中的当前用户消息。否则，消息包括对话历史记录和当前消息。消息包含按时间顺序排列的用户查询和助手响应。
`stream`	布尔	指定返回流式响应 (`text/event-stream`) 还是非流式 JSON 响应 (`application/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"
    ]
  }
}

重要

stream 字段将被忽略。系统始终返回非流式响应。

返回¶

返回包含代理响应的 JSON 字符串。

访问控制要求¶

要运行代理，您必须使用具备 Cortex Agent 访问权限以及您正在调用的代理对象的角色。访问控制要求是 Web 令牌 ()、令牌或编程访问令牌。有关详细信息，请参阅访问控制要求。

使用说明¶

该函数会返回 JSON 字符串。请将此字符串传递给 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>"
  }
}