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 Category | What to Verify | Example |
|---|---|---|
| Accuracy | SQL results match expected values | "Total Q4 revenue" should equal known figure |
| Tool selection | Agent picks the right tool | SQL question should not trigger search |
| Edge cases | Handles nulls, empty results, ambiguity | "Revenue for a region with no orders" |
| Latency | Response time is acceptable | Complex multi-tool queries under 30s |
| Security | Agent respects RBAC | Restricted 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.