Skip to main content

Cortex Agents

What are Cortex Agents​

A Cortex Agent is a Snowflake-managed AI agent that can use multiple tools to answer complex questions. Unlike Cortex Analyst (which generates SQL from a single semantic view), an agent can combine:

  • SQL via Cortex Analyst — query structured data through semantic views
  • Cortex Search — retrieve unstructured content from documents and knowledge bases
  • Python tools — execute custom logic, call APIs, or run computations

Agents reason about which tools to use, chain tool calls together, and synthesize a final answer.

Agent Architecture​

 User Question
│
▼
Cortex Agent (LLM reasoning loop)
│
├──► Tool: Cortex Analyst ──► SQL query ──► Structured results
│
├──► Tool: Cortex Search ──► Document retrieval ──► Text chunks
│
└──► Tool: Python ──► Custom computation ──► Calculated output
│
▼
Synthesized Answer (combines all tool outputs)

The agent decides at each step which tool to call based on the question and the results it has so far. It can make multiple tool calls in sequence before producing a final answer.

CREATE CORTEX AGENT Syntax​

CREATE OR REPLACE CORTEX AGENT analytics_db.public.sales_agent
COMMENT = 'Sales analytics agent with SQL and search capabilities'
MODEL = 'claude-3.5-sonnet'
TOOLS = (
SEMANTIC_VIEW_TOOL(
semantic_view => 'analytics_db.public.sales_semantic_view'
),
CORTEX_SEARCH_TOOL(
search_service => 'analytics_db.public.product_docs_search'
)
)
SYSTEM_PROMPT = 'You are a sales analytics assistant. Answer questions using sales data and product documentation. Be precise with numbers and cite sources for document-based answers.';

Configuring Agent Tools​

Semantic View Tool (SQL)​

Gives the agent access to structured data via Cortex Analyst:

SEMANTIC_VIEW_TOOL(
semantic_view => 'analytics_db.public.sales_semantic_view'
)

You can attach multiple semantic views for cross-domain questions:

TOOLS = (
SEMANTIC_VIEW_TOOL(semantic_view => 'analytics_db.public.sales_sv'),
SEMANTIC_VIEW_TOOL(semantic_view => 'analytics_db.public.finance_sv')
)

Cortex Search Tool (Unstructured Data)​

Gives the agent access to a Cortex Search Service for document retrieval:

CORTEX_SEARCH_TOOL(
search_service => 'analytics_db.public.knowledge_base_search'
)

Python Tool​

Allows the agent to run custom Python functions:

PYTHON_TOOL(
function => 'analytics_db.public.calculate_forecast'
)

Building Your First Agent​

Step 1: Prerequisites​

Ensure you have a semantic view and optionally a Cortex Search Service:

-- Verify semantic view exists
SHOW SEMANTIC VIEWS IN SCHEMA analytics_db.public;

-- Verify search service exists (if using)
SHOW CORTEX SEARCH SERVICES IN SCHEMA analytics_db.public;

Step 2: Create the Agent​

CREATE OR REPLACE CORTEX AGENT analytics_db.public.my_first_agent
MODEL = 'claude-3.5-sonnet'
TOOLS = (
SEMANTIC_VIEW_TOOL(
semantic_view => 'analytics_db.public.sales_semantic_view'
)
)
SYSTEM_PROMPT = 'You are a helpful data analyst. Answer questions about sales data accurately.';

Step 3: Query the Agent​

SELECT SNOWFLAKE.CORTEX.AGENT(
'What were the top 5 regions by revenue last quarter?',
AGENT => 'analytics_db.public.my_first_agent'
);

Agent Evaluation and Testing​

Test your agent systematically before production deployment:

Test CategoryWhat to VerifyExample
AccuracySQL results match expected values"Total Q4 revenue" should equal known figure
Tool selectionAgent picks the right toolSQL question should not trigger search
Edge casesHandles nulls, empty results, ambiguity"Revenue for a region with no orders"
LatencyResponse time is acceptableComplex multi-tool queries under 30s
SecurityAgent respects RBACRestricted user cannot access unauthorized data
-- Create a test suite as a table
CREATE TABLE analytics_db.public.agent_test_cases (
test_id INT,
question VARCHAR,
expected_tool VARCHAR,
expected_answer_contains VARCHAR
);

INSERT INTO analytics_db.public.agent_test_cases VALUES
(1, 'What is total revenue?', 'analyst', 'revenue'),
(2, 'What is our refund policy?', 'search', 'refund');

Production Deployment​

Checklist for deploying an agent to production:

  • Grant appropriate roles access to the agent
  • Ensure underlying semantic views and search services are stable
  • Set up monitoring for agent query volume and error rates
  • Document the agent's capabilities and limitations for end users
  • Establish a feedback loop for users to report incorrect answers
-- Grant access
GRANT USAGE ON CORTEX AGENT analytics_db.public.sales_agent TO ROLE analyst_role;

Streamlit Chat UI for Agents​

import streamlit as st
from snowflake.snowpark.context import get_active_session

session = get_active_session()
st.title("Sales Assistant")
st.caption("Ask questions about sales data or product documentation")

if "messages" not in st.session_state:
st.session_state.messages = []

for msg in st.session_state.messages:
with st.chat_message(msg["role"]):
st.markdown(msg["content"])

if prompt := st.chat_input("Ask me anything about sales..."):
st.session_state.messages.append({"role": "user", "content": prompt})
with st.chat_message("user"):
st.markdown(prompt)

with st.chat_message("assistant"):
with st.spinner("Thinking..."):
result = session.sql(f"""
SELECT SNOWFLAKE.CORTEX.AGENT(
'{prompt.replace("'", "''")}',
AGENT => 'analytics_db.public.sales_agent'
)
""").collect()
answer = result[0][0]
st.markdown(answer)
st.session_state.messages.append({"role": "assistant", "content": answer})

Next Steps​

Continue to Module 25 to apply semantic models and agents in capstone projects.