Every organization sits on two kinds of data: structured data (numbers in tables like sales figures, inventory counts, and transaction logs) and unstructured data (text in documents like product manuals, troubleshooting guides, and policy documents). Traditionally, getting answers from these two worlds required completely different tools and skills. Want to know last quarter's revenue? Write a SQL query. Need to find the assembly instructions for a product? Search through a document repository. Want both in one conversation? Good luck stitching those workflows together manually.

This is the problem AI agents solve. An AI agent doesn't just generate text like a basic LLM call. It reasons about your question, decides which tool to use, executes that tool, and synthesizes the results into a coherent answer. Ask it "What are total sales by region?" and it routes to a SQL engine. Ask it "How do I fix laptop overheating?" and it searches your documentation. Ask both in the same conversation, and it handles each seamlessly.

Cortex Agents bring this capability directly into Snowflake. You don't need to set up external orchestration frameworks, manage API keys for third-party services, or write complex routing logic. Everything (the agent, its tools, and the data it accesses) lives inside your Snowflake account, governed by the same roles and permissions you already use.

In this guide, you'll build an end-to-end pipeline from scratch, starting with the data. You'll create and load sample data into tables, create a semantic view that lets the agent translate natural language into SQL, build a Cortex Search service that lets it retrieve relevant documentation, and wire both into a Cortex Agent that answers questions about sales data and product documentation, all with standard SQL.

A Cortex Agent with two tools:

The agent automatically decides which tool to use based on what the user asks. You don't write any routing logic; the agent figures it out.

Before building anything, you need a workspace in Snowflake to hold all the objects you'll create (tables, semantic views, search services, and the agent itself). Think of a database as a top-level folder and a schema as a subfolder within it.

You'll also verify that Cortex AI is available on your account, since the agent depends on it.

You can run all the SQL in this guide in either:

Copy and paste the following SQL and run it. Each line is explained below:

What each command does:

Before going further, confirm that Cortex AI is working on your account. Run this simple test that asks an LLM to respond:

What this does: SNOWFLAKE.CORTEX.COMPLETE() is a built-in function that sends a prompt to an LLM and returns the response. Here, we're using claude-3-5-sonnet as the model. If it returns something like "Hello", you're all set.

If you get an error: Cortex AI may not be enabled in your account's region. Check the Cortex AI availability documentation for supported regions.

Now you'll create the data that your agent will work with. You need two types:

1. Structured data (a sales table with numbers and categories) that Cortex Analyst will query with SQL
2. Unstructured data (product documentation as free-form text) that Cortex Search will index and retrieve

You'll also create an inventory table that's useful for exploring the data, though the agent in this tutorial focuses on sales and documentation.

This table represents transaction-level sales data for a retail business. Each row is one sale, with information about what was sold, where, for how much, and to what type of customer.

What this creates: 12 sales transactions across 3 regions (North America, Europe, Asia Pacific), 2 categories (Electronics, Furniture), and 3 customer segments (Enterprise, SMB, Consumer). The AUTOINCREMENT on sale_id means Snowflake automatically assigns an incrementing ID to each row.

Quick check: Preview the data to see what you loaded:

This table tracks stock levels for each product. It's not directly used by the agent in this tutorial, but it's included so you can explore the data and potentially extend the agent later.

This is the unstructured data that Cortex Search will index. Each row contains a text document about a product, covering things like specifications, troubleshooting guides, assembly instructions, and care tips.

Unlike the sales table (which has clean numeric columns you can aggregate), this data is free-form text that requires semantic search to be useful.

What this creates: 6 documents covering 3 products. Notice the content column: it contains plain English text, not structured data. This is exactly the kind of data that's hard to query with SQL (you can't SUM or GROUP BY a paragraph of text) but perfect for semantic search.

Run this query to confirm all three tables loaded correctly:

Expected results: 12 sales rows, 6 inventory rows, and 6 product docs rows. If any count is off, re-run the INSERT statements for that table.

Now you'll create the first tool the agent will use: Cortex Analyst, which converts natural language questions into SQL queries.

But there's a challenge: how does an LLM know that "revenue" means SUM(total_amount) or that "region" refers to the region column? It doesn't, unless you tell it. That's what a semantic view does.

A semantic view is a layer on top of your table that defines the business meaning of your data:

Think of it as a data dictionary that the LLM reads to write correct SQL.

Semantic views are defined with SQL using TABLES, DIMENSIONS, and METRICS clauses. Run the following:

Breaking this down:

Confirm the semantic view was created:

You should see SALES_SEMANTIC_VIEW in the results.

Before wiring it into the agent, query the semantic view directly to make sure it works. This is a good debugging practice: if the semantic view doesn't return correct data, the agent won't either.

What this does: Uses the SEMANTIC_VIEW() function to query the view just like a table, but using the business names you defined (e.g., total_sales instead of SUM(total_amount)). You should see sales totals broken down by region.

To see the natural-language-to-SQL translation in action, try asking an LLM to write a query based on the schema:

Why this matters: This is essentially what Cortex Analyst does under the hood. It takes your natural language question, reads the semantic view's definitions, and generates a SQL query. The semantic view just makes it far more accurate by giving the LLM explicit business context instead of making it guess.

Now you'll create the second tool: Cortex Search, which enables the agent to find relevant product documentation using semantic search.

Traditional SQL search requires exact matches. WHERE content LIKE '%overheating%' only finds documents containing that exact word. But what if a user asks "my laptop is getting too hot"? A LIKE query would miss the troubleshooting document because it uses the word "overheating," not "too hot."

Semantic search understands the meaning behind words. It converts text into numerical vectors (embeddings) and finds documents that are conceptually similar to the query, even if they use different words.

Retrieval-Augmented Generation (RAG) is the pattern where you:

1. Retrieve relevant documents using search
2. Augment an LLM prompt with those documents as context
3. Generate an answer grounded in the retrieved information

Cortex Search handles the retrieval step. The agent handles the augmentation and generation steps automatically.

Run the following to create a search service that indexes your product documentation:

Breaking this down:

Confirm the service was created:

You should see PRODUCT_SEARCH_SERVICE in the results. Note: the service takes a moment to build the initial index.

Now test it by searching for troubleshooting information about laptop overheating. This uses the SEARCH_PREVIEW function, which returns results as JSON:

What's happening here (inside out):

1. SEARCH_PREVIEW() sends the query "laptop overheating fix" to the search service and returns matching documents as a JSON string
2. PARSE_JSON() converts the JSON string into a Snowflake VARIANT object
3. ['results'] extracts the results array from the JSON
4. TABLE(FLATTEN(...)) expands the JSON array into rows (one row per search result)
5. r.value:product_name::STRING extracts specific fields from each result

You should see the Laptop Pro troubleshooting document returned, even though the search query ("laptop overheating fix") doesn't exactly match the document text.

To see the full RAG pattern in action, take the search results and feed them into an LLM to generate an answer:

What this does: Retrieves the top 2 documents matching "laptop overheating," concatenates their content together using LISTAGG, then passes that as context to the LLM along with the question. The LLM's answer is grounded in your actual product documentation rather than its general training data.

This is exactly the pattern the Cortex Agent automates. It decides when to search, what to search for, and how to present the results, all without you having to write this query manually each time.

You've now built both tools independently:

Now you'll create a Cortex Agent that sits on top of both tools and automatically routes each question to the right one. The agent is the orchestration layer that reads the user's question, decides which tool to call, executes it, and synthesizes a final answer.

When you ask the agent a question, here's what happens behind the scenes:

1. Thinking: the agent's LLM reads your question and decides which tool is most appropriate
2. Tool call: the agent invokes the chosen tool (Analyst for SQL queries, Search for document retrieval)
3. Tool result: the tool returns its results (SQL + data, or matching documents)
4. Answer: the agent synthesizes the tool's results into a natural language response

All of this happens in a single call. You don't need to build this orchestration logic yourself.

The CREATE AGENT ... FROM SPECIFICATION command defines everything about the agent in a single YAML spec embedded in SQL. Run the following:

Breaking down the YAML spec section by section:

models specifies which LLM the agent uses for reasoning and tool selection:

orchestration sets resource limits to prevent runaway queries:

instructions contains three types of instructions that shape the agent's behavior:

tools declares what tools are available. Each tool has:

tool_resources connects each tool to its underlying data source:

Confirm the agent was created:

You should see TUTORIAL_AGENT listed. The agent is now a first-class Snowflake object, just like a table or view.

Now that the agent exists, you'll test it by asking questions and examining the full response to understand what's happening at each step.

You call the agent using the SNOWFLAKE.CORTEX.DATA_AGENT_RUN() function. It takes two arguments:

1. The fully qualified agent name (e.g., 'CORTEX_AGENTS_LAB.TUTORIAL.TUTORIAL_AGENT')
2. A JSON string containing the conversation messages

The function returns a JSON string with the agent's complete response, including its thinking process, tool calls, and final answer.

The response JSON has a content array where each item has a type field. Here's what each type means:

This test asks about sales data, which should route to the Analyst tool. Run this in a Snowflake Notebook Python cell:

What to expect in the output:

1. THINKING: the agent recognizes this is a sales metrics question and chooses the Analyst tool
2. TOOL CALL: shows the agent called the "Analyst" tool
3. TOOL RESULT: displays the SQL query the Analyst generated (e.g., SELECT region, SUM(total_amount) FROM sales GROUP BY region) and the actual data rows
4. ANSWER: a natural language summary like "Total sales by region: North America had the highest at $69,497..."

Now ask about product documentation, which should route to the Search tool:

What to expect: This time the agent recognizes this is a documentation question and routes to the Search tool instead of Analyst. The THINKING section will show the agent reasoning about this differently, and the ANSWER will contain troubleshooting steps retrieved from the product documentation you loaded earlier.

With the same agent and no routing code on your part:

The agent handled the routing, tool execution, and response formatting automatically based on the instructions you provided in the YAML spec.

So far you've tested the agent programmatically with Python. But you don't always need to write code to use an agent. Snowflake Intelligence provides a chat interface where you can talk to any agent created with CREATE AGENT, with no additional setup required.

This is especially useful for non-technical users (business analysts, product managers, support teams) who want to ask questions without writing SQL or Python.

Follow these steps to connect to your agent:

1. In Snowsight, navigate to AI & ML > Snowflake Intelligence in the left sidebar
2. In the chat bar at the bottom, click the agent picker (it may say "General purpose" by default)
3. Select TUTORIAL_AGENT from the list
4. Type a question and press Enter

Test both tools to see the agent route questions automatically:

Structured data questions (routes to Cortex Analyst):

Documentation questions (routes to Cortex Search):

Snowflake Intelligence can present the agent's responses as tables or charts depending on the question:

Try a follow-up question to test multi-turn conversation:

1. First ask: "What are total sales by region?"
2. Then follow up: "Which region had the lowest?" The agent remembers the previous context

This is the fastest way to interact with any agent built with CREATE AGENT, and it's what most end users will use in practice.

You can also interact with the objects you built in this guide directly from a Snowflake Notebook using Cortex Code, an AI coding assistant built into Snowsight (also available as Cortex Code CLI for terminal-based workflows).

Because the agent, semantic view, search service, and tables all persist as first-class objects in your Snowflake account, Cortex Code is context-aware and can discover and use them to answer questions without any extra configuration.

1. Open any Snowflake Notebook (or the companion notebook from this guide)
2. Click the Cortex Code toggle in the bottom-right corner of the notebook
3. Type a question in the chat panel

Cortex Code works best when your question includes enough context for it to identify the right objects. Mention the relevant table name, semantic view, or agent so Cortex Code can route your request accurately.

Examples with context:

When you created the agent, semantic view, and search service earlier in this guide, those objects became persistent resources in your Snowflake account. Cortex Code can detect these objects and use them to answer your questions, just like Snowflake Intelligence does. The difference is that Cortex Code lives inside the notebook environment, so you can ask questions and get answers without leaving your development workflow.

You've built a fully functional Cortex Agent from scratch. Starting from raw data, you created the infrastructure (semantic view, search service) and the orchestration layer (agent) that ties it all together.

Here's a recap of the key concepts and skills you picked up:

Now that you have a working agent, here are ways to extend it:

To remove all objects created in this guide, run the following. The commented-out lines at the bottom drop the entire database and schema; uncomment them only if you want to remove everything.