Cortex Agents REST API¶

profile¶

The profile field configures tool selection behavior.

models¶

The models field configures models for the agent.

orchestration¶

The orchestration field configures orchestration settings for the agent.

budget¶

The budget object specifies resource limits for the agent.

instructions¶

The instructions field defines instructions for the agent’s behavior, including response generation, orchestration, system instructions, and sample questions.

sample_questions¶

Each element in the sample_questions array is an object with the following fields:

tools¶

The tools field defines the list of tools available for the agent to use. Tools provide specific capabilities such as data analysis, search, or generic functions. Each tool may have a corresponding configuration in the tool_resources object.

tool_spec¶

The tool_spec object describes the tool’s capabilities and configuration.

input_schema¶

The input_schema object defines the input parameters for the tool.

tool_resources¶

The tool_resources object defines configuration for each tool referenced in the tools array. Each key must match the tool name. The value can be one of the following objects:

Cortex Analyst analysis tool configuration¶

Configuration for Cortex Analyst analysis tools. Provides parameters for SQL query generation and execution.

Search tool configuration¶

Configuration for search functionality. Defines how document search and retrieval should be performed.

Both configuration objects allow additional properties.

profile¶

The profile field configures tool selection behavior.

models¶

The models field configures models for the agent.

orchestration¶

The orchestration field configures orchestration settings for the agent.

budget¶

The budget object specifies resource limits for the agent.

instructions¶

The instructions field defines instructions for the agent’s behavior, including response generation, orchestration, system instructions, and sample questions.

sample_questions¶

Each element in the sample_questions array is an object with the following fields:

tools¶

The tools field defines the list of tools available for the agent to use. Tools provide specific capabilities such as data analysis, search, or generic functions. Each tool may have a corresponding configuration in the tool_resources object.

tool_spec¶

The tool_spec object describes the tool’s capabilities and configuration.

input_schema¶

The input_schema object defines the input parameters for the tool.

tool_resources¶

The tool_resources object defines configuration for each tool referenced in the tools array. Each key must match the tool name. The value can be one of the following objects:

Cortex Analyst analysis tool configuration¶

Configuration for Cortex Analyst analysis tools. Provides parameters for SQL query generation and execution.

Search tool configuration¶

Configuration for search functionality. Defines how document search and retrieval should be performed.

Both configuration objects allow additional properties.

messages¶

The messages array contains the conversation history between the user and assistant. If a thread is used, only user message is needed.

Message content structure¶

Each message’s content array can contain multiple content elements with different types.

“text”¶

When type is "text":

Field	Type	Description
annotations	array	An array of annotations attached to the text result. Can be either cortex_search_citation or web_search_citation.
is_elicitation	boolean	Whether this text content is the agent asking for more information from the end user.

cortex_search_citation¶

The cortex_search_citation object contains the following fields:

Field	Type	Description
index	integer	(Required) The index of the citation in the search results.
search_result_id	string	(Required) The unique identifier for the search result.
doc_id	string	(Required) The unique identifier for the document.
doc_title	string	(Required) The title of the document.
text	string	(Required) The text excerpt from the document used as the citation.

web_search_citation¶

The web_search_citation object contains the following fields:

Field	Type	Description
start_index	integer	(Required) The starting index of the citation in the text.
end_index	integer	(Required) The ending index of the citation in the text.
source_url	string	(Required) The URL of the source document.
text	string	(Required) The text excerpt from the source used as the citation.

“thinking”¶

When type is "thinking":

Field	Type	Description
type	string	The text content of the message.
thinking	string	Thinking tokens from the agent.

“tool_use”¶

When type is "tool_use":

Field	Type	Description
tool_use	object	Container for tool use request details.
tool_use.tool_use_id	string	Unique identifier for this tool use request. Can be used to associated tool results.
tool_use.type	string	The type of the tool. For example, cortex_search or cortex_analyst_text2sql.
tool_use.name	string	The unique identifier for this tool instance.
tool_use.input	object	The structured input for this tool.

“tool_result”¶

When type is "tool_result":

Field	Type	Description
tool_result	object	(Required) Container for tool execution results and metadata.
tool_result.tool_use_id	string	(Required) Unique identifier for this tool use. Can be used to associated tool results.
tool_result.type	string	(Required) The type of the tool. For example, cortex_search or cortex_analyst_text2sql.
tool_result.name	string	(Required) The unique identifier for this tool instance.
tool_result.status	string	(Required) Tool execution status. Valid values: "success" "error"
tool_result.result	object	Additional result data.
tool_result.content	array	(Required) 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. The schema varies depending on the tool type.

“table”¶

When type is "table":

Field	Type	Description
table	object	(Required) The table content of the message.
table.tool_use_id	string	(Required) The ID of the tool use that generated this table.
table.query_id	string	(Required) The query ID of the SQL query that generated this data.
table.result_set	string	(Required) The query ID of the SQL query that generated this data.

table.result_set¶

The ResultSet object represents the result of a SQL query execution. This object matches the schema for ResultSet.

Field	Type	Description
statementHandle	string	(Required) The unique identifier for the executed statement.
resultSetMetaData	object	(Required) Metadata describing the structure of the result set.
data	array of arrays of strings	(Required) The actual result data, represented as an array of rows. Each row is an array of string values.

resultSetMetaData¶

The ResultSetMetaData object describes metadata for a SQL query result set.

Field	Type	Description
partition	integer	(Required) The partition number for the result set.
numRows	integer	(Required) The number of rows in the result set.
format	string	(Required) The format of the result set.
rowType	array	(Required) Array describing the type of each row. Each element is a rowType object.

rowType¶

The RowType object describes the metadata for a single row in a SQL query result set.

Field	Type	Description
name	integer	(Required) The name of the row.
type	integer	(Required) The data type of the row.
length	string	(Required) The length.
precision	array	(Required) The precision.
scale	array	(Required) The scale.
nullable	array	(Required) Indicates whether the row can contain null values.

“chart”¶

When type is "chart"`:

Field	Type	Description
chart	object	The chart content of the message.

Chart content structure¶

The chart object contains the following fields:

Field	Type	Description
tool_use_id	string	(Required) The ID of the tool use that generated this chart.
chart_spec	string	(Required) The vega-lite chart specification serialized as a string.
analyst_tool_use_id	string	(Deprecated) The tool_use_id of the Cortex Analyst tool call that generated the data for this chart. Clients should use tool_use_id to fetch the chart tool use and from there find the Analyst tool_use_id if needed.

“suggested_queries”¶

When type is "suggested_queries"`:

Field	Type	Description
suggested_queries	array	(Required) An array of query arrays.

execution_trace¶

The execution_trace object configures execution tracing for the agent:

tool_choice¶

The tool_choice object configures how tools should be selected and used during the interaction.

Tool specifications¶

The tools field contains an array of available tools:

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

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. The configuration must include the semantic model or view to use. For example:

"AnalystName": {
    // Stage path to semantic model file in `semantic_model_file`
    "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml"
}

Copy

or using Overview of semantic views

"AnalystName": {
    // Fully qualified name of the semantic view object
    "semantic_view": "database.schema.semantic_view"
}

Copy

Tool choice¶

The tool_choice field configures tool selection behavior.

Message content structure¶

Each message’s content array can contain multiple content elements with different types.

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