Cortex Agents REST API¶
Use this API to simplify the creation of an interactive chat application.
Run agent¶
POST <account_url>/api/v2/cortex/agent:run
Sends a user query to the Cortex Agents service provided in the request body and returns its response.
Request¶
Path parameters¶
Parameter |
Description |
---|---|
|
(Required) Your Snowflake Account URL. For instructions on finding your account URL, see Finding the organization and account name for an account. |
Request headers¶
Header |
Description |
---|---|
|
(Required) Authorization token. For more information, see Configure Key-Pair Authentication. |
|
(Required) application/json |
Request body¶
The request body contains the model, response instruction, experimental fields, tools, tool resources, and messages.
Field |
Type |
Description |
---|---|---|
|
string |
The name of the model used by the Agent to generate a response. For a list of supported models, see Supported models. |
|
string |
The instructions the model follows when it generates the response. |
|
object |
Experimental flags passed to the agent. |
|
array |
An array of tool specifications available to the agent. |
|
object |
Resources required by the tools. |
|
object |
The configuration used to select the tool. |
|
array |
Array of messages in the conversation. |
Response instruction¶
The response_instruction
field is a string that provides instructions to the model for response generation.
Tool configuration¶
This section details the supported tool types, their configuration options, and how to specify the necessary resources for each tool.
Tool specifications¶
The tools
field contains an array of available tools:
Field |
Type |
Description |
---|---|---|
|
string |
The type of tool. A combination of type and name is a unique identifier. |
|
string |
The name of the tool. A combination of type and name is a unique identifier. |
Supported tool_spec.type
values include the following:
cortex_search
: Used for Cortex search functionalitycortex_analyst_text_to_sql
: Used for Cortex Analyst text-to-SQLsql_exec
: Used for executing SQL queries. You are responsible for executing the SQL query and providing the results as tool results. For more details, see Sample answers request below.data_to_chart
: Used for generating charts
Tool resources¶
The tool_resources
object provides configuration objects for each tool.
tool_resources: {
"toolName1": {configuration object for toolName1},
"toolName2": {configuration object for toolName2},
// ...
}
The configuration for each tool type is described below.
cortex_search
The
SearchName
object contains the configuration for a Cortex Search tool."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>"} } }
cortex_analyst_text_to_sql
The
AnalystName
object contains the configuration for a Cortex Analyst text-to-SQL tool."AnalystName": { // Required: Stage path to semantic model file "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml" }
Tool choice¶
The tool_choice
field configures tool selection behavior.
Field |
Type |
Description |
---|---|---|
|
string |
How tools should be selected. Valid values:
|
|
array |
Optional array of tool names to use. Only valid when |
Messages¶
The messages
array contains the conversation history between the user and assistant:
Field |
Type |
Description |
---|---|---|
|
string |
The role of the message sender. Valid values:
|
|
array |
Array of content elements making up the message. |
Message content structure¶
Each message’s content
array can contain multiple content elements with different types.
Field |
Type |
Description |
---|---|---|
|
string |
The content type. Valid values:
|
- Text content
When
type
is"text"
:Field
Type
Description
messages[].content[].text
string
The text content of the message.
Example:
{ "type": "text", "text": "Show me sales by region for Q1 2024" }
- Chart content
When
type
is “chart”:Field
Type
Description
messages[].content[].chart
object
The chart content of the message.
messages[].content[].chart.chart_spec
string
Chart as a Vega-Lite specification.
Example:
{ "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\"}", } }
- Table content
When
type
is “table”:Field
Type
Description
messages[].content[].table
object
The table content of the message.
messages[].content[].table.query_id
string
The ID of the executed query.
Example:
{ "type": "table", "table": { "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22" } }
- Tool use
When
type
is “tool_use”:Field
Type
Description
messages[].content[].tool_use
object
Container for tool use request details.
messages[].content[].tool_use.tool_use_id
string
Unique identifier for this tool use request.
messages[].content[].tool_use.name
string
Name of the tool to execute. Must match a tool name from the tools array.
messages[].content[].tool_use.input
object
Input parameters for the tool execution.
Example:
{ "type": "tool_use", "tool_use": { "tool_use_id": "tu_01", "name": "Analyst1", "input": { "query": "Show me sales by region for Q1 2024" } } }
- Tool results
When
type
is"tool_results"
:Field
Type
Description
messages[].content[].tool_results
object
Container for tool execution results and metadata.
messages[].content[].tool_results.tool_use_id
string
References the tool_use_id that generated these results.
messages[].content[].tool_results.name
string
Name of the tool that was executed. Must match a tool name from the tools array.
messages[].content[].tool_results.status
string
Tool execution status.
Valid values:
"success"
"error"
messages[].content[].tool_results.content
array
Array of content elements produced by the tool execution.
Can contain elements of the following types:
Type
Fields
Description
text
type: "text"
text: string
Plain text content returned by the tool.
json
type: "json"
json: object
Structured JSON data returned by the tool.
Example:
{ "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" } } ] } }
Complete message example¶
This example shows a complete message with a user query (role
is user
) and a response (role
is assistant
).
The response includes a tool use event for a tool named Analyst1
and a tool results event for the same tool.
{
"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"
}
}
]
}
}
]
}
]
}
Response¶
When streaming, each event arrives in a Server-Sent Events (SSE) format, with the following primary patterns:
Incremental
message.delta
events for chunks of the outputerror
events if something goes wrong.
message.delta
event¶
Field |
Type |
Description |
---|---|---|
|
string |
|
|
object |
Contains incremental update data. |
|
string |
Unique identifier for the message. |
|
string |
|
|
array |
A list of chunks or partial message segments. |
|
integer |
The position of this chunk within the current message. |
|
string |
Content type. Valid values:
|
|
string |
If |
|
object |
If |
|
string |
Chart as a Vega-Lite specification. |
|
object |
If |
|
string |
The ID of the executed query. |
|
object |
If |
|
string |
The unique identifier for the tool call. |
|
string |
The name of the tool being called. |
|
object |
JSON payload for the tool. |
|
object |
If |
|
string |
The unique identifier for the tool output. |
|
string |
The tool execution status. Valid values:
|
|
array |
A list of items describing the tool’s returned data. |
|
string |
The type of content returned by the tool. Valid values:
|
|
object |
If |
|
string |
If |
error
event¶
Field |
Type |
Description |
---|---|---|
|
string |
|
|
object |
Contains error details. |
|
string |
The Snowflake error code. For example, |
|
string |
A description of what went wrong. For example, |
Sample conversation flow¶
This section shows a sample conversation flow between a user and an assistant using the Cortex Agents REST API.
Sample request¶
{
"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?"
}
]
}
]
}
Sample response¶
{
"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"
}
}
}
]
}
}
Sample answers request¶
Cortex Agents can generate textual and chart answers based on executed SQL queries. The following example shows how to use the Cortex Agents API to generate such answers.
To get the answers, the client makes a follow-up request to the Cortex Agent API with the query_id
of the SQL executed on the client side.
The SQL to be executed is provided in the tool_use
event of sql_exec
tool type in the latest response message.
Requests must use the cortex_analyst_text_to_sql
and sql_exec
tools to get the textual answer, and furthermore must use the data_to_chart
tool to get the chart answer. Charts are returned only if the agent decides that charts are a good way to present the answer.
Note
For result sets over 4000 cells, a table
response is returned instead of text
and chart
answers.
{
"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_002",
"result": {
"query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
}
}
}
]
}
]
}
Sample answers response¶
{
"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\"}]}}"
}
}
]
}
}
Cortex Agents limitations¶
Because Streamlit in Snowflake (SiS) apps run under owner’s rights, executing SQL statements within SiS apps is not supported.
Azure OpenAI models are not supported.