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

account_url

(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

Authorization

(Required) Authorization token. For more information, see Configure Key-Pair Authentication.

Content-Type

(Required) application/json

Request body

The request body contains the model, response instruction, experimental fields, tools, tool resources, and messages.

Field

Type

Description

model

string

The name of the model used by the Agent to generate a response. For a list of supported models, see Supported models.

response_instruction

string

The instructions the model follows when it generates the response.

experimental

object

Experimental flags passed to the agent.

tools

array

An array of tool specifications available to the agent.

tool_resources

object

Resources required by the tools.

tool_choice

object

The configuration used to select the tool.

messages

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

tool_spec.type

string

The type of tool. A combination of type and name is a unique identifier.

tool_spec.name

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 functionality

  • cortex_analyst_text_to_sql: Used for Cortex Analyst text-to-SQL

  • sql_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},
    // ...
}
Copy

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>"}
    }
}
Copy
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"
}
Copy

Tool choice

The tool_choice field configures tool selection behavior.

Field

Type

Description

type

string

How tools should be selected.

Valid values:

  • "auto"` (default)

  • "required" (use at least one tool)

  • "tool" (use specified tool)

name

array

Optional array of tool names to use. Only valid when type = "tool".

Messages

The messages array contains the conversation history between the user and assistant:

Field

Type

Description

messages[].role

string

The role of the message sender.

Valid values:

  • "system"

  • "user"

  • "assistant"

messages[].content

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

messages[].content[].type

string

The content type.

Valid values:

  • "text"

  • "chart"

  • "table"

  • "tool_use"

  • "tool_results"

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"
}
Copy
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\"}",
  }
}
Copy
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"
  }
}
Copy
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"
    }
  }
}
Copy
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"
        }
      }
    ]
  }
}
Copy
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"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
Copy

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 output

  • error events if something goes wrong.

message.delta event

Field

Type

Description

event

string

message.delta for partial message data.

data

object

Contains incremental update data.

data.id

string

Unique identifier for the message.

data.object

string

message.delta or a similar descriptor.

data.delta.content

array

A list of chunks or partial message segments.

data.delta.content[].index

integer

The position of this chunk within the current message.

data.delta.content[].type

string

Content type. Valid values:

  • "text"

  • "chart"

  • "table"

  • "tool_use"

  • "tool_results"

data.delta.content[].text

string

If type = "text", the partial text string.

data.delta.content[].chart

object

If type = "chart", the chart content of the message.

data.delta.content[].chart.chart_spec

string

Chart as a Vega-Lite specification.

data.delta.content[].table

object

If type = "table", the table content of the message.

data.delta.content[].table.query_id

string

The ID of the executed query.

data.delta.content[].tool_use

object

If type = "tool_use", indicates a tool call in progress. Contains tool_use_id, name, input.

data.delta.content[].tool_use.tool_use_id

string

The unique identifier for the tool call.

data.delta.content[].tool_use.name

string

The name of the tool being called.

data.delta.content[].tool_use.input

object

JSON payload for the tool.

data.delta.content[].tool_results

object

If type = "tool_results", contains the tool output.

data.delta.content[].tool_results.tool_use_id

string

The unique identifier for the tool output.

data.delta.content[].tool_results.status

string

The tool execution status. Valid values:

  • "success"

  • "error"

data.delta.content[].tool_results.content

array

A list of items describing the tool’s returned data.

data.delta.content[].tool_results.content[].type

string

The type of content returned by the tool. Valid values:

  • "text/csv"

  • "application/json"

  • "application/pdf"

data.delta.content[].tool_results.content[].json

object

If type = "application/json", the JSON data returned by the tool.

data.delta.content[].tool_results.content[].text

string

If type = "text", the text data returned by the tool.

error event

Field

Type

Description

event

string

error for error events.

data

object

Contains error details.

data.code

string

The Snowflake error code. For example, "399505".

data.message

string

A description of what went wrong. For example, "Internal server error".

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?"
        }
      ]
    }
  ]
}
Copy

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"
            }
          }
        }
    ]
  }
}
Copy

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"
            }
          }
        }
      ]
    }
  ]
}
Copy

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\"}]}}"
        }
      }
    ]
  }
}
Copy

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.