AGENT_RUN (SNOWFLAKE.CORTEX)¶

语法¶

SNOWFLAKE.CORTEX.AGENT_RUN( <request_body> )

实参¶

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	配置代理在交互过程中应如何选择和使用工具。控制工具的使用是自动的、必需的，还是应使用特定工具。
models	ModelConfig	代理的模型配置。包括编排模型（例如 claude-4-sonnet）。如果未提供，则自动选择模型。目前仅适用于 编排 步骤。
instructions	AgentInstructions	代理的行为指令，包括响应、编排、系统和示例问题。
orchestration	OrchestrationConfig	编排配置，包括预算约束（例如，秒数、令牌）。
tools	Tool 的数组	代理可使用的工具列表。每个工具包含一个 tool_spec，其中包括类型、名称、描述和输入架构。工具可能在 tool_resources 中有相应的配置。
tool_resources	ToolResource 的地图	对工具数组中每个引用工具的配置。密钥必须与相应工具的名称匹配。

See moreShow less

Expand

示例

CopyExpand

{
  "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"
    ]
  },
  "models": {
    "orchestration": "claude-4-sonnet"
  },
  "instructions": {
    "response": "You will respond in a friendly but concise manner",
    "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
    "system": "You are a friendly agent ..."
  },
  "orchestration": {
    "budget": {
      "seconds": 30,
      "tokens": 16000
    }
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "get_revenue",
        "description": "Fetch the delivery revenue for a location.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
  "tool_resources": {
    "get_revenue": {
      "type": "function",
      "execution_environment": {
        "type": "warehouse",
        "warehouse": "MY_WH"
      },
      "identifier": "DB.SCHEMA.UDF"
    }
  }
}

Show lessSee more

Scroll to top

返回¶

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

访问控制要求¶

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

使用说明¶

• 该函数会返回 JSON 字符串。请将此字符串传递给 TRY_PARSE_JSON，以将响应转换为 VARIANT 值。

• 与 DATA_AGENT_RUN (SNOWFLAKE.CORTEX) 不同，此函数不需要您先创建代理对象。相反，您直接在请求正文中提供配置。

示例¶

运行代理并解析响应 JSON：

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.AGENT_RUN(
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "What is the total revenue for 2025?"
              }
            ]
          }
        ],
        "models": {
          "orchestration": "claude-4-sonnet"
        }
      }$$
    )
  ) AS resp;

返回值示例：

{
  "content": [
    {
      "text": "The total revenue for 2025 was $100,000.",
      "type": "text"
    }
  ],
  "metadata": {
    "usage": {
      "tokens_consumed": [
        {
          "context_window": 200000,
          "input_tokens": {
            "cache_read": 0,
            "cache_write": 0,
            "total": 67,
            "uncached": 67
          },
          "model_name": "claude-4-sonnet",
          "output_tokens": {
            "total": 38
          }
        }
      ]
    }
  },
  "role": "assistant"
}