CertSafari
    Snowflake SnowPro Specialty: Gen AI (GES-C02)· Lessons

    Domain 2 · Lesson 5/15

    Chat with data in Snowflake: privileges, multi-turn messages, agents and Snowflake Intelligence

    Build or interact with interfaces to chat with data in Snowflake.

    21 min read
    7.6% of exam
    11 sources
    Published 21 Oct 2026
    Docs as of 18 Oct 2026

    What you will be able to do

    • Pick the least-privileged database role and object grants a chat app's role needs to call Cortex Analyst or a Cortex Agent
    • Explain why an agent's tools need privileges granted to the caller's role, and what happens when one is missing
    • Build a multi-turn conversation by resending role-tagged history in the messages array, and explain why its cost grows each turn
    • Describe the plan, use tools, reflect loop of a Cortex Agent and continue a conversation with threads using parent_message_id
    • Set up Snowflake Intelligence for business users: the account-level object, its privileges, and which agents users see

    Key concept

    Cortex Agent — A reusable Snowflake object that bundles a model, tools and instructions. For each request it plans, calls tools such as Cortex Analyst and Cortex Search, and reflects on the results before answering. Every tool runs under the caller's roles, so what a chat user can get back depends on what their role is allowed to touch.

    1.Roles that let a chat app call Cortex Analyst and Cortex Agents

    A chat-with-data app is a thin front end over Cortex services. It might be a Streamlit in Snowflake page or a web app outside Snowflake, and Snowflake checks every call it makes against one role. Setting up the environment comes down to choosing that role and giving it what each service checks for, and nothing else. For the AI functions themselves, such as AI_COMPLETE, the role must pass the two gates: USE AI FUNCTIONS privilege and the SNOWFLAKE.CORTEX_USER database role. This section is about the database roles for the chat services that sit on top of those gates.

    SNOWFLAKE.CORTEX_USER is the broad role. It covers every Covered AI Feature, and by default it is granted to PUBLIC, so in an untouched account every user already has it. Each chat-relevant service also has its own narrower role (covered in Feature privileges: CORTEX_ANALYST_USER, CORTEX_AGENT_USER, Cortex Search and the Snowflake Intelligence object), and least privilege means granting that narrow role:

    • SNOWFLAKE.CORTEX_ANALYST_USER gives access to Cortex Analyst only.
    • SNOWFLAKE.CORTEX_AGENT_USER gives access to Cortex Agents only.
    • SNOWFLAKE.AI_FUNCTIONS_USER covers the scalar AI functions but not services such as Cortex Agent, Cortex Analyst or Cortex Search. It suits a chat app that only calls AI_COMPLETE.

    Database roles can't be granted to a user directly. Grant the database role to a custom role, then grant that custom role to the app's service user. The narrow grant only restricts anything once the broad one is gone: a role that still holds CORTEX_USER, directly or through PUBLIC, keeps access to every Covered AI Feature. ACCOUNTADMIN and SYSADMIN are administrative roles. They are the wrong answer when the question is the minimum a user needs to run Analyst or an agent.

    An agent has object grants on top of the database role. The calling role needs USAGE on the agent, on the database and schema that contain it, and on each warehouse configured for the agent's tools.

    Minimum object grants for a role that calls an agentsql
    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>;

    Checkpoint 1 of 9· Fill the gap

    A custom role will call a Cortex Agent from a chat app. Which privilege completes the minimum grant on the agent itself?

    GRANT USAGE ON DATABASE <database_name> TO ROLE <role_name>;
    GRANT USAGE ON SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;
    GRANT  ?  ON AGENT <database_name>.<schema_name>.<agent_name> TO ROLE <role_name>;
    GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE <role_name>;

    Checkpoint 2 of 9· Exam question

    Which database role provides the minimum privileges required for a user to invoke Cortex Analyst, following the principle of least privilege?

    Sources123

    2.An agent's tools run with the caller's privileges

    An agent doesn't borrow its owner's rights. It uses the caller's session roles, so USAGE on the agent isn't enough by itself. The role also needs USAGE on each Cortex Search service the agent is configured with, along with the database and schema that hold it. It needs access to the objects behind the agent's semantic view, and USAGE on any function or stored procedure used as a custom tool. Stored procedures are the exception that follows its own rule: each one runs with owner's rights or caller's rights, whichever the procedure defines.

    Cortex Analyst behaves the same way, whether the app calls it directly or the agent calls it as a tool (Cortex Analyst over semantic views). The feature role lets the request through. The semantic model then decides which further grants apply:

    Privileges Cortex Analyst needs beyond its database role
    PrivilegeObjectFailure when missing
    READ or WRITEStage that contains the semantic model YAML file, if the model is on a stageUsers who hold CORTEX_ANALYST_USER still get insufficient-privileges errors, because the model file can't be read
    USAGECortex Search services mentioned in the semantic modelLookups against those search services fail
    SELECTTables mentioned in the semantic modelAnalyst still generates SQL, but running that SQL fails for the user

    Each failure points to its own fix. A missing SELECT on a fact table is fixed by granting SELECT on that table to the user's role. Swapping the user's role for CORTEX_USER doesn't help, because no Cortex role gives access to table data. Re-uploading the YAML under a more powerful owner doesn't help either. A stage error is fixed by granting READ on the stage. Storing a model on a stage is in fact how you limit who can use it: you control access to that stage. Revoking or granting IMPORTED PRIVILEGES on the SNOWFLAKE database is a different matter. It mainly affects shared objects such as ACCOUNT_USAGE views. Stage-based YAML models are the legacy option, and semantic views are recommended for new work.

    Silent degradation in accept mode is easy to miss. A user without access to the search service just gets a weaker answer, along with a warning the app might never show. If a partial answer is worse than an error for your app, set orchestration.tool_not_accessible to reject so the run fails instead.

    Checkpoint 3 of 9· Check yourself

    Your compliance team says a chat user should never get a partial answer. If their role can't reach one of the agent's tools, the request must fail. What do you change?

    Checkpoint 4 of 9· Exam question

    A team builds a Streamlit in Snowflake app that calls Cortex Analyst using a semantic model YAML file stored in an internal stage. Business users already hold the CORTEX_ANALYST_USER role but still get "insufficient privileges" errors when submitting questions. What is the most likely missing grant?

    Checkpoint 5 of 9· Exam question

    A semantic model used by a chat-with-data app references a fact table that the calling role cannot query. Cortex Analyst returns generated SQL, but running it fails for the end user. What should be corrected?

    Sources21

    3.Multi-turn chat: the messages array carries the history

    The completion functions keep no memory between calls. COMPLETE, and its successor AI_COMPLETE, start every call from scratch. To hold a conversation, the app keeps the history itself and sends all of it on every turn: each earlier user prompt and each earlier model response, as an array of role-tagged objects in chronological order.

    Roles allowed in the COMPLETE conversation array
    rolecontentOrdering rule
    systemBackground instructions and response style; the model does not reply to itAt most one, and it must be first
    userA prompt from the userMust follow the system prompt or an assistant response
    assistantA response the model gave earlierMust follow a user prompt

    The options argument decides which form the call takes. Without options, the second argument must be a plain prompt string. With options, even an empty {}, it must be the conversation array, and the result is a JSON string with choices, created, model and a usage object that counts prompt and completion tokens. A chat app therefore always passes options, even if only to get the history form and the token counts.

    Resending everything has a price. Turn ten sends the nine turns before it again, so the tokens processed grow each round and cost grows with them. A long conversation can also run past the model's limit. Use the usage.prompt_tokens value from each reply, or the AI_COUNT_TOKENS helper before a call, to see when the history is getting too long. Then drop or summarize the oldest turns while keeping the system prompt at the front.

    Cortex Analyst also takes its history in a messages field, but with different role names. Earlier questions use the role user, and earlier answers use analyst. User messages contain only text, while analyst messages contain both a text block and a sql block with the generated statement.

    SQL AI functions are built for throughput across many table rows. An interactive chat window cares more about latency, so the REST API is the better fit there. Calling the Cortex REST APIs from app code means building the JSON request yourself, reading the response as it streams back, and keeping the conversation state in the client.

    Checkpoint 6 of 9· Check yourself

    On the second turn of a Streamlit in Snowflake chat, the app calls COMPLETE with the options argument and an array that holds only the user's newest question. The question is a follow-up: "What about last year?" What happens?

    Sources4561

    4.Cortex Agents: plan, use tools, reflect

    A Cortex Agent saves you from writing your own orchestration loop. You define the agent once, as a schema-level object that bundles its model, tools and instructions. You can create it in Snowsight, with SQL commands, or through the REST API, and you call it through the REST API. Snowflake recommends auto for the model, which lets Cortex choose the highest-quality model available to the account.

    For each request the agent runs a three-step loop. It plans: it works out what the question means, splits a compound question into subtasks, and picks a tool for each one. It uses tools: Cortex Analyst for structured data, Cortex Search for unstructured text, or the code execution tool to process results. It reflects: it looks at what each tool returned and decides whether to ask a clarifying question, call another tool, or write the final answer. It can go round this loop several times within one request.

    The tools decide what the agent can reach. Analyst turns metric questions into SQL over semantic views, and Search pulls passages from documents. Beyond those, an agent can use:

    • a code execution tool that runs Python in an isolated sandbox
    • a Data to Chart tool that turns data into visualizations
    • custom tools built from stored procedures and UDFs
    • MCP connectors that call tools on remote MCP servers
    • web search for public, real-time information

    An agent with no tools can still chat, but it answers only from the model's general knowledge and can't query anything in the account. That is why the tool configuration, and the privileges behind it, is what turns a chatbot into chat with data. A run is one request to /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run. There is also /api/v2/cortex/agent:run for calls made without an agent object. No stored agent supplies the configuration on that endpoint, so the request is stateless and carries the model name itself, in a model field next to messages. During a run the agent streams events that show its reasoning, tool calls and reflections.

    Checkpoint 7 of 9· Check yourself

    An agent object ANALYTICS.CHAT.SALES_AGENT already bundles the model, tools and instructions that a chat front end needs. How does the app run a request against that defined agent?

    Sources78

    5.Threads keep agent conversation state on the server

    With threads, the agent stores the conversation history instead of your app. A thread is its own object: you create it first with the Create thread endpoint, before any agent:run request. The ID of that newly created thread is the thread_id you pass on each agent:run request. On the first turn, parent_message_id is 0 and messages holds exactly one user message. The response streams metadata events that carry the stored IDs of both the user message and the assistant message, so listen for both.

    On each later turn, send only the new user message and set parent_message_id to the ID of the last successful assistant message. It must be an assistant message ID; a user message ID is not allowed. If the app loses track of the ID, the Describe thread endpoint lists every message in the thread.

    Second turn of a thread: only the new question is sent, anchored to the assistant message 456json
    {
      "thread_id": 1234,
      "parent_message_id": 456,
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "What about last year?"
            }
          ]
        }
      ]
    }

    Threads also take care of growth. When a thread gets long, Cortex Agents compacts older turns into a summary message stored with message_type compaction. To rebuild recent state, fetch the newest compaction message, then every conversation message whose ID is greater than the summary's. Message IDs only ever increase, so comparing IDs gives you time order.

    Checkpoint 8 of 9· Fill the gap

    The first turn of thread 1234 streamed two metadata events: user message_id 123 and assistant message_id 456. The app now sends the follow-up question. Which value completes the request body?

    {
      "thread_id": 1234,
      "parent_message_id":  ? ,
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "What about last year?"
            }
          ]
        }
      ]
    }

    Sources9

    6.Snowflake Intelligence: the packaged chat-with-data experience

    Snowflake Intelligence is the answer when business users need to chat with data and nobody should build or maintain a custom app. It is a ready-made agentic application. Users ask questions in natural language, the question goes to the Cortex Agent API, and the agent answers with text, tables or charts that trace back to source data and queries. The documentation now uses the name Snowflake CoWork for this product, while the SQL object keeps the SNOWFLAKE INTELLIGENCE keyword. If a user wants to keep their own chat client instead, the Snowflake-managed MCP server is a way to connect it to Snowflake data without a custom app.

    Admins decide which agents users see through one account-level object that holds a list of agents. An account can have only one, and when it is created in Snowsight it is named SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT. Without the object, users see every agent they have access to. Once the object exists, an agent must be added to it with ALTER SNOWFLAKE INTELLIGENCE ... ADD AGENT to show up. Creating an agent doesn't add it.

    Privileges on the Snowflake Intelligence object
    PrivilegeWhat it allowsDefault holder
    CREATE SNOWFLAKE INTELLIGENCE (on account)Create the objectACCOUNTADMIN
    USAGE (on the object)See the list of agents in the object and its configuration valuesGranted explicitly, for example to PUBLIC to make it visible to everyone
    MODIFY (on the object)Add or remove agents and change configuration valuesAccount administrators
    Creating the object and letting a role see itsql
    USE ROLE ACCOUNTADMIN;
    CREATE SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT;
    GRANT USAGE ON SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT TO ROLE snowflake_intelligence_admin;

    A team lead who should manage the agent list, and do nothing else as an admin, needs MODIFY on the object. ACCOUNTADMIN would be far too much. Users also still need the agent privileges from the sections above, because every query from Snowflake Intelligence runs with the user's own credentials, and their role-based access and masking policies apply. A session starts with the user's default role and default warehouse, so set both before inviting people. Otherwise their first questions run under the wrong role, or with no warehouse at all.

    Two details separate the packaged experience from calling agents directly. First, you can lock a user into it: ALTER USER <user_name> SET ALLOWED_INTERFACES = (SNOWFLAKE_INTELLIGENCE); limits that user to Snowflake Intelligence. Second, user memory, such as a saved preference for concise answers, applies only inside Snowflake Intelligence. It has no effect on calls your own app makes to the Cortex Agent API.

    Checkpoint 9 of 9· Check yourself

    Through Snowflake Intelligence, a regional manager asks an agent for customer revenue. A SYSADMIN-owned role owns the agent. The customer table has a row access policy that limits the manager's role to their own region, and a masking policy on email. What does the manager get back?

    Sources1011

    Sources

    (11)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “CORTEX_USER provides access to all Covered AI features, while CORTEX_ANALYST_USER provides access only to Cortex Analyst.”
      ↩︎ Roles that let a chat app call Cortex Analyst and Cortex Agents
      “Stage that contains the semantic model YAML file, if the semantic model is uploaded to a stage.”
      ↩︎ An agent's tools run with the caller's privileges
      “The tables mentioned in the semantic model.”
      ↩︎ An agent's tools run with the caller's privileges
      “To control access to specific semantic models, you can store the YAML file in a stage and control access to that stage.”
      ↩︎ An agent's tools run with the caller's privileges
      “Legacy semantic model YAML files (stored on stages) are still supported for backward compatibility, but Semantic Views are the recommended approach for new implementations.”
      ↩︎ An agent's tools run with the caller's privileges
      “Analyst responses have both text and SQL responses, as shown in the example above, while user messages have only text.”
      ↩︎ Multi-turn chat: the messages array carries the history
      “CORTEX_USER provides access to all Covered AI features, while CORTEX_ANALYST_USER provides access only to Cortex Analyst.”
      ↩︎ Exam trap 1
    2. 2.
      “SNOWFLAKE.CORTEX_AGENT_USER: Grants access to Cortex Agents only.”
      ↩︎ Roles that let a chat app call Cortex Analyst and Cortex Agents
      “Database roles can’t be granted directly to users”
      ↩︎ Roles that let a chat app call Cortex Analyst and Cortex Agents
      “A role that also has the CORTEX_USER database role retains access to all Covered AI Features.”
      ↩︎ Roles that let a chat app call Cortex Analyst and Cortex Agents
      “The role used to authorize the request comes from the X-Snowflake-Role header, or from the user’s default role if the header is omitted.”
      ↩︎ Roles that let a chat app call Cortex Analyst and Cortex Agents
      “Because the agent uses the caller’s session roles, those roles also need privileges on the objects used by the agent’s tools”
      ↩︎ An agent's tools run with the caller's privileges
      “Stored procedures run with owner’s rights or caller’s rights as defined on the procedure.”
      ↩︎ An agent's tools run with the caller's privileges
      “it also removes PUBLIC’s access to other objects in the shared SNOWFLAKE database, such as ACCOUNT_USAGE views.”
      ↩︎ An agent's tools run with the caller's privileges
      “Set orchestration.tool_not_accessible to reject or legacy if you want the run to fail instead.”
      ↩︎ An agent's tools run with the caller's privileges
      “USAGE on the agent isn’t sufficient on its own.”
      ↩︎ Exam trap 2
      “By default (accept), a missing privilege on a configured tool doesn’t reject the entire run.”
      ↩︎ Prediction
    3. 3.
      “without granting access to Cortex services such as Cortex Agent, Cortex Analyst, Cortex Fine-tuning, or Cortex Search.”
      ↩︎ Roles that let a chat app call Cortex Analyst and Cortex Agents
    4. 4.
      “COMPLETE does not retain any state from one call to the next.”
      ↩︎ Multi-turn chat: the messages array carries the history
      “Only one system prompt may be provided, and if it is present, it must be the first in the array.”
      ↩︎ Multi-turn chat: the messages array carries the history
      “affects how the prompt argument is interpreted and how the response is formatted.”
      ↩︎ Multi-turn chat: the messages array carries the history
      “Keep in mind that the number of tokens processed increases for each “round,” and costs increase proportionally.”
      ↩︎ Multi-turn chat: the messages array carries the history
      “COMPLETE does not retain any state from one call to the next.”
      ↩︎ Exam trap 3
    5. 6.
      “by getting the count of tokens in an input prompt to ensure the call doesn’t exceed a model limit”
      ↩︎ Multi-turn chat: the messages array carries the history
      “For more interactive use cases where latency is important, use the REST API.”
      ↩︎ Multi-turn chat: the messages array carries the history
    6. 7.
      “You define an agent as a reusable object that bundles its model, tools, and orchestration instructions.”
      ↩︎ Cortex Agents: plan, use tools, reflect
      “The agent repeats this loop as needed within a single request.”
      ↩︎ Cortex Agents: plan, use tools, reflect
      “They generate SQL over structured data using Cortex Analyst semantic views and use Cortex Search to retrieve insights from unstructured sources”
      ↩︎ Cortex Agents: plan, use tools, reflect
      “An agent with no tools configured can still hold a conversation, but it answers only from the language model’s general knowledge”
      ↩︎ Cortex Agents: plan, use tools, reflect
      “The agent emits events throughout the run that surface its reasoning, tool calls, and reflections.”
      ↩︎ Cortex Agents: plan, use tools, reflect
      “An agent reasons over a request, plans the work, calls tools, executes code, and generates a response”
      ↩︎ Key concept
    7. 8.
      “inline to the stateless agent:run endpoint, without persisting an agent”
      ↩︎ Cortex Agents: plan, use tools, reflect
    8. 9.
      “parent_message_id must be 0. This indicates that this request is the start of the thread.”
      ↩︎ Threads keep agent conversation state on the server
      “Create a new thread using Create thread.”
      ↩︎ Threads keep agent conversation state on the server
      “Pass the ID of the newly created thread as part of a request to one of the agent:run REST API endpoints.”
      ↩︎ Threads keep agent conversation state on the server
      “Always listen for both user and assistant metadata events.”
      ↩︎ Threads keep agent conversation state on the server
      “You must pass an assistant message ID as the parent_message_id to ensure the LLM functions as expected.”
      ↩︎ Threads keep agent conversation state on the server
      “Cortex Agents periodically compacts older turns into a summary message and stores it in the thread with a message type of compaction.”
      ↩︎ Threads keep agent conversation state on the server
      “You can also fork the conversation by continuing from any earlier assistant message.”
      ↩︎ Threads keep agent conversation state on the server
      “You must pass an assistant message ID as the parent_message_id to ensure the LLM functions as expected.”
      ↩︎ Exam trap 4
      “agent:run with Agent Object: Copy code/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run”
      ↩︎ Checkpoint
    9. 10.
      “Snowflake CoWork is a ready-to-use agentic application with an intuitive, conversational interface that helps business users discover and act on deep insights.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “The question is routed to the Cortex Agent API, which powers Snowflake CoWork.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “User memory applies only to interactions in Snowflake CoWork, not to direct calls to agents through the Cortex Agent API.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “Automatically inherits and respects all existing Snowflake data governance controls, including row-access policies and column-level security.”
      ↩︎ Checkpoint
    10. 11.
      “The Snowflake CoWork object is an account-level object that contains a list of agents.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “users automatically see all agents they have access to in your account.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “agents are not automatically added to the Snowflake CoWork object”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “Privilege that allows users to add or remove agents from the Snowflake CoWork object and change configuration values.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “All of the queries from Snowflake CoWork use the user’s credentials.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “Snowflake CoWork initializes the user session with the default role and default warehouse.”
      ↩︎ Snowflake Intelligence: the packaged chat-with-data experience
      “This privilege is granted to ACCOUNTADMIN by default.”
      ↩︎ Exam trap 5

    Spotted a mistake, or was something unclear? Tell us.