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.

Tools configuration

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.

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

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".

Messages

The messages array contains the conversation history:

Field

Type

Description

messages[].role

string

The role of the message sender. Values: “system”, “user”, “assistant”.

messages[].content[].type

string

The content type. Values: “text”, “tool_use”, “tool_results”.

messages[].content[].text

string

The text content. Only for type = “text”.

messages[].content[].tool_use

object

The tool use specification. Only for type = “tool_use”.

messages[].content[].tool_use.tool_use_id

string

Unique identifier for the tool use.

messages[].content[].tool_use.name

string

Name of the tool to use.

messages[].content[].tool_use.input

object

Input parameters for the tool.

messages[].content[].tool_results

object

The tool results. Only for type = “tool_results”.

messages[].content[].tool_results.tool_use_id

string

References the tool_use_id that generated these results.

messages[].content[].tool_results.status

string

Tool execution status. Values: “success”, “error”.

messages[].content[].tool_results.content

array

Array of result content objects.

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

data.delta.content[].text

string

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

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_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": "cortex_analyst_sql_exec",
        "name": "SQL_exec1"
      }
    },
    {
      "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": "text",
          "text": "<thinking> ... here <..>"
        },
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_001",
            "name": "get_stock_price",
            "input": {
              "semantic_model_file": "semantic_model_1",
              "user_query": "What are the top three customers by revenue?"
            }
          }
        },
        {
          "type": "tool_results",
          "tool_results": {
            "status": "success",
            "tool_use_id": "tool_001",
            "content": [
              {"type": "json", "json": {"sql": "select * from table"}},
              {"type": "text", "text": "15 degrees"}
            ]
          }
        },
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_002",
            "name": "SQL_exec1",
            "input": {
              "sql": "select * from table"
            }
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_results": {
            "tool_use_id": "tool_002",
            "result": {
              "query_id": "kjlasdfasdfh234a"
            }
          }
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Top 3 customers by revenue are Acme, ..."
        }
      ]
    }
  ]
}
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
Language: English