Cortex Analyst, Agents, Search and Snowflake Intelligence Privileges

1.Cortex Analyst: CORTEX_ANALYST_USER plus semantic-model privileges

To make requests to Cortex Analyst, a role needs one of two SNOWFLAKE database roles. CORTEX_USER grants access to all Covered AI features. CORTEX_ANALYST_USER grants access to Cortex Analyst only. Use the narrower role when a group of users should be able to use Analyst and nothing else.

The narrow role only works if the broad one is removed. CORTEX_USER is granted to PUBLIC by default, and a role that still holds CORTEX_USER keeps access to every covered feature. That is why the documentation says that if your user roles have CORTEX_USER, you must revoke it, for example with REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE analyst. Then grant CORTEX_ANALYST_USER to a custom role and assign that role to users, because a database role cannot be granted to a user directly.

USE ROLE ACCOUNTADMIN;
CREATE ROLE cortex_analyst_user_role;
GRANT  ?  ROLE SNOWFLAKE.CORTEX_ANALYST_USER TO ROLE cortex_analyst_user_role;

GRANT ROLE cortex_analyst_user_role TO USER example_user;

The database role lets a user call Analyst. To answer questions over a particular semantic model, the role also needs privileges on the objects that model uses. If the semantic model YAML file is stored on a stage, you can control who can use that model by controlling access to the stage.

Sources1

2.Cortex Agents: CORTEX_AGENT_USER and the default role

Agents follow the same pattern as Analyst. To call the agent:run API, a role needs either SNOWFLAKE.CORTEX_USER, which covers all Covered AI Features, or SNOWFLAKE.CORTEX_AGENT_USER, which covers Cortex Agents only. As with Analyst, a role that keeps CORTEX_USER keeps access to everything. To restrict it to Agents, revoke CORTEX_USER from it.

Agents check the user's default role, not the role that is active in the session. Every user who calls an agent therefore needs a default role with the right privileges and a default warehouse, with USAGE on that warehouse granted to the default role. If either is missing, agent calls fail even when the current session role has every privilege. When you call the Agents REST API, you can run a request under a different role by setting the X-Snowflake-Role header. At a minimum, the default role needs these grants:

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>;
GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE <role_name>;

USAGE on the agent is not enough on its own. The default role also needs privileges on the objects each tool uses: USAGE on any Cortex Search service, USAGE on the database, schema and tables behind the semantic view, and USAGE on any custom function or stored procedure. By default (the accept mode), a missing tool privilege does not reject the whole run. The agent continues with the tools the role can access and reports the others as warnings.

Sources23

3.Cortex Search: create, query and operate

Cortex Search does not have its own CORTEX_*_USER role in these sources. Its privileges split into three jobs.

To create a service, the creator role needs access to the Cortex embedding functions, through SNOWFLAKE.CORTEX_USER or SNOWFLAKE.CORTEX_EMBED_USER. It also needs CREATE CORTEX SEARCH SERVICE (or OWNERSHIP) on the target schema, SELECT on the underlying tables or views, and USAGE on the warehouse that refreshes the service. In Snowsight, the role you pick for creating a service must be granted CORTEX_USER.

To query a service, the querying role needs USAGE on the service and on its database and schema. To suspend or resume a service with ALTER, the role needs OPERATE on the service. After you create a service, you grant query access like this:

GRANT USAGE ON DATABASE cortex_search_db TO ROLE customer_support;
GRANT USAGE ON SCHEMA services TO ROLE customer_support;

GRANT USAGE ON CORTEX SEARCH SERVICE transcript_search_service TO ROLE customer_support;

Sources4

4.Snowflake Intelligence: the agent-list object

The current documentation calls this interface Snowflake CoWork, but the SQL object type is still SNOWFLAKE INTELLIGENCE, and the default object is named SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT. It is an account-level object that holds a curated list of agents, and only one can exist in an account. If no such object exists with agents added to it, users see every agent they have access to.

Three privileges control the object. CREATE SNOWFLAKE INTELLIGENCE on the account allows creating it; ACCOUNTADMIN has this privilege by default. USAGE on the object lets users view the agent list and the configuration values. MODIFY lets users add or remove agents and change configuration values. To add an agent to the list, an administrator also needs USAGE on that agent. Granting USAGE on the object to PUBLIC makes it visible to all users.

USE ROLE ACCOUNTADMIN;
CREATE SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT;
GRANT USAGE ON SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT TO ROLE snowflake_intelligence_admin;

Seeing an agent in the list does not give a user more data access than they already have. Queries run with the user's own credentials, so all of their role-based access control and masking policies still apply. Agent privileges are configured separately, as covered in the Agents section. You can also restrict a user to this interface only with ALTER USER ... SET ALLOWED_INTERFACES = (SNOWFLAKE_INTELLIGENCE). The older SNOWFLAKE_INTELLIGENCE.AGENTS schema for controlling agent visibility is deprecated in favour of this object.

Sources5

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Granting CORTEX_ANALYST_USER to a role limits that role to Cortex Analyst.Why is that wrong?

   If the role still holds CORTEX_USER, either directly or through PUBLIC, it keeps access to every covered feature. Revoke CORTEX_USER to actually restrict it.

   Covered in Cortex Analyst: CORTEX_ANALYST_USER plus semantic-model privileges

2. 2.Switching to a privileged role with USE ROLE is enough to call a Cortex Agent.Why is that wrong?

   Agents take their permissions from the user's default role, so the default role must hold the privileges.

   Covered in Cortex Agents: CORTEX_AGENT_USER and the default role

3. 3.USAGE on the agent lets a user use all of the agent's tools.Why is that wrong?

   The default role also needs privileges on each tool's objects, such as Search services, semantic-view tables, and functions or procedures.

   Covered in Cortex Agents: CORTEX_AGENT_USER and the default role

Practise it for real

Limit Cortex Agents to one group of users and make sure their calls succeed.

1. 1.As ACCOUNTADMIN, run REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE PUBLIC;

   Why: CORTEX_USER is granted to PUBLIC by default and would otherwise give everyone access to every covered feature.

   You should see: Roles that relied on PUBLIC lose Cortex access.

2. 2.CREATE ROLE cortex_agent_user_role; then GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE cortex_agent_user_role;

   Why: Database roles cannot be granted to users, so you need an account role to carry the grant.

   You should see: The role can call Cortex Agents and no other Cortex feature.

3. 3.Grant USAGE on the agent's database, schema, agent and a warehouse to cortex_agent_user_role, then GRANT ROLE cortex_agent_user_role TO USER example_user;

   Why: The role needs privileges on the agent object and a warehouse to run the agent's queries.

   You should see: SHOW GRANTS TO ROLE cortex_agent_user_role lists the USAGE grants.

4. 4.Set the role as the user's default role, for example ALTER USER my_user SET DEFAULT_ROLE=my_role, and set a default warehouse that the role has USAGE on.

   Why: Agents take their permissions from the default role and need a default warehouse.

   You should see: Agent calls from example_user succeed even if their session role is different.