Cortex Agents¶

Overview¶

Cortex Agents is a fully managed agentic platform for building and running AI agents within Snowflake’s governed environment. An agent reasons over a request, plans the work, calls tools, executes code, and generates a response, without requiring you to build or operate your own orchestration loop, runtime, or sandbox infrastructure. Data access is governed by Snowflake privileges and the execution context of each configured tool.

Agents bring your structured and unstructured data together in a single governed workflow. They generate SQL over structured data using Cortex Analyst semantic views and use Cortex Search to retrieve insights from unstructured sources, then reason over the combined results. You can extend what an agent can do with several types of tools:

• A built-in code execution tool that, when enabled, runs Python in a secure, isolated sandbox to process data and perform calculations.
• A Data to Chart tool that generates visualizations from data.
• Custom tools built from stored procedures and user-defined functions (UDFs) to call backend systems or implement your own business logic.
• Packaged agent skills, modular bundles of instructions and scripts that give an agent repeatable, task-specific capabilities.
• MCP connectors to remote Model Context Protocol (MCP) servers, letting agents discover and invoke tools hosted by providers such as Atlassian Jira, Salesforce, or your own applications.
• Web search for real-time information from the public internet.

Threads maintain conversation context across turns, so your client application doesn’t have to manage state. After deployment, you can monitor agents, collect end-user feedback, and run evaluations to continuously refine their behavior.

To answer a request, an agent follows a reasoning loop with three steps:

1. Plan: The agent parses the request and decides how to answer it. It can disambiguate a vague question (for example, “Tell me about Acme Supplies” might refer to products, location, or sales personnel), split a complex request into subtasks (for example, “What are the differences between contract terms for Acme Supplies and Acme Stationery?”), and choose which tool to use for each part.
2. Use tools: The agent calls the tools it selected, such as Cortex Analyst for structured data, Cortex Search for unstructured data, or the code execution tool to process results.
3. Reflect and respond: The agent evaluates the results from each tool to decide what to do next, whether that’s asking a clarifying question, calling another tool, or generating a final response. This loop lets the agent handle complex, multi-step questions while staying within Snowflake’s secure perimeter.

The agent repeats this loop as needed within a single request.

You define an agent as a reusable object that bundles its model, tools, and orchestration instructions. Create one in Snowsight, with the Cortex Agents SQL commands, or through the REST API, then integrate it into your application using the REST API. You guide its behavior with natural-language instructions, and you can choose the language model that powers it or let Snowflake select one automatically. In addition to calling agents from your own applications through the REST API, users can interact with them in Snowflake CoWork and Cortex Code.

For tutorials to help you get started, see Cortex Agents tutorials.

Access control requirements¶

To make a request to Cortex Agent via agent:run API, you can use a role that has the SNOWFLAKE.CORTEX_USER or SNOWFLAKE.CORTEX_AGENT_USER role granted. The CORTEX_USER provides access to all Covered AI features including Cortex Agents whereas CORTEX_AGENT_USER provides access to the Agents feature.

GRANT USAGE ON DATABASE <database_name> to ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;
GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> to ROLE <role_name>;

To use Cortex Agents with a semantic model, you also need the following privileges:

Requests to the Cortex Agents API must include an authorization token. For details on how to authenticate to the API, see Authenticating Snowflake REST APIs with Snowflake. Note that the example in this topic uses a session token to authenticate to a Snowflake account.

Limiting access to specific roles

By default, the CORTEX_USER role is granted to the PUBLIC role. The PUBLIC role is automatically granted to all users and roles. If you don’t want all users to have this privilege, you can revoke access to the PUBLIC role and grant access to specific roles. For more information, see Cortex LLM privileges.

To provide selective access to Cortex Agents so that only a subset of users have access to the feature, use the CORTEX_AGENTS_USER role.

Limiting access using the Cortex Agents user role

To provide selective access to Cortex Agents for specific users, use the SNOWFLAKE.CORTEX_AGENT_USER database role. This role includes the privileges needed to call the Cortex Agent API.

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE agent;

To provide access to Cortex Agents, use the ACCOUNTADMIN role to do the following:

1. Grant the SNOWFLAKE.CORTEX_AGENT_USER database role to a custom role.
2. Assign this custom role to users.

The following example:

1. Creates the custom role, cortex_agent_user_role.
2. Grants it the CORTEX_AGENT_USER database role.
3. Assigns this role to example_user.

USE ROLE ACCOUNTADMIN;
CREATE ROLE cortex_agent_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE cortex_agent_user_role;

GRANT ROLE cortex_agent_user_role TO USER example_user;

You can also grant access to Cortex Agents through existing roles. For example, if you have an agent role used by agents in your organization, you can grant access with a single GRANT statement:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE agent;

Authentication¶

Snowflake REST APIs support authentication via programmatic access tokens (PATs), key pair authentication using JSON Web Tokens (JWTs), and OAuth. For details, see Authenticating Snowflake REST APIs with Snowflake.

Cost considerations¶

Cortex Agents incur charges for the orchestration and use of tools.

• The orchestration usage is charged based on the tokens used.
• Cortex Analyst is charged per token.
• Cortex Search charges depend on the size of the index and the time it has persisted.
• Warehouse charges depend on the size of the warehouse and how long it runs.

For more information, see the Snowflake Service Consumption Table. Also, use of custom tools may incur warehouse costs.

Models¶

When creating an agent, we recommend selecting auto for the model. With this option, Cortex automatically selects the highest quality model for your account, and the quality automatically improves as new models become available.

Model and feature availability can vary by region and georegion. For the list of available models, see Model availability.

Cortex Agent Concepts¶

Cortex Agents use Cortex Analyst, Cortex Search and custom tools to plan tasks and generate responses. You can influence the orchestration with instructions. You can also specify attributes to dynamically select a tool based on business logic.

During an interaction, Agents use a thread to maintain context. A thread provides an easy retrieval of the entire conversation context for use in application logic.

You can collect feedback from end-users as you continuously iterate and refine the Agent. An explicit feedback mechanism (positive/negative rating) coupled with subjective feedback (text) allows you to capture user inputs throughout the lifecycle of the Agent.

Agent object¶

The agent configuration includes all metadata, orchestration settings, and tool details that are stored in the agent object. You can use the agent object to interact with the agent.

Threads¶

Threads persist the context of your interactions with the agent, so you don’t have to maintain context on the client application. To use threads, you create a thread object and reference the thread ID in the agent interactions.

Orchestration¶

Cortex Agents use LLM-based orchestration to plan tasks and generate responses. You can control the orchestration with the following settings:

Models¶

For information about the models you can use with Cortex Agents for orchestration, see Models.

Instructions¶

Response instructions allow you to configure the agent responses to a brand and tone of your preference.

Sample questions¶

You can use these questions to seed the conversation in your client application. These are common questions that can get users started with the interaction.

Tools¶

Cortex Agents can orchestrate across both structured and unstructured data. Also, custom tools allow agents to interact with other backend systems or implement custom logic.

Cortex Analyst semantic view¶

You can use Cortex Analyst to create SQL queries from natural language. To use Cortex Analyst, you must create a Semantic Model. For more information, see Create a semantic model.

Cortex Search Service¶

Use Cortex Search to search through your data. For more information, see CREATE CORTEX SEARCH SERVICE.

Agents can dynamically adjust the following search parameters if the user’s query requires it: filter conditions, metadata columns to retrieve, number of results, per-index queries for multi-index services, and time-decay settings.

Custom tools¶

You can use stored procedures and user defined functions (UDF) to implement custom business logic as a tool. For more information, see Stored procedures overview and User-defined functions overview.

Thinking and reflection¶

The Agent emits events throughout the interaction, providing insights into the reasoning process. These steps cover the initial splitting of tasks, sequencing into sub-tasks, and selection of tools for the sub-task. In addition, the agent also surfaces its reflections about tool results and how these influence further orchestration.

Monitor, evaluate, and iterate¶

You can collect feedback from the end user as a rating (positive/negative), along with any subjective inputs (as text). These can be used to refine and improve the agent over the lifecycle. For more information on how to perform monitoring and evaluation with native Snowflake features, see Monitor Cortex Agent requests and Cortex Agent evaluations.

Web search¶

Before providing web search access to your agents, an ACCOUNTADMIN role must first enable web search access at the account level. To properly enable web search:

1. Sign in to Snowsight.
2. In the navigation menu, select AI & ML » Agents.
3. Select Settings.
4. Select the Web search toggle to enable the feature, as shown below.

After enabling web search at the account level, you can use the web search tool in your agents. For more information, see Create an agent.

Cortex Agents use the Brave Web Search API to query the web and retrieve results for real-time information during an interaction. The agent creates a query based on the user’s input and any relevant context from the interaction. The API returns results from Brave Search’s independent web index. The query and the results leave Snowflake and traverse the public internet. The agent then incorporates the relevant results into its response alongside any data from other configured tools. Snowflake has enabled zero data retention (ZDR) with Brave, which means no search queries are stored by Brave for any length of time. This applies to the search query text, the results returned, and any metadata associated with the request. ZDR simplifies compliance obligations and reduces risk — because the data is never stored.

Interact with agents¶

Cortex Agents support two distinct methods of interacting with agents through the REST API:

• Configure an agent object to interact with the agent: With this method, you first configure an agent object that can be reused for the entire interaction. Configuring an agent object simplifies client code and enables CI/CD for enterprise-ready applications.
• Interact without an agent object: With this method, you must pass the agent configuration as part of every interaction request. Interaction without an agent object allows you to quickly try out use cases and experiment with different scenarios.

For information about these methods, see Configure and interact with Agents.

Legal notices¶

Where your configuration of Cortex Agents uses a model provided on the Model and Service Flow-down Terms, your use of that model is further subject to the terms for that model on that page.

The data classification of inputs and outputs are as set forth in the following table.

For additional information, refer to Snowflake AI and ML.