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 then generates a 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.

Tools 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
data_to_chart: Used for generating charts

Tool Resources¶

The tool_resources field is an object that maps tool names to their configuration objects:

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

Copy

The following configurations are supported for each tool type:

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

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¶

The tool_choice field configures tool selection behavior:

Field	Type	Description
`type`	string	How tools should be selected. Valid values: "auto"` (default) `"required"` (use ≥1 tool) `"tool"` (use specified tool).
`name`	array	Optional array of tool names to use. Only valid when `type = "tool"`.

Field

Type

Description

type

string

How tools should be selected.

Valid values:

"auto"` (default)
"required" (use ≥1 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.

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"` `"tool_use"` `"tool_results"`

Field

Type

Description

messages[].content[].type

string

The content type.

Valid values:

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

Text Content¶

When type is "text":

Field	Type	Description
`messages[].content[].text`	string	The text content of the message.

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.

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.

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. Values: `"success"` `"error"`
`messages[].content[].tool_results.content`	array	Array of content elements produced by the tool execution.

Tool Results Content Types¶

The tool_results.content array 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.

Examples¶

Text Content example¶

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

Copy

Chart Content 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

Tool Use 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 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¶

{
  "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 typically arrives in a Server-Sent Events (SSE) format, with the following primary patterns:

Incremental message.delta events for partial 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"` `"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[].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 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_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

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:\"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

Cortex Agents REST API¶

Run agent¶

Request¶

Path parameters¶

Request headers¶

Request body¶

Response instruction¶

Tools configuration¶

Tool specifications¶

Tool Resources¶

cortex_search¶

cortex_analyst_text_to_sql¶

Tool choice¶

Messages¶

Message Content Structure¶

Text Content¶

Chart Content¶

Tool Use¶

Tool Results¶

Tool Results Content Types¶

Examples¶

Text Content example¶

Chart Content example¶

Tool Use example¶

Tool Results example¶

Complete Message example¶

Response¶

message.delta Event¶

error Event¶

Sample request¶

Sample response¶

`cortex_search`¶

`cortex_analyst_text_to_sql`¶

`message.delta` Event¶