AI Data Agent Guide 2025: Snowflake Cortex Tutorial

The world of data analytics is changing. For years, accessing insights required writing complex SQL queries. However, the industry is now shifting towards a more intuitive, conversational approach. At the forefront of this revolution is agentic AI—intelligent systems that can understand human language, reason, plan, and automate complex tasks.

Snowflake is leading this charge by transforming its platform into an intelligent and conversational AI Data Cloud. With the recent introduction of Snowflake Cortex Agents, they have provided a powerful tool for developers and data teams to build their own custom AI assistants.

This guide will walk you through, step-by-step, how to build your very first AI data agent. You will learn how to create an agent that can answer complex questions by pulling information from both your database tables and your unstructured documents, all using simple, natural language.

What is a Snowflake Cortex Agent and Why Does it Matter?

First and foremost, a Snowflake Cortex Agent is an AI-powered assistant that you can build on top of your own data. Think of it as a chatbot that has expert knowledge of your business. It understands your data landscape and can perform complex analytical tasks based on simple, conversational prompts.

This is a game-changer for several reasons:

• It Democratizes Data: Business users no longer need to know SQL. Instead, they can ask questions like, “What were our top-selling products in the last quarter?” and get immediate, accurate answers.
• It Automates Analysis: Consequently, data teams are freed from writing repetitive, ad-hoc queries. They can now focus on more strategic initiatives while the agent handles routine data exploration.
• It Provides Unified Insights: Most importantly, a Cortex Agent can synthesize information from multiple sources. It can query your structured sales data from a table and cross-reference it with strategic goals mentioned in a PDF document, all in a single response.

The Blueprint: How a Cortex Agent Works

Under the hood, a Cortex Agent uses a simple yet powerful workflow to answer your questions. It orchestrates several of Snowflake’s Cortex AI features to deliver a comprehensive answer.

1. Planning: The agent first analyzes your natural language question to understand your intent. It figures out what information you need and where it might be located.
2. Tool Use: Next, it intelligently chooses the right tool for the job. If it needs to query structured data, it uses Cortex Analyst to generate and run SQL. If it needs to find information in your documents, it uses Cortex Search.
3. Reflection: Finally, after gathering the data, the agent evaluates the results. It might ask for clarification, refine its approach, or synthesize the information into a clear, concise answer before presenting it to you.

Step-by-Step Tutorial: Building a Sales Analysis Agent

Now, let’s get hands-on. We will build a simple yet powerful sales analysis agent. This agent will be able to answer questions about sales figures from a table and also reference goals from a quarterly business review (QBR) document.

Prerequisites

• A Snowflake account with ACCOUNTADMIN privileges.
• A warehouse to run the queries.

Step 1: Prepare Your Data

First, we need some data to work with. Let’s create two simple tables for sales and products, and then upload a sample PDF document.

Run the following SQL in a Snowflake worksheet:

-- Create our database and schema
CREATE DATABASE IF NOT EXISTS AGENT_DEMO;
CREATE SCHEMA IF NOT EXISTS AGENT_DEMO.SALES;
USE SCHEMA AGENT_DEMO.SALES;

-- Create a products table
CREATE OR REPLACE TABLE PRODUCTS (
    product_id INT,
    product_name VARCHAR,
    category VARCHAR
);

INSERT INTO PRODUCTS (product_id, product_name, category) VALUES
(101, 'Quantum Laptop', 'Electronics'),
(102, 'Nebula Smartphone', 'Electronics'),
(103, 'Stardust Keyboard', 'Accessories');

-- Create a sales table
CREATE OR REPLACE TABLE SALES (
    sale_id INT,
    product_id INT,
    sale_date DATE,
    sale_amount DECIMAL(10, 2)
);

INSERT INTO SALES (sale_id, product_id, sale_date, sale_amount) VALUES
(1, 101, '2025-09-01', 1200.00),
(2, 102, '2025-09-05', 800.00),
(3, 101, '2025-09-15', 1250.00),
(4, 103, '2025-09-20', 150.00);

-- Create a stage for our unstructured documents
CREATE OR REPLACE STAGE qbr_documents;

Now, create a simple text file named QBR_Report_Q3.txt on your local machine with the following content and upload it to the qbr_documents stage using the Snowsight UI.

Quarterly Business Review – Q3 2025 Summary

Our primary strategic goal for Q3 was to drive the adoption of our new flagship product, the ‘Quantum Laptop’. We aimed for a sales target of over $2,000 for this product. Secondary goals included expanding our market share in the accessories category.

Step 2: Create the Semantic Model

Next, we need to teach the agent about our structured data. We do this by creating a Semantic Model. This is a YAML file that defines our tables, columns, and how they relate to each other.

# semantic_model.yaml
model:
  name: sales_insights_model
  tables:
    - name: SALES
      columns:
        - name: sale_id
          type: INT
        - name: product_id
          type: INT
        - name: sale_date
          type: DATE
        - name: sale_amount
          type: DECIMAL
    - name: PRODUCTS
      columns:
        - name: product_id
          type: INT
        - name: product_name
          type: VARCHAR
        - name: category
          type: VARCHAR
  joins:
    - from: SALES
      to: PRODUCTS
      on: SALES.product_id = PRODUCTS.product_id

Save this as semantic_model.yaml and upload it to the @qbr_documents stage.

Step 3: Create the Cortex Search Service

Now, let’s make our PDF document searchable. We create a Cortex Search Service on the stage where we uploaded our file.

CREATE OR REPLACE CORTEX SEARCH SERVICE sales_qbr_service
    ON @qbr_documents
    TARGET_LAG = '0 seconds'
    WAREHOUSE = 'COMPUTE_WH';

Step 4: Combine Them into a Cortex Agent

With all the pieces in place, we can now create our agent. This single SQL statement brings together our semantic model (for SQL queries) and our search service (for document queries).

CREATE OR REPLACE CORTEX AGENT sales_agent
    MODEL = 'mistral-large',
    CORTEX_SEARCH_SERVICES = [sales_qbr_service],
    SEMANTIC_MODELS = ['@qbr_documents/semantic_model.yaml'];

Step 5: Ask Your Agent Questions!

The agent is now ready! You can interact with it using the CALL command. Let’s try a few questions.

First up: A simple structured data query.

CALL sales_agent('What were our total sales?');

Next: A more complex query involving joins.

CALL sales_agent('Which product had the highest revenue?');

Then comes: A question for our unstructured document.

CALL sales_agent('Summarize our strategic goals from the latest QBR report.');

Finally , the magic: The magic! A question that combines both.

CALL sales_agent('Did we meet our sales target for the Quantum Laptop as mentioned in the QBR?');

This final query demonstrates the true power of a Snowflake Cortex Agent. It will first query the SALES and PRODUCTS tables to calculate the total sales for the “Quantum Laptop.” Then, it will use Cortex Search to find the sales target mentioned in the QBR document. Finally, it will compare the two and give you a complete, synthesized answer.

Conclusion: The Future is Conversational

You have just built a powerful AI data agent in a matter of minutes. This is a fundamental shift in how we interact with data. By combining natural language processing with the power to query both structured and unstructured data, Snowflake Cortex Agents are paving the way for a future where data-driven insights are accessible to everyone in an organization.

As Snowflake continues to innovate with features like Adaptive Compute and Gen-2 Warehouses, running these AI workloads will only become faster and more efficient. The era of conversational analytics has arrived, and it’s built on the Snowflake AI Data Cloud.

---

Additional materials

• Official Snowflake Blog: Announcing Cortex AI
• Snowflake Docs: Getting Started with Cortex Agents
• Quickstart: Build a Document Chatbot with Cortex Search
• Medium: Developer’s Guide to Snowflake Cortex Agent