Cortex Agents¶
Overview¶
Cortex Agents orchestrate across both structured and unstructured data sources to deliver insights. They plan tasks, use tools to execute these tasks, and generate responses. Agents use Cortex Analyst (structured) and Cortex Search (unstructured) as tools, along with LLMs, to analyze data. Cortex Search extracts insights from unstructured sources, while Cortex Analyst generates SQL to process structured data. In addition, you can use stored procedures and user defined functions (UDFs) to implement custom tools. A comprehensive support for tool identification and tool execution enables delivery of sophisticated applications grounded in enterprise data.
The workflow involves four key components:
Planning: Applications often switch between processing data from structured and unstructured sources. For example, consider a conversational app designed to answer user queries. A business user may first ask for top distributors by revenue (structured) and then switch to inquiring about a contract (unstructured). Cortex Agents can parse a request to orchestrate a plan and arrive at the solution or response.
Explore options: When the user poses an ambiguous question (for example, “Tell me about Acme Supplies”), the agent considers different permutations - products, location, or sales personnel - to disambiguate and improve accuracy.
Split into subtasks: Cortex Agents can split a task or request (for example, “What are the differences between contract terms for Acme Supplies and Acme Stationery?”) into multiple parts for a more precise response.
Route across tools: The agent selects the right tool - Cortex Analyst or Cortex Search - to ensure governed access and compliance with enterprise policies.
Tool use: With a plan in place, the agent retrieves data efficiently. Cortex Search extracts insights from unstructured sources, while Cortex Analyst generates SQL to process structured data. A comprehensive support for tool identification and tool execution enables delivery of sophisticated applications grounded in enterprise data.
Reflection: After each tool use, the agent evaluates results to determine the next steps - asking for clarification, iterating, or generating a final response. This orchestration allows it to handle complex data queries while ensuring accuracy and compliance within Snowflake’s secure perimeter.
Monitor and iterate: After deployment, customers can track metrics, analyze performance and refine behavior for continuous improvements. On the client application developers can use TruLens to monitor the Agent interaction. By continuously monitoring and refining governance controls, enterprises can confidently scale AI agents while maintaining security and compliance.
For tutorials to help you get started, see Cortex Agents tutorials.
Note
While Snowflake strives to provide high quality responses, the accuracy of the LLM responses or the citations provided are not guaranteed. You should review all answers from the Agents API before serving them to your users.
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.
To use Cortex Agents with a semantic model, you also need the following privileges:
Privilege |
Object |
---|---|
USAGE |
The Cortex Search services mentioned in the Cortex Agents request |
USAGE |
The database, schema, and tables referenced in the Cortex Agents semantic model |
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 Required 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.
Important
If your user roles have the CORTEX_USER role, you must revoke access to the CORTEX_USER role. To revoke the CORTEX_USER database role from your user roles, run the following command using the ACCOUNTADMIN role:
REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE agent;
To provide access to Cortex Agents, use the ACCOUNTADMIN role to do the following:
Grant the SNOWFLAKE.CORTEX_AGENT_USER database role to a custom role.
Assign this custom role to users.
Note
You can’t grant database roles directly to users. For more information, see GRANT DATABASE ROLE.
The following example:
Creates the custom role,
cortex_agent_user_role
.Grants it the CORTEX_AGENT_USER database role.
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.
Important
Cortex Agents uses models that might not be available in all regions. To access these models, you will have to enable cross-region inference, if feasible. For more information, see Regional availability.
Cost considerations¶
In preview, Cortex Agents doesn’t have any cost considerations besides those associated with the underlying Cortex Search and Cortex Analyst functionality. The Cortex Search and Cortex Analyst services incur costs per the details listed in the Snowflake Service Consumption Table. Also, use of custom tools may incur warehouse costs.
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.
Thread object¶
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¶
You can use the following models with Cortex Agents for orchestration. If the model is not available in the local region, you must use cross-region inference.
llama3.1-70b
llama3.3-70b
mistral-large2
claude-3-5-sonnet
claude-3-7-sonnet
claude-4-0-sonnet
openai-gpt-5
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.
Note
The DEFAULT_ROLE of the querying user must have USAGE privilege on the Cortex Search Service, as well as the database and schema in which it resides.
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 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.
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.