Cortex Agents REST API

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

运行代理

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

向请求正文中提供的 Cortex Agents 服务发送用户查询,然后生成响应。

请求

路径参数

参数

描述

account_url

(必填)您的 Snowflake 账户 URL。有关查找您的账户 URL 的说明,请参阅 查找账户的组织和账户名称

请求标头

标头

描述

Authorization

(必需)授权令牌。有关更多信息,请参阅 配置密钥对身份验证

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 查询

  • data_to_chart:用于生成图表

工具资源

tool_resources 字段是将工具名称映射到其配置对象的对象:

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

每种工具类型支持以下配置:

cortex_analyst_text_to_sql
"AnalystName": {
    "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml"  # Required: Stage path to semantic model file
}
Copy

工具选择

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

字段

类型

描述

type

字符串

应如何选择工具。

有效值:

  • :code:`"auto"``(默认值)

  • :code:`"required"`(使用 ≥1 的工具)

  • :code:`"tool"`(使用指定的工具)。

name

数组

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

消息

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

字段

类型

描述

messages[].role

字符串

消息发送者的角色。

有效值:

  • "system"

  • "user"

  • "assistant"

messages[].content

数组

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

消息内容结构

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

字段

类型

描述

messages[].content[].type

字符串

内容类型。

有效值:

  • "text"

  • "chart"

  • "tool_use"

  • "tool_results"

文本内容

type"text" 时:

字段

类型

描述

messages[].content[].text

字符串

消息的文本内容。

图表内容

type 为“图表”时:

字段

类型

描述

messages[].content[].chart

对象

消息的图表内容。

messages[].content[].chart.chart_spec

字符串

图表为 Vega-Lite 规格。

工具使用

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_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

数组

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

工具结果内容类型

tool_results.content 数组可以包含以下类型的元素:

类型

字段

描述

text

type: "text"
text: string

工具返回的纯文本内容。

json

type: "json"
json: object

工具返回的结构化 JSON 数据。

示例

文本内容示例
{
  "type": "text",
  "text": "Show me sales by region for Q1 2024"
}
Copy
图表内容示例
{
  "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": "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",
  "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
完整消息示例
{
  "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"

  • "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[].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",工具返回的文本数据。

错误事件

字段

类型

描述

event

字符串

错误事件的 error

data

对象

包含错误详细信息。

data.code

字符串

Snowflake 错误代码。例如 "399505"

data.message

字符串

对所发生错误的描述。例如 "Internal server error"

请求示例

{
  "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_exec"
      }
    },
    {
      "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"
                }
              }
            ]
          }
        },
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_002",
            "name": "sql_exec",
            "input": {
              "sql": "select * from table"
            }
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_results",
          "tool_results": {
            "tool_use_id": "tool_002",
            "result": {
              "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
            }
          }
        }
      ]
    }
  ]
}
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:\"count book id\"}}"
            ],
            "model": "snowflake-hosted-semantic",
            "experimental": ""
          }
        }
      },
      {
        "index": 0,
        "type": "tool_results",
        "tool_results": {
          "tool_use_id": "toolu_XXXXXX",
          "content": [
            {
              "type": "json",
              "json": {
                "suggestions": [],
                "sql": "WITH __books AS (\n  SELECT\n    book_id\n  FROM user_database.user_schema.user_table\n)\nSELECT\n  COUNT(book_id) AS book_count\nFROM __books\n -- Generated by Cortex Analyst\n;",
                "text": "This is our interpretation of your question:\n\n__Count the total number of books__ \n\n"
              }
            }
          ],
          "status": "success"
        }
      }
    ]
  }
}
Copy
语言: 中文