图表内容¶
当 type
为“图表”时:
字段 |
类型 |
描述 |
---|---|---|
|
对象 |
消息的图表内容。 |
|
字符串 |
图表为 Vega-Lite 规格。 |
使用此 API 可简化交互式聊天应用程序的创建。
:code:` POST <account_url>/api/v2/cortex/agent:run`
向请求正文中提供的 Cortex Agents 服务发送用户查询,然后生成响应。
参数 |
描述 |
---|---|
|
(必填)您的 Snowflake 账户 URL。有关查找您的账户 URL 的说明,请参阅 查找账户的组织和账户名称。 |
标头 |
描述 |
---|---|
|
(必需)授权令牌。有关更多信息,请参阅 配置密钥对身份验证。 |
|
(必需)应用程序/json |
请求正文包含模型、响应指令、实验字段、工具、工具资源和消息。
字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
Agent 用于生成响应的模型的名称。有关支持的模型列表,请参阅 支持的模型。 |
|
字符串 |
模型生成响应时遵循的指令。 |
|
对象 |
实验旗标已传递给代理。 |
|
数组 |
代理可用的工具规格数组。 |
|
对象 |
工具所需的资源。 |
|
对象 |
用于选择工具的配置。 |
|
数组 |
对话中的消息数组。 |
response_instruction
字段是一个字符串,用于向模型提供生成响应的指令。
本节详细介绍了支持的工具类型、其配置选项以及如何为每个工具指定必要的资源。
tools
字段包含一系列可用的工具:
字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
工具的类型。类型和名称的组合是唯一的标识符。 |
|
字符串 |
工具名称。类型和名称的组合是唯一的标识符。 |
支持的 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},
...
}
每种工具类型支持以下配置:
cortex_search
¶"SearchName": {
"name": "database.schema.service_name", # Required: The Snowflake search service identifier
"max_results": 5, # Optional: Number of search results to include
"title_column": "title", # Optional: Column to use as document title
"id_column": "id", # Optional: Column to use as document identifier
"filter": { # Optional: Filters to apply to search results
"@eq": {"<column>": "<value>"}
}
}
cortex_analyst_text_to_sql
¶"AnalystName": {
"semantic_model_file": "@database.schema.stage/my_semantic_model.yaml" # Required: Stage path to semantic model file
}
tool_choice
字段配置工具选择行为:
字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
应如何选择工具。 有效值: |
|
数组 |
要使用的可选工具名称数组。仅在 |
messages
数组包含用户和助理之间的对话历史记录:
字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
消息发送者的角色。 有效值:
|
|
数组 |
组成消息的内容元素数组。 |
每条消息的 content
数组可以包含多个不同类型的内容元素:
字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
内容类型。 有效值:
|
当 type
为 "text"
时:
字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
消息的文本内容。 |
当 type
为“图表”时:
字段 |
类型 |
描述 |
---|---|---|
|
对象 |
消息的图表内容。 |
|
字符串 |
图表为 Vega-Lite 规格。 |
当 type
为“tool_use”时:
字段 |
类型 |
描述 |
---|---|---|
|
对象 |
工具使用请求详细信息的容器。 |
|
字符串 |
此工具使用请求的唯一标识符。 |
|
字符串 |
要执行的工具的名称。必须与工具数组中的工具名称匹配。 |
|
对象 |
输入工具执行参数。 |
当 type
为 "tool_results"
时:
字段 |
类型 |
描述 |
---|---|---|
|
对象 |
工具执行结果和元数据的容器。 |
|
字符串 |
参照生成这些结果的 tool_use_id。 |
|
字符串 |
已执行的工具的名称。必须与工具数组中的工具名称匹配。 |
|
字符串 |
工具执行状态。 值:
|
|
数组 |
工具执行生成的内容元素的数组。 |
tool_results.content
数组可以包含以下类型的元素:
类型 |
字段 |
描述 |
---|---|---|
|
type: "text" text: string |
工具返回的纯文本内容。 |
|
type: "json" json: object |
工具返回的结构化 JSON 数据。 |
{
"type": "text",
"text": "Show me sales by region for Q1 2024"
}
{
"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\"}",
}
}
{
"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",
"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"
}
}
]
}
}
{
"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"
}
}
]
}
}
]
}
]
}
进行流式传输时,各个事件通常以服务器发送的事件 (SSE) 格式到达,主要模式如下:
部分输出的增量 message.delta
事件
error
事件(如果出了问题)。
message.delta
事件¶字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
部分消息数据的 |
|
对象 |
包含增量更新数据。 |
|
字符串 |
消息的唯一标识符。 |
|
字符串 |
|
|
数组 |
块或部分消息段的列表。 |
|
整数 |
此块在当前消息中的位置。 |
|
字符串 |
内容类型。有效值:
|
|
字符串 |
如果 |
|
对象 |
如果 |
|
字符串 |
图表为 Vega-Lite 规格。 |
|
对象 |
如果 |
|
字符串 |
工具调用的唯一标识符。 |
|
字符串 |
正在调用的工具的名称。 |
|
对象 |
工具的 JSON 有效负载。 |
|
对象 |
如果 |
|
字符串 |
工具输出的唯一标识符。 |
|
字符串 |
工具执行状态。有效值:
|
|
数组 |
描述工具的返回数据的项目列表。 |
|
字符串 |
工具返回的内容类型。有效值:
|
|
对象 |
如果 |
|
字符串 |
如果 |
字段 |
类型 |
描述 |
---|---|---|
|
字符串 |
错误事件的 |
|
对象 |
包含错误详细信息。 |
|
字符串 |
Snowflake 错误代码。例如 |
|
字符串 |
对所发生错误的描述。例如 |
{
"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"
}
}
}
]
}
]
}
{
"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"
}
}
]
}
}