Cortex Agents REST API¶
You can use the Cortex Agent REST API to create, manage, and interact with Cortex Agent Objects in your Snowflake account.
Create Cortex Agent¶
POST /api/v2/databases/{database}/schemas/{schema}/agents
Creates a new Cortex Agent Object with the specified attributes and specification.
Request¶
Path parameters¶
Parameter |
Description |
---|---|
|
(Required) Your Snowflake Account URL. |
|
(Required) Schema identifier. |
Query parameters¶
Parameter |
Description |
---|---|
|
(Optional) Resource creation mode. Valid values:
|
Request headers¶
Header |
Description |
---|---|
|
(Required) Authorization token. For more information, see Authentication. |
|
(Required) application/json |
Request body¶
Field |
Type |
Description |
---|---|---|
|
string |
Name of the agent. |
|
string |
Optional comment about the agent. |
|
Agent profile information (display name, avatar, color, etc.). |
|
|
Model configuration for the agent. Includes the orchestration model (e.g., claude-4-sonnet). If not provided, a model is automatically selected. Currently only available for the |
|
|
Instructions for the agent’s behavior, including response, orchestration, system, and sample questions. |
|
|
Orchestration configuration, including budget constraints (e.g., seconds, tokens). |
|
|
array of Tool |
List of tools available for the agent to use. Each tool includes a tool_spec with type, name, description, and input schema. Tools may have a corresponding configuration in tool_resources. |
|
map of ToolResource |
Configuration for each tool referenced in the tools array. Keys must match the name of the respective tool. |
Example
{
"name": "MY_AGENT",
"comment": "An agent to answer questions about all my data",
"profile": {
"display_name": "My Agent"
},
"models": {
"orchestration": "claude-4-sonnet"
},
"instructions": {
"response": "You will respond in a friendly but concise manner",
"orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
"system": "You are a friendly agent ..."
},
"orchestration": {
"budget": {
"seconds": 30,
"tokens": 16000
}
},
"tools": [
{
"tool_spec": {
"type": "generic",
"name": "get_revenue",
"description": "Fetch the delivery revenue for a location.",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
}
},
"required": [
"location"
]
}
}
],
"tool_resources": {
"get_revenue": {
"type": "function",
"execution_environment": {
"type": "warehouse",
"warehouse": "MY_WH"
},
"identifier": "DB.SCHEMA.UDF"
}
}
}
Response¶
A successful response returns a JSON object with details about the status of Cortex Agent creation.
Response body¶
{"status": "Agent xxxx successfully created."}
Describe Cortex Agent¶
GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}
Describes a Cortex Agent.
Request¶
Path parameters¶
Parameter |
Description |
---|---|
|
(Required) Identifier for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases. |
|
(Required) Identifier for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database. |
|
(Required) Identifier for the agent. |
Request headers¶
Header |
Description |
---|---|
|
(Required) Authorization token. For more information, see Authentication. |
|
(Required) application/json |
Response¶
A successful response returns a JSON object describing the Cortex Agent.
Response headers¶
Header |
Description |
---|---|
|
Unique ID of the API request. |
|
Links to the page of results (e.g. the first page, the last page, etc.). The header can include multiple url entries with different rel attribute values that specify the page to return (first, next, prev, and last). |
Response body¶
The response body contains the details of the Cortex Agent.
{
"agent_spec": "{\"models\":{\"orchestration\":\"llama3.1-70B\"},\"experimental\":{\"foo\":\"bar\",\"nested\":{\"key\":\"value\"}},\"orchestration\":{\"budget\":{\"seconds\":30,\"tokens\":16000}},\"instructions\":{\"response\":\"You will respond in a friendly but concise manner\",\"orchestration\":\"For any revenue question use Analyst; for policy use Search\",\"system\":\"You are a friendly agent.\",\"sample_questions\":[{\"question\":\"question 1\"},{\"question\":\"question 2\"},{\"question\":\"question 3\"}]},\"tools\":[{\"tool_spec\":{\"type\":\"cortex_analyst_text_to_sql\",\"name\":\"Analyst1\",\"description\":\"test\"}},{\"tool_spec\":{\"type\":\"cortex_analyst_sql_exec\",\"name\":\"SQL_exec1\"}},{\"tool_spec\":{\"type\":\"cortex_search\",\"name\":\"Search1\"}},{\"tool_spec\":{\"type\":\"web_search\",\"name\":\"web_search_1\"}},{\"tool_spec\":{\"type\":\"generic\",\"name\":\"get_weather\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"The city and state\"}},\"required\":[\"Location\"]}}}],\"tool_unable_to_answer\":\"I don't know the answer to that\",\"tool_resources\":{\"Analyst1\":{\"semantic_model_file\":\"stage1\"},\"Analyst2\":{\"semantic_view\":\"db.schema.semantic_view\"},\"Search1\":{\"name\":\"db.schema.service_name\",\"Max_results\":\"5\",\"filter\":{\"@eq\":{\"region\":\"North America\"}},\"Title_column\":\"<title_name>\",\"ID_column\":\"<column_name>\"},\"SQL_exec1\":{\"Name\":\"my_warehouse\",\"Timeout\":\"30\",\"AutoExecute\":\"true\"},\"web_search\":{\"name\":\"web_search_1\",\"Function\":\"db/schema/search_web\"}}}",
"name": "MY_AGENT1",
"database_name": "TEST_DATABASE",
"schema_name": "TEST_SCHEMA",
"owner": "ACCOUNTADMIN",
"created_on": "1967-06-23T07:00:00.123+00:00"
}
Update Cortex Agent¶
PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
Updates an existing Cortex Agent with the specified attributes and specification.
Request¶
Path parameters¶
Parameter |
Description |
---|---|
|
(Required) Your Snowflake Account URL. You can use the |
|
(Required) Schema identifier. You can use the |
|
(Required) Name of the agent. |
Request headers¶
Header |
Description |
---|---|
|
(Required) Authorization token. For more information, see Authentication. |
|
(Required) application/json |
Request body¶
Field |
Type |
Description |
---|---|---|
|
string |
Optional comment about the agent. |
|
Agent profile information (display name, avatar, color, etc.). |
|
|
Model configuration for the agent. Includes the orchestration model (e.g., claude-4-sonnet). If not provided, a model is automatically selected. Currently only available for the |
|
|
Instructions for the agent’s behavior, including response, orchestration, system, and sample questions. |
|
|
Orchestration configuration, including budget constraints (e.g., seconds, tokens). |
|
|
array of Tool |
List of tools available for the agent to use. Each tool includes a tool_spec with type, name, description, and input schema. Tools may have a corresponding configuration in tool_resources. |
|
map of ToolResource |
Configuration for each tool referenced in the tools array. Keys must match the name of the respective tool. |
Example
{
"comment": "An agent to answer questions about all my data",
"profile": {
"display_name": "My Agent"
},
"models": {
"orchestration": "claude-4-sonnet"
},
"instructions": {
"response": "You will respond in a friendly but concise manner",
"orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
"system": "You are a friendly agent ..."
},
"orchestration": {
"budget": {
"seconds": 30,
"tokens": 16000
}
},
"tools": [
{
"tool_spec": {
"type": "generic",
"name": "get_revenue",
"description": "Fetch the delivery revenue for a location.",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
}
},
"required": [
"location"
]
}
}
],
"tool_resources": {
"get_revenue": {
"type": "function",
"execution_environment": {
"type": "warehouse",
"warehouse": "MY_WH"
},
"identifier": "DB.SCHEMA.UDF"
}
}
}
Response¶
A successful response returns a JSON object with details about the status of Cortex Agent update.
Response body¶
{"status": "Agent xxxx successfully updated."}
List Cortex Agents¶
GET /api/v2/databases/{database}/schemas/{schema}/agents
Lists the Cortex Agents under the specified database and schema.
Request¶
Path parameters¶
Parameter |
Description |
---|---|
|
(Required) Identifier for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases. |
|
(Required) Identifier for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database. |
Query parameters¶
Parameter |
Description |
---|---|
|
(Optional) Filter the output by resource name. Uses case-insensitive pattern matching with support for SQL wildcard characters. |
|
(Optional) Enable fetching rows only following the first row whose object name matches the specified string. Case-sensitive and does not have to be the full name. |
|
(Optional) Limit the maximum number of rows returned by the command. Minimum: 1. Maximum: 10000. |
Request headers¶
Header |
Description |
---|---|
|
(Required) Authorization token. For more information, see Authentication. |
|
(Required) application/json |
Response¶
A successful response returns a JSON array of Cortex Agent resources.
Response headers¶
Header |
Description |
---|---|
|
Unique ID of the API request. |
|
Links to the page of results (e.g. the first page, the last page, etc.). The header can include multiple url entries with different rel attribute values that specify the page to return (first, next, prev, and last). |
Response body¶
[
{
"name": "my_agent",
"database": "TEST_DB",
"schema": "TEST_SCHEMA",
"created_on": "2024-06-01T12:00:00Z",
"owner": "ACCOUNTADMIN",
"comment": "Sample agent"
},
{
"name": "another_agent",
"database": "TEST_DB",
"schema": "TEST_SCHEMA",
"created_on": "2024-06-02T08:30:00Z",
"owner": "SYSADMIN",
"comment": ""
}
]
Delete Cortex Agent¶
DELETE /api/v2/databases/{database}/schemas/{schema}/agents/{name}
Deletes a Cortex Agent with the specified name. If the ifExists
parameter is set to true
, the operation succeeds even if the agent does not exist. Otherwise, the operation fails if the agent cannot be deleted.
Request¶
Path parameters¶
Parameter |
Description |
---|---|
|
(Required) Identifier for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases. |
|
(Required) Identifier for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database. |
|
(Required) Identifier for the agent. |
Query parameters¶
Parameter |
Description |
---|---|
|
(Optional) Specifies how to handle the request if the agent does not exist.
|
Request headers¶
Header |
Description |
---|---|
|
(Required) Authorization token. For more information, see Authentication. |
|
(Required) application/json |
Response¶
A successful response returns a confirmation message.
Response body¶
{
"status": "Request successfully completed"
}
Schemas¶
AgentInstructions
¶
Field |
Type |
Description |
---|---|---|
|
string |
Instructions for response generation. |
|
string |
These custom instructions are used when the agent is planning which tools to use. |
|
string |
System instructions for the agent. |
Example
{
"response": "You will respond in a friendly but concise manner",
"orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
"system": "You are a friendly agent ..."
}
AgentProfile
¶
The profile information for a Data Cortex agent.
Field |
Type |
Description |
---|---|---|
|
string |
Display name for the agent. |
Example
{
"display_name": "My Agent"
}
BudgetConfig
¶
Field |
Type |
Description |
---|---|---|
|
integer |
Time budget in seconds. |
|
integer |
Token budget. |
Example
{
"seconds": 30,
"tokens": 16000
}
ExecutionEnvironment
¶
Configuration for server-executed tools.
Field |
Type |
Description |
---|---|---|
|
string |
The type of execution environment, currently only |
|
string |
The name of the warehouse. Case-sensitive, if it is an unquoted identifier, provide the name in all-caps. |
|
integer |
The query timeout in seconds |
Example
{
"type": "warehouse",
"warehouse": "MY_WAREHOUSE",
"query_timeout": 60
}
ModelConfig
¶
Field |
Type |
Description |
---|---|---|
|
string |
Model to use for orchestration. If not provided, a model is automatically selected. |
Example
{
"orchestration": "claude-4-sonnet"
}
OrchestrationConfig
¶
Field |
Type |
Description |
---|---|---|
|
Budget constraints for the agent. If more than one constraint is specified, whichever is first hit will end the request. |
Example
{
"budget": {
"seconds": 30,
"tokens": 16000
}
}
Tool
¶
Defines a tool that can be used by the agent. Tools provide specific capabilities like data analysis, search, or generic functions.
Field |
Type |
Description |
---|---|---|
|
Specification of the tool’s type, configuration, and input requirements. |
Example
{
"tool_spec": {
"type": "generic",
"name": "get_revenue",
"description": "Fetch the delivery revenue for a location.",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
}
},
"required": [
"location"
]
}
}
ToolInputSchema
¶
Field |
Type |
Description |
---|---|---|
|
string |
The type of the input schema object. |
|
string |
A description of what the input is. |
|
map of ToolInputSchema |
If type is |
|
If type is |
|
|
array of string |
If type is |
Example
{
"type": "object",
"description": "Input for my custom tool",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"items": {},
"required": [
"location"
]
}
ToolResource
¶
Configuration for text-to-SQL analysis tool. Provides parameters for SQL query generation and execution. Exactly one of semantic_model_file or semantic_view must be provided.
Field
Type
Description
semantic_model_file
string
The path to a file stored in a Snowflake Stage holding the semantic model yaml.
semantic_view
string
The name of the Snowflake native semantic model object.
execution_environment
Configuration for how to execute the generated SQL query.
Example
{ "semantic_model_file": "@db.schema.stage/semantic_model.yaml", "semantic_view": "db.schema.semantic_view", "execution_environment": { "type": "warehouse", "warehouse": "MY_WAREHOUSE", "query_timeout": 60 } }Configuration for search functionality. Defines how document search and retrieval should be performed.
Field
Type
Description
search_service
string
The fully qualified name of the search service.
title_column
string
The title column of the document.
id_column
string
The ID column of the document.
filter
object
Filter query for search results.
Example
{ "search_service": "database.schema.service_name", "title_column": "account_name", "id_column": "account_id", "filter": { "@eq": { "<column>": "<value>" } } }
Field
Type
Description
type
string
If the tool is server-side executed, whether it is a Stored Procedure or a UDF.
execution_environment
identifier
string
Fully qualified name of the Stored Procedure or UDF.
Example
{ "type": "function", "execution_environment": { "type": "warehouse", "warehouse": "MY_WAREHOUSE", "query_timeout": 60 }, "identifier": "MY_DB.MY_SCHEMA.MY_UDF" }
ToolSpec
¶
Specification of the tool’s type, configuration, and input requirements.
Field |
Type |
Description |
---|---|---|
|
string |
The type of tool capability. Can be specialized types like ‘cortex_analyst_text_to_sql’ or ‘generic’ for general-purpose tools. |
|
string |
Unique identifier for referencing this tool instance. Used to match with configuration in tool_resources. |
|
string |
Description of the tool to be considered for tool use. |
|
JSON Schema definition of the expected input parameters for this tool. This will be fed to the agent so it knows the structure it should follow for when generating the input for ToolUses. Required for generic tools to specify their input parameters. |
Example
{
"type": "generic",
"name": "get_weather",
"description": "lorem ipsum",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": [
"location"
]
}
}