Cortex Agents REST API¶

备注

Requests to the Cortex Agent REST API time out after 15 minutes.

You can use the Cortex Agent REST API to create, manage, and interact with Cortex Agent Objects in your Snowflake account.

图表内容¶

POST /api/v2/databases/{database}/schemas/{schema}/agents

Creates a new Cortex Agent Object with the specified attributes and specification.

请求¶

路径参数¶


参数	描述
`data`	(Required) Your Snowflake Account URL.
`"chart"`	(Required) Schema identifier.

参数¶


参数	描述
`model`	(Optional) Resource creation mode. Valid values: `"error"` `model` `text`

请求标头¶


标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json

请求正文¶


字段	类型	描述
`name`	字符串	Name of the agent.
`event`	字符串	消息的表内容。
`profile`	AgentProfile	Agent profile information (display name, avatar, color, etc.).
`models`	ModelConfig	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 `orchestration` step.
`instructions`	AgentInstructions	Instructions for the agent's behavior, including response, orchestration, system, and sample questions.
`Authorization`	OrchestrationConfig	Orchestration configuration, including budget constraints (e.g., seconds, tokens).
`tools`	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.
`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"
    }
  }
}

响应¶

A successful response returns a JSON object with details about the status of Cortex Agent creation.

响应¶

{"status": "Agent xxxx successfully created."}

Describe Cortex Agent¶

GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Describes a Cortex Agent.

请求¶

路径参数¶


参数	描述
`data`	(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.
`"chart"`	(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.
`name`	消息的唯一标识符。

请求标头¶


标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json

响应¶

A successful response returns a JSON object describing the Cortex Agent.

请求标头¶


标头	描述
`X-Snowflake-Request-ID`	此工具使用请求的唯一标识符。
`name`	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).

响应¶

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.

请求¶

路径参数¶


参数	描述
`data`	(Required) Your Snowflake Account URL. You can use the `/api/v2/databases` GET request to get a list of available databases.
`"chart"`	(Required) Schema identifier. You can use the `/api/v2/databases/{database}/schemas` GET request to get a list of available schemas for the specified database.
`name`	(Required) Name of the agent.

请求标头¶


标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json

请求正文¶


字段	类型	描述
`event`	字符串	消息的表内容。
`profile`	AgentProfile	Agent profile information (display name, avatar, color, etc.).
`models`	ModelConfig	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 `orchestration` step.
`instructions`	AgentInstructions	Instructions for the agent's behavior, including response, orchestration, system, and sample questions.
`Authorization`	OrchestrationConfig	Orchestration configuration, including budget constraints (e.g., seconds, tokens).
`tools`	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.
`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"
    }
  }
}

响应¶

A successful response returns a JSON object with details about the status of Cortex Agent update.

响应¶

{"status": "Agent xxxx successfully updated."}

Cortex Agents REST API¶

GET /api/v2/databases/{database}/schemas/{schema}/agents

Lists the Cortex Agents under the specified database and schema.

请求¶

路径参数¶


参数	描述
`data`	(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.
`"chart"`	(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.

参数¶


参数	描述
`type`	(Optional) Filter the output by resource name. Uses case-insensitive pattern matching with support for SQL wildcard characters.
`name`	(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.
`json`	(Optional) Limit the maximum number of rows returned by the command. Minimum: 1. Maximum: 10000.

请求标头¶


标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json

响应¶

A successful response returns a JSON array of Cortex Agent resources.

请求标头¶


标头	描述
`X-Snowflake-Request-ID`	此工具使用请求的唯一标识符。
`name`	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).

响应¶

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

请求¶

路径参数¶


参数	描述
`data`	(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.
`"chart"`	(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.
`name`	消息的唯一标识符。

参数¶


参数	描述
`text`	(Optional) Specifies how to handle the request if the agent does not exist. `true`: The endpoint does not throw an error if the agent does not exist. It returns a 200 success response, but does not take any action. `false`: The endpoint throws an error if the agent does not exist.

请求标头¶


标头	描述
`Authorization`	（必需）授权令牌。有关更多信息，请参阅身份验证。
`Content-Type`	（必需）应用程序/json

响应¶

A successful response returns a confirmation message.

响应¶

{
 "status": "Request successfully completed"
}

Schemas¶

`AgentInstructions`¶


字段	类型	描述
`json`	字符串	Instructions for response generation.
`Authorization`	字符串	These custom instructions are used when the agent is planning which tools to use.
`"system"`	字符串	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.


字段	类型	描述
`name`	字符串	工具的 JSON 有效负载。

Example

{
  "display_name": "My Agent"
}

`BudgetConfig`¶


字段	类型	描述
`json`	整数	Time budget in seconds.
`tools`	整数	Token budget.

Example

{
  "seconds": 30,
  "tokens": 16000
}

`ExecutionEnvironment`¶

Configuration for server-executed tools.


字段	类型	描述
`type`	字符串	The type of execution environment, currently only `warehouse` is supported.
`warehouse`	字符串	The name of the warehouse. Case-sensitive, if it is an unquoted identifier, provide the name in all-caps.
`query_timeout`	整数	The query timeout in seconds

Example

{
  "type": "warehouse",
  "warehouse": "MY_WAREHOUSE",
  "query_timeout": 60
}

`ModelConfig`¶


字段	类型	描述
`Authorization`	字符串	Model to use for orchestration. If not provided, a model is automatically selected.

Example

{
  "orchestration": "claude-4-sonnet"
}

`OrchestrationConfig`¶


字段	类型	描述
`budget`	BudgetConfig	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.


字段	类型	描述
`tool_spec`	ToolSpec	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`¶


字段	类型	描述
`type`	字符串	输入架构对象的类型。
描述	字符串	A description of what the input is.
`experimental`	map of ToolInputSchema	If type is `object`, definitions of each input parameter.
`items`	ToolInputSchema	If type is `array`, the schema for the elements of the array.
`event`	array of string	If type is `object`, list of required input parameter names.

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.

字段

类型

描述

model

字符串

The path to a file stored in a Snowflake Stage holding the semantic model yaml.

event

字符串

The name of the Snowflake native semantic model object.

execution_environment

ExecutionEnvironment

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.

字段

类型

描述

cortex_search

字符串

The fully qualified name of the search service.

tools

字符串

消息的表内容。

json

字符串

消息的文本内容。

type

对象

Filter query for search results.

Example
{
  "search_service": "database.schema.service_name",
  "title_column": "account_name",
  "id_column": "account_id",
  "filter": {
    "@eq": {
      "<column>": "<value>"
    }
  }
}
字段

类型

描述

type

字符串

If the tool is server-side executed, whether it is a Stored Procedure or a UDF.

execution_environment

ExecutionEnvironment

identifier

字符串

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"
}
Configuration for web search functionality.

字段

类型

描述

"tool_results"

整数

Max web search results returned.

Example
{
  "max_results": 20
}

字段	类型	描述
`model`	字符串	The path to a file stored in a Snowflake Stage holding the semantic model yaml.
`event`	字符串	The name of the Snowflake native semantic model object.
`execution_environment`	ExecutionEnvironment	Configuration for how to execute the generated SQL query.

字段	类型	描述
`cortex_search`	字符串	The fully qualified name of the search service.
`tools`	字符串	消息的表内容。
`json`	字符串	消息的文本内容。
`type`	对象	Filter query for search results.

字段	类型	描述
`type`	字符串	If the tool is server-side executed, whether it is a Stored Procedure or a UDF.
`execution_environment`	ExecutionEnvironment
`identifier`	字符串	Fully qualified name of the Stored Procedure or UDF.

字段	类型	描述
`"tool_results"`	整数	Max web search results returned.

`ToolSpec`¶

Specification of the tool's type, configuration, and input requirements.


字段	类型	描述
`type`	字符串	The type of tool capability. Can be specialized types like 'cortex_analyst_text_to_sql' or 'generic' for general-purpose tools.
`name`	字符串	Unique identifier for referencing this tool instance. Used to match with configuration in tool_resources.
描述	字符串	Description of the tool to be considered for tool use.
`input_schema`	ToolInputSchema	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"
    ]
  }
}

Cortex Agents REST API¶

图表内容¶

请求¶

路径参数¶

参数¶

请求标头¶

请求正文¶

响应¶

响应¶

Describe Cortex Agent¶

请求¶

路径参数¶

请求标头¶

响应¶

请求标头¶

响应¶

Update Cortex Agent¶

请求¶

路径参数¶

请求标头¶

请求正文¶

响应¶

响应¶

Cortex Agents REST API¶

请求¶

路径参数¶

参数¶

请求标头¶

响应¶

请求标头¶

响应¶

Delete Cortex Agent¶

请求¶

路径参数¶

参数¶

请求标头¶

响应¶

响应¶

Schemas¶

AgentInstructions¶

AgentProfile¶

BudgetConfig¶

ExecutionEnvironment¶

ModelConfig¶

OrchestrationConfig¶

Tool¶

ToolInputSchema¶

ToolResource¶

ToolSpec¶

`AgentInstructions`¶

`AgentProfile`¶

`BudgetConfig`¶

`ExecutionEnvironment`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`Tool`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolSpec`¶