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:

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

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

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

   3. Route across tools: The agent selects the right tool - Cortex Analyst or Cortex Search - to ensure governed access and compliance with enterprise policies.

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

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

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

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:

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.

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¶

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.

Models¶

You can use the following models with Cortex Agents. If the model is not available in the local region, you must use cross-region inference.

• claude-4-sonnet

• claude-3-7-sonnet

• claude-3-5-sonnet

• openai-gpt-5

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.

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.