Cortex Agents REST API¶

使用此 API 可简化交互式聊天应用程序的创建。

运行代理¶

:code:` POST <account_url>/api/v2/cortex/agent:run`

向请求正文中提供的 Cortex Agents 服务发送用户查询，然后返回其响应。

请求¶

路径参数¶

参数	描述
`account_url`	（必填）您的 Snowflake 账户 URL。有关查找您的账户 URL 的说明，请参阅查找账户的组织和账户名称。

请求标头¶

标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅配置 REST API 身份验证。
`Content-Type`	（必需）应用程序/json

请求正文¶

请求正文包含模型、响应指令、实验字段、工具、工具资源和消息。

字段	类型	描述
`model`	字符串	Agent 用于生成响应的模型的名称。有关支持的模型列表，请参阅支持的模型。
`response_instruction`	字符串	模型生成响应时遵循的指令。
`experimental`	对象	实验旗标已传递给代理。
`tools`	数组	代理可用的工具规格数组。
`tool_resources`	对象	工具所需的资源。
`tool_choice`	对象	用于选择工具的配置。
`messages`	数组	对话中的消息数组。

响应指令¶

response_instruction 字段是一个字符串，用于向模型提供生成响应的指令。

工具配置¶

本节详细介绍了支持的工具类型、其配置选项以及如何为每个工具指定必要的资源。

工具规格¶

tools 字段包含一系列可用的工具：

字段	类型	描述
`tool_spec.type`	字符串	工具的类型。类型和名称的组合是唯一的标识符。
`tool_spec.name`	字符串	工具名称。类型和名称的组合是唯一的标识符。

支持的 tool_spec.type 值包括以下内容：

cortex_search：用于 Cortex 搜索功能
cortex_analyst_text_to_sql：用于 Cortex Analyst 文本转 SQL
sql_exec：用于执行 SQL 查询。您负责执行 SQL 查询并以工具结果的形式提供结果。有关更多详细信息，请参阅下面的示例答案请求。
data_to_chart：用于生成图表

工具资源¶

tool_resources 对象为每个工具提供配置对象。

tool_resources: {
    "toolName1": {configuration object for toolName1},
    "toolName2": {configuration object for toolName2},
    // ...
}

Copy

每种工具类型的配置如下所述。

cortex_search

SearchName 对象包含 Cortex Search 工具的配置。

"SearchName": {
    // Required: The Snowflake search service identifier
    "name": "database.schema.service_name",
    // Optional: Number of search results to include
    "max_results": 5,
    // Optional: Column to use as document title
    "title_column": "title",
    // Optional: Column to use as document identifier
    "id_column": "id",
     // Optional: Filters to apply to search results (such as @eq for equality)
    "filter": {
      "@eq": {"<column>": "<value>"}
    }
}

Copy

cortex_analyst_text_to_sql

AnalystName 对象包含 Cortex Analyst 文本转 SQL 工具的配置。配置必须包括要使用的语义模型或视图。例如：

"AnalystName": {
    // Stage path to semantic model file in `semantic_model_file`
    "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml"
}

Copy

或使用语义视图概述

"AnalystName": {
    // Fully qualified name of the semantic view object
    "semantic_view": "database.schema.semantic_view"
}

Copy

工具选择¶

tool_choice 字段配置工具选择行为。

字段	类型	描述
`type`	字符串	应如何选择工具。有效值： :code:`"auto"``（默认值） :code:`"required"`（使用至少一个工具） :code:`"tool"`（使用指定的工具）
`name`	数组	要使用的可选工具名称数组。仅在 `type = "tool"` 时有效。

字段

类型

描述

type

字符串

应如何选择工具。

有效值：

:code:`"auto"``（默认值）
:code:`"required"`（使用至少一个工具）
:code:`"tool"`（使用指定的工具）

name

数组

要使用的可选工具名称数组。仅在 type = "tool" 时有效。

消息¶

messages 数组包含用户和助理之间的对话历史记录：

字段	类型	描述
`messages[].role`	字符串	消息发送者的角色。有效值： `"system"` `"user"` `"assistant"`
`messages[].content`	数组	组成消息的内容元素数组。

字段

类型

描述

messages[].role

字符串

消息发送者的角色。

有效值：

"system"
"user"
"assistant"

messages[].content

数组

组成消息的内容元素数组。

消息内容结构¶

每条消息的 content 数组可以包含多个不同类型的内容元素。

字段	类型	描述
`messages[].content[].type`	字符串	内容类型。有效值： `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`

字段

类型

描述

messages[].content[].type

字符串

内容类型。

有效值：

"text"
"chart"
"table"
"tool_use"
"tool_results"

文本内容

当 type 为 "text" 时：

字段	类型	描述
`messages[].content[].text`	字符串	消息的文本内容。

示例：

{
  "type": "text",
  "text": "Show me sales by region for Q1 2024"
}

Copy

图表内容

当 type 为“图表”时：

字段	类型	描述
`messages[].content[].chart`	对象	消息的图表内容。
`messages[].content[].chart.chart_spec`	字符串	图表为 Vega-Lite 规格。

示例：

{
  "type": "chart",
  "chart": {
    "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{\"values\":[{\"REGION\":\"NORTH_AMERICA\",\"SUM(SALES)\":\"2000.00\"},{\"REGION\":\"EUROPE\",\"SUM(SALES)\":\"1700.00\"},{\"REGION\":\"SAUTH_AMERICA\",\"SUM(SALES)\":\"1500.00\"}]},\"encoding\":{\"x\":{\"field\":\"REGION\",\"sort\":null,\"type\":\"nominal\"},\"y\":{\"field\":\"SUM(SALES)\",\"sort\":null,\"type\":\"quantitative\"}},\"mark\":\"bar\"}",
  }
}

Copy

文本内容

当 type 为“表”时：

字段	类型	描述
`messages[].content[].table`	对象	消息的表内容。
`messages[].content[].table.query_id`	字符串	已执行的查询的 ID。

示例：

{
  "type": "table",
  "table": {
    "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
  }
}

Copy

工具使用

当 type 为“tool_use”时：

字段	类型	描述
`messages[].content[].tool_use`	对象	工具使用请求详细信息的容器。
`messages[].content[].tool_use.tool_use_id`	字符串	此工具使用请求的唯一标识符。
`messages[].content[].tool_use.name`	字符串	要执行的工具的名称。必须与工具数组中的工具名称匹配。
`messages[].content[].tool_use.input`	对象	输入工具执行参数。

示例：

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "tu_01",
    "name": "Analyst1",
    "input": {
      "query": "Show me sales by region for Q1 2024"
    }
  }
}

Copy

工具结果

当 type 为 "tool_results" 时：

字段

类型

描述

messages[].content[].tool_results

对象

工具执行结果和元数据的容器。

messages[].content[].tool_results.tool_use_id

字符串

参照生成这些结果的 tool_use_id。

messages[].content[].tool_results.name

字符串

已执行的工具的名称。必须与工具数组中的工具名称匹配。

messages[].content[].tool_results.status

字符串

工具执行状态。

有效值：

"success"
"error"

messages[].content[].tool_results.content

数组

工具执行生成的内容元素的数组。

可以包含以下类型的元素：

类型	字段	描述
`text`	`type: "text"` `text: string`	工具返回的纯文本内容。
`json`	`type: "json"` `json: object`	工具返回的结构化 JSON 数据。

示例：

{
  "type": "tool_results",
  "tool_results": {
    "tool_use_id": "tu_01",
    "status": "success",
    "content": [
      {
        "type": "json",
        "json": {
          "sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
          "text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
        }
      }
    ]
  }
}

Copy

完整消息示例¶

此示例显示一条包含用户查询（role 为 user）和响应（role 为 assistant）的完整消息。响应包括名为 Analyst1 的工具的工具使用事件和同一工具的工具结果事件。

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Show me sales by region for Q1 2024"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tu_01",
            "name": "Analyst1",
            "input": {
              "query": "Show me sales by region for Q1 2024"
            }
          }
        },
        {
          "type": "tool_results",
          "tool_results": {
            "tool_use_id": "tu_01",
            "name": "Analyst1",
            "status": "success",
            "content": [
              {
                "type": "json",
                "json": {
                  "sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
                  "text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Copy

响应¶

进行流式传输时，各个事件以服务器发送的事件 (SSE) 格式到达，主要模式如下：

输出块的增量 message.delta 事件
error 事件（如果出了问题）。

`message.delta` 事件¶

字段	类型	描述
`event`	字符串	部分消息数据的 `message.delta`。
`data`	对象	包含增量更新数据。
`data.id`	字符串	消息的唯一标识符。
`data.object`	字符串	`message.delta` 或类似的描述符。
`data.delta.content`	数组	块或部分消息段的列表。
`data.delta.content[].index`	整数	此块在当前消息中的位置。
`data.delta.content[].type`	字符串	内容类型。有效值： `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`
`data.delta.content[].text`	字符串	如果 `type = "text"`，则为部分文本字符串。
`data.delta.content[].chart`	对象	如果 `type = "chart"`，则为消息的图表内容。
`data.delta.content[].chart.chart_spec`	字符串	图表为 Vega-Lite 规格。
`data.delta.content[].table`	对象	如果为 `type = "table"`，则为消息的表内容。
`data.delta.content[].table.query_id`	字符串	已执行的查询的 ID。
`data.delta.content[].tool_use`	对象	如果 `type = "tool_use"`，表示正在进行工具调用。包含 tool_use_id、名称、输入。
`data.delta.content[].tool_use.tool_use_id`	字符串	工具调用的唯一标识符。
`data.delta.content[].tool_use.name`	字符串	正在调用的工具的名称。
`data.delta.content[].tool_use.input`	对象	工具的 JSON 有效负载。
`data.delta.content[].tool_results`	对象	如果 `type = "tool_results"`，则包含工具输出。
`data.delta.content[].tool_results.tool_use_id`	字符串	工具输出的唯一标识符。
`data.delta.content[].tool_results.status`	字符串	工具执行状态。有效值： `"success"` `"error"`
`data.delta.content[].tool_results.content`	数组	描述工具的返回数据的项目列表。
`data.delta.content[].tool_results.content[].type`	字符串	工具返回的内容类型。有效值： `"text/csv"` `"application/json"` `"application/pdf"`
`data.delta.content[].tool_results.content[].json`	对象	如果 `type = "application/json"`，工具返回的 JSON 数据。
`data.delta.content[].tool_results.content[].text`	字符串	如果 `type = "text"`，工具返回的文本数据。

`error` 事件¶

字段	类型	描述
`event`	字符串	错误事件的 `error`。
`data`	对象	包含错误详细信息。
`data.code`	字符串	Snowflake 错误代码。例如 `"399505"`。
`data.message`	字符串	对所发生错误的描述。例如 `"Internal server error"`。

示例对话流¶

本部分显示用户和助手之间使用 Cortex Agents REST API 的示例对话流。

请求示例¶

{
  "model": "llama3.3-70b",
  "response_instruction": "You will always maintain a friendly tone and provide concise response.",
  "experimental": {},
  "tools": [
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst1"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst2"
      }
    },
    {
      "tool_spec": {
        "type": "sql_exec",
        "name": "sql_execution_tool"
      }
    },
    {
      "tool_spec": {
        "type": "data_to_chart",
        "name": "data_to_chart"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_search",
        "name": "Search1"
      }
    }
  ],
  "tool_resources": {
    "Analyst1": { "semantic_model_file": "stage1"},
    "Analyst2": { "semantic_model_file": "stage2"},
    "Search1": {
      "name": "db.schema.service_name",
      "filter": {"@eq": {"region": "North America"} }
    }
  },
  "tool_choice": {
    "type": "auto"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What are the top three customers by revenue?"
        }
      ]
    }
  ]
}

Copy

响应示例¶

{
  "id": "msg_001",
  "object": "message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "tool_use",
        "tool_use": {
          "tool_use_id": "toolu_XXXXXX",
          "name": "analyst1",
          "input": {
            "messages": [
              "role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
            ],
            "model": "snowflake-hosted-semantic",
            "experimental": ""
          }
        }
      },
      {
        "index": 0,
        "type": "tool_results",
        "tool_results": {
          "tool_use_id": "toolu_XXXXXX",
          "content": [
            {
              "type": "json",
              "json": {
                "suggestions": [],
                "sql": "WITH __customers AS (\n  SELECT\n    customer_id,\n    revenue\n  FROM user_database.user_schema.user_table\n)\nSELECT\n  customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3\n -- Generated by Cortex Analyst\n;",
                "text": "This is our interpretation of your question:\n\n__What are the top three customers by revenue?\n\n"
              }
            }
          ],
          "status": "success"
        }
      },
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_002",
            "name": "sql_execution_tool",
            "input": {
              "sql": "WITH __customers AS (SELECT customer_id, revenue FROM user_database.user_schema.user_table) SELECT customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3"
            }
          }
        }
    ]
  }
}

Copy

示例答案请求¶

Cortex 代理可以根据已执行的 SQL 查询生成文本和图表答案。以下示例显示如何使用 Cortex Agent API 生成此类答案。

为了获得答案，客户向 Cortex Agent API 提出后续请求，并在客户端执行 SQL 的 query_id。最新响应消息中 sql_exec 工具类型的 tool_use 事件中提供要执行的 SQL。

请求必须使用 cortex_analyst_text_to_sql 和 sql_exec 工具来获得文本答案，而且还必须使用 data_to_chart 工具来获得图表答案。只有当代理认为图表是呈现答案的好方法时，才会返回图表。

备注

对于超过 4000 个单元格的结果集，将返回 table 响应，而不是 text 和 chart 答案。

{
  "model": "llama3.3-70b",
  "response_instruction": "You will always maintain a friendly tone and provide concise response.",
  "experimental": {},
  "tools": [
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst1"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst2"
      }
    },
    {
      "tool_spec": {
        "type": "sql_exec",
        "name": "sql_execution_tool"
      }
    },
    {
      "tool_spec": {
        "type": "data_to_chart",
        "name": "data_to_chart"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_search",
        "name": "Search1"
      }
    }
  ],
  "tool_resources": {
    "Analyst1": { "semantic_model_file": "stage1"},
    "Analyst2": { "semantic_model_file": "stage2"},
    "Search1": {
      "name": "db.schema.service_name",
      "filter": {"@eq": {"region": "North America"} }
    }
  },
  "tool_choice": {
    "type": "auto"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What are the top three customers by revenue?"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_001",
            "name": "Analyst1",
            "input": {
              "messages": [
                "role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
              ],
              "model": "snowflake-hosted-semantic",
            }
          }
        },
        {
          "type": "tool_results",
          "tool_results": {
            "status": "success",
            "tool_use_id": "tool_001",
            "content": [
              {
                "type": "json",
                "json": {
                  "sql": "select * from table",
                  "text": "This is our interpretation of your question: What are the top three customers by revenue? \n\n"
                }
              }
            ]
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
      {
        "type": "tool_results",
        "tool_results": {
          "tool_use_id": "tool_001", // must match the previous tool use id sent back from the "assistant" role
          "name": "sql_execution_tool", // must match the name of the sql_exec tool previously sent in the request
          "content": [{
            "type": "json",
            "json": {
              "query_id": "01bcfcde-0100-0001-0000-000000102549"
            }
          }]
    }
  ]
}

Copy

示例答案响应¶

{
  "id": "msg_001",
  "object": "message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "text",
        "text": "This is a textual answer to your question"
      },
      {
        "index": 0,
        "type": "chart",
        "chart": {
          "chart_spec": "{\"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\", \"title\": \"Example chart\", \"mark\": \"bar\", \"encoding\": {\"x\": {\"field\": \"column_x\", \"type\": \"nominal\", \"sort\": null}, \"y\": {\"field\": \"column_y\", \"type\": \"quantitative\"}}, \"data\": {\"values\": [{\"column_x\": \"A\", \"column_y\": \"1\"}, {\"column_x\": \"A\", \"column_y\": \"1\"}]}}"
        }
      }
    ]
  }
}

Copy

Cortex 代理的局限性¶

由于 Streamlit in Snowflake (SiS) 应用程序在所有者权限下运行，因此不支持在 SiS 应用程序内执行 SQL 语句。
不支持 Azure OpenAI 模型。

Cortex Agents REST API¶

运行代理¶

请求¶

路径参数¶

请求标头¶

请求正文¶

响应指令¶

工具配置¶

工具规格¶

工具资源¶

工具选择¶

消息¶

消息内容结构¶

完整消息示例¶

响应¶

message.delta 事件¶

error 事件¶

示例对话流¶

请求示例¶

响应示例¶

示例答案请求¶

示例答案响应¶

Cortex 代理的局限性¶

`message.delta` 事件¶

`error` 事件¶