Best Practices for Building Cortex Agents

Snowflake for Developers GuidesBest Practices for Building Cortex Agents

Quickstart

Best Practices for Building Cortex Agents

Shen Wang, Tyler Richards, Krista Rockson, Josh Reini, James Cha-Earley

Overview

Agents represent a new paradigm for how work gets done with data. Instead of pre-defined dashboards or static queries, agents reason through tasks, choose the right tools, and deliver results in natural language or take actions on your behalf.

You can create, update, and deploy these high-quality agents directly inside your Snowflake environment. Snowflake Agents integrate directly with Snowflake Intelligence with governance, observability, and performance built in.

This guide is your map to building agents for use with Snowflake Intelligence, from idea to production, including links to deeper resources, examples, and tutorials along the way.

What you'll learn

How Snowflake Intelligence and Cortex Agents work together.
How to define agent purpose and scope.
How to configure orchestration and response instructions.
How to design effective tools for Cortex Agents.
How to use agent versioning to manage your deployment lifecycle.
How to evaluate and monitor agent performance.

Important: Before building Cortex Agents, configure your permissions and make sure that you have access to the right models.

How Snowflake Intelligence works

Cortex Agents power the reasoning behind Snowflake Intelligence, turning natural language into governed actions and answers.

Cortex Agents combine reasoning from large language models with Snowflake’s governance, data access, and observability layers to deliver accurate, explainable answers. When a user asks a question in Snowflake Intelligence, it uses Cortex Agents under the hood with the following stages.

User input: A user submits a natural-language question. For example, “How are Q4 sales trending?”.
Cortex Agent API: The question is routed to the Cortex Agent API, which powers Snowflake Intelligence.
Orchestration: The orchestrator (an LLM) interprets intent, selects the right tools, and plans the sequence of actions. It may use one tool, chain several together, or decide that the question is out of scope.
Tool execution:
- Cortex Analyst: Write and run SQL on your semantic views for structured data.
- Cortex Search: Retrieve relevant document text for unstructured data.
- Code Execution: Generate and run Python code in a sandboxed environment.
- Web Search: Query the web for real-time information.
- MCP Connectors: Connect to external SaaS tools via the Model Context Protocol.
- Custom Tools: Execute user-defined functions or stored procedures for actions.
Reflection & response: The orchestrator reviews results, refines if needed, and generates the final answer (including summaries, tables, or charts) shown in the Snowflake Intelligence UI.

The following image describes this structure of Snowflake Intelligence.

👉 Read the blog to learn more about how Snowflake Intelligence orchestration works

Building Cortex Agents

Cortex Agents are configurable reasoning systems that combine Snowflake’s built-in intelligence with your domain context.

You can build and run agents in several ways:

Agent UI in Snowsight: An interactive interface that handles identity, access control, and monitoring out of the box.
Cortex Agent API: A REST API for integrating agents into your own applications (like Streamlit apps or custom apps).

Pro tip: Build agents using natural language with Snowflake's AI coding agent Cortex Code.

Consider the following when building an agent.

Define your agent's purpose

Every great agent starts with a clear purpose. Before adding tools or writing instructions, define why the agent exists, who it serves, and what specific questions it should answer. This step shapes everything that follows, from tool selection to performance and trust.

Start with an end user, and think through what they would actually want: what specific job is this agent meant to do, and for whom? If they had 24/7 access to a data analyst who reads incredibly quickly and has single-digit minute response times, what would they ask of them?

Favor narrowly-scoped specialized agents

Don’t boil the ocean with a generalist agent. Start narrow with a specific, high-value use case. After an agent proves reliable in one area, you can replicate the pattern for others.

For example, you could have the following agents:

One agent that analyzes your Shopify store’s recent sales and marketing data.
One agent that sales can use to recommend the best SKUs to pitch to the retailer.

Map key use cases to tools

To get high-value, narrow use cases, partner with business stakeholders to identify the top 20 most important questions that they need answered. Use these questions as the initial scope for your agent.

If you were to answer that question using a set of documents or data, what would you use? Would you use the sales table, read a few Google docs (which ones?), or look up support tickets?

How many tools should a single agent have? An agent should have access to exactly as many tools as it needs to fulfill its predefined, targeted purpose. In the previous guidance, you wrote down exactly what you needed to answer each question. This becomes the list of tools your agent needs access to.

For example, if you needed to write one set of SQL statements about your Shopify data, then read a Google doc, and finally read some support tickets when answering your question, your agent needs at least 3 separate components:

A semantic view for your Shopify data
A Cortex Search service to read your Google docs
A Cortex Search service to read your support tickets

👉Lessons learned building agents from our data science team

Importance of Cortex Agent instructions

A well-written agent will run efficiently and reliably: calling the right tools, producing explainable results, and reflecting your business logic. Bad or incomplete instructions lead to missteps in reasoning, incorrect data retrieval, and wasted compute cost.

Every Cortex Agent combines your custom instructions with Snowflake’s built-in base system instructions. These base instructions inform general workflows for tool usage, data analysis patterns, validation, visualization, citation, and safety guardrails.

You won’t need to further instruct the agent on this base functionality. For example:

❌ DON'T include:
"When you receive a question, first analyze it carefully, then
select appropriate tools, call them in sequence, and format results properly..."

Your custom agent instructions are configured in 4 key layers, each playing a specific role to define how the agent reasons and responds with domain-specific context, rules, and workflows.

Semantic views are configured inside your data layer. They act as translators, or “cheat sheets” between your raw, structured data and how humans or AI interpret it.
Orchestration instructions are configured high-level business logic, rules, and multi-step workflows. These instruct the agent on how to approach answering a question.
Response instructions control the final output format, tone, and communication style of the agent.
Tool descriptions explain precisely what a tool does, which data it accesses, when to use it, and when not to use it. This is the most critical factor for accurate tool selection.

We’ll go into more detail for each instruction layer in the following sections.

Semantic views (data level)

Each semantic view should cover a similar set of tables, and is instructions that tell the agent how to query or interpret the data. This is where you want to set data specific defaults, such as always adding a date filter for the past three months if not specified or always excluding internal accounts.

Resources for semantic views:

🎥 Watch the hands-on lab
📖 Get started with semantic views

Orchestration instructions (agent level)

Orchestration instructions could include:

Your agent’s identity and narrow scope prevents scope creep and helps the agent stay focused on its intended purpose.

✅ ORCHESTRATION INSTRUCTION

Your Role: You are "SalesBot", a sales intelligence assistant for the Snowflake sales team. Your Scope: You answer questions about customer accounts, pipeline opportunities, deal history, and product usage. You help sales professionals prepare for customer meetings and track account health. 

Your Users: Account Executives (AEs), Solution Engineers (SEs), and Sales Leaders who need quick access to customer data and insights.

Domain context helps the agent interpret questions correctly and use appropriate terminology.

✅ ORCHESTRATION INSTRUCTION

Domain Context 
- Snowflake uses a "consumption-based" pricing model where customers pay for compute (measured in credits) and storage separately.
- An "opportunity" represents a potential deal tracked in Salesforce with stages: Prospecting → Qualification → Proof of Value → Negotiation → Closed Won/Lost
- "ARR" (Annual Recurring Revenue) is the key metric for subscription value
- Our fiscal year runs Feb 1 - Jan 31

Explicit tool selection logic to prevent the agent from choosing the wrong tool and improve consistency.

✅ ORCHESTRATION INSTRUCTION

Tool Selection Guidelines:
- For questions about CURRENT customer data (accounts, usage, credits): Use the "CustomerData" tool.
    For example: "What's Acme Corp's credit usage?", "Show me active accounts"
- For questions about HISTORICAL trends and analytics: Use the "Analytics" tool.
    For example: "How has consumption grown over time?", "Compare Q1 vs Q2"
- For questions about sales pipeline and opportunities: Use the "SalesforcePipeline" tool.
    For example: "What deals are closing this quarter?", "Show me open opportunities"

Boundaries and limitations prevent hallucinations and inappropriate responses. Users will inevitably ask questions outside your agent's scope.

✅ ORCHESTRATION INSTRUCTION

Limitations and Boundaries:
- You do NOT have access to customer contracts or legal agreements.
    If asked, respond: "I don't have access to contract details. Please contact Legal."
- You do NOT have real-time data. Your data is refreshed daily at 2 AM UTC.
    If asked about "right now", clarify: "My data is current as of this morning's refresh."
- Do NOT calculate financial forecasts or make predictions about future revenue.
    You can show historical trends but should not extrapolate future values.
- Do NOT provide customer contact information (emails, phone numbers) for privacy reasons.

Business rules and conditional logic to ensure consistent handling of common scenarios, edge cases, and error conditions.

✅ ORCHESTRATION INSTRUCTION

Business Rules:
- When a user asks about a customer by name (not ID), ALWAYS use
CustomerLookup tool first to get the customer_id before calling other tools

- If a query result returns more than 100 rows, ALWAYS aggregate or
filter the data before presenting. Do NOT display all rows.

- For any consumption questions about dates within the last 7 days,
remind users that data has a 24-hour delay and today's data is not yet
available

- When multiple regions match a query, ALWAYS ask for clarification
rather than assuming which region the user meant

- If a tool returns an error code "INSUFFICIENT_PERMISSIONS", respond
with: "You don't have access to this data. Please contact your Snowflake admin to request access."

Domain-specific workflows to deliver consistency and reduce the need for users to ask complex multi-part questions.

✅ ORCHESTRATION INSTRUCTION

Account Summary Workflow:

When a user asks to "summarize my accounts" or "give me a book of
business update":

1. Use CustomerData tool to get the user's assigned accounts list
2. Use Analytics tool to show each account's':
    - Last 90-day consumption and growth rate
    - Total ARR and change from last quarter
3. Use SalesforcePipeline tool to show:
    - Top 5 open opportunities by value
    - Any opportunities closing in next 30 days
4. Use SupportTickets tool to flag any critical severity tickets in last 7 days

Present results in tables with clear sections.

Response instructions (agent level)

These instructions control the final output format, tone, and communication style of the agent. Examples include:

Tone and communication style:

✅ RESPONSE INSTRUCTION

Response Style:
    - Be concise and professional - sales teams are busy
    - Lead with the direct answer, then provide supporting details
    - Be direct with data. Avoid hedging language like "it seems" or "it appears"
    - Use active voice and clear statements

Data presentation formats

✅ RESPONSE INSTRUCTION

Data Presentation:
    - Use tables for multi-row data (\>3 items)
    - Use charts for comparisons, trends, and rankings
    - For single values, state them directly without tables
    - Always include units (credits, dollars, %) with numbers
    - Include data freshness timestamp in responses

Response structure templates

✅ RESPONSE INSTRUCTION

Response Structure:

For "What is X?" questions:
    - Lead with direct answer
    - Follow with supporting context if relevant

    Response example: "Acme Corp used 12,450 credits last month (up 8% from September)."

For "Show me X" questions:
    - Brief summary sentence
    - Table or chart with data
    - Key insights or highlights

    Response example: "You have $2.4M in open Q4 pipeline across 12 opportunities. \[table\]"

For "Compare X and Y" questions:
    - Summary of comparison result
    - Chart showing comparison visually
    - Notable differences highlighted

Error and edge case messaging

✅ RESPONSE INSTRUCTION

Error Handling:
- When data is unavailable: "I don't have access to \[data type\]. You can find this information in \[alternative source\] or contact \[team\]."
- When query is ambiguous: "To provide accurate data, I need clarification: \[specific question\]. Did you mean \[option A\] or \[option B\]?"
- When results are empty: "No results found for \[criteria\]. This could mean \[possible reason\]. Would you like to try \[alternative approach\]?"

Best practices between orchestration and response instructions

It’s important to separate orchestration (what to do, which tools) and response (how to format, tone) into distinct instruction settings. Don’t combine tool selection logic with response formatting in the same section.

To help categorize where instructions should live, ask yourself:

Does this instruction affect...	Put it in...	Example
Which tool to select	Orchestration	"Use CustomerData for current metrics"
What data to retrieve	Orchestration	"Include last 90 days of usage data"
How to interpret user intent	Orchestration	"When user says 'recent', use last 30 days"
How to sequence tool calls	Orchestration	"Always call CustomerLookup before CustomerMetrics"
Conditional logic and rules	Orchestration	"If result > 100 rows, aggregate before displaying"
What to do in specific scenarios	Orchestration	"When error code X occurs, try alternative tool Y"
How to format the answer	Response	"Use tables for multi-row results"
What tone to use	Response	"Be concise and professional"
How to structure text	Response	"Lead with direct answer, then details"
What to say when errors occur	Response	"Explain limitation and suggest alternatives"

Tool descriptions (agent level)

These describe to the agent what types of things the tool (Semantic View, Search Service, or Custom Tool) can do, so it can infer when it would be best to call it.

Tool descriptions are often the culprit for most agent quality problems. Agents choose tools based on name and description context, so make them obvious. Bad tool descriptions create cascading failures, and can lead to downstream hallucinations.

While instructions set the agent's identity and scope, tool descriptions directly govern:

Tool selection accuracy: Whether the agent picks the right tool for each question.
Parameter usage: Whether the agent provides correct inputs to tools.
Error prevention: Whether the agent avoids misusing tools or making invalid calls.
Consistency: Whether the agent behaves predictably across similar questions.

Step 1: Start with a clear, specific tool name

Tool names are loaded into the agent's context and influence selection.

Tip: Combine a domain (“Customer”, “Sales”) with a function (“Analytics”, “Search”) to make each tool unambiguous.

✅ GOOD: "CustomerConsumptionAnalytics"
❌ BAD: "DataTool" or "Tool1"

✅ GOOD: "SalesforcePipelineQuery"
❌ BAD: "Query" or "SalesData"

✅ GOOD: "ProductDocumentationSearch"
❌ BAD: "Search" or "Docs"

Step 2: Write a purpose-driven tool description

A strong description tells the agent:

[What the tool does] + [What data it accesses] + [When to use it] + [When NOT to use it]

[What data it accesses] refers to what’s in your semantic view. Include a concise summary of what’s in your semantic view. The agent first chooses tools based on their descriptions, not by inspecting your full data model.
"When NOT to Use" is critical. Without it, agents will try to use tools for everything remotely related. "When NOT to Use" creates clear boundaries and redirects the agent to appropriate alternatives.

✅ GOOD EXAMPLE

Name: CustomerConsumptionAnalytics

Description: Analyzes Snowflake consumption metrics for customer accounts including credit usage,compute hours, and storage.

Data Coverage: Daily aggregated consumption data for all commercial
customers, updated nightly. Includes data from the past 2 years.

When to Use:
    - Questions about customer usage patterns, trends, or growth
    - Queries about specific customers' consumption (e.g., "How much did Acme use?")
    - Comparisons between time periods (e.g., "Compare Q1 vs Q2 usage")

When NOT to Use:
    - Do NOT use for real-time/current-hour data (data is daily batch, not real-time)
    - Do NOT use for trial or non-commercial accounts (not included in dataset)
    - Do NOT use for individual query performance (use QueryHistory tool instead)

Key Parameters:
    - customer_name: Exact customer name (case-sensitive).
        Use CustomerList tool first if unsure of exact spelling.
    - date_range: ISO format dates (YYYY-MM-DD). Required.
        Use specific dates, not relative terms like "last month".
    - metric: One of: 'credits', 'compute_hours', 'storage_tb'

❌ BAD EXAMPLE:
Name: ConsumptionTool
Description: Gets consumption data.

Step 3: Be explicit about tool inputs

This is where most tool descriptions fail. Ambiguous inputs to your tools lead to incorrect tool calls and errors, whether Cortex Analyst, Cortex Search, or custom tools.

Common pitfalls	Recommendation
Using a generic name user vs user_id vs username	Be specific salesforce_user_id (18-char ID) vs user_email (email string)
Unclear data formats "date" vs "ISO 8601 date (YYYY-MM-DD)"	Specify data format Agents may pass "last month", "Q3", or other invalid formats
Not explaining how to obtain IDs "Provide customer_id"	Provide clear data instructions "Customer ID from CustomerLookup tool, or directly from user if known"
Unclear optionality "region (optional)"	Provide default guidance "region (optional, defaults to 'ALL', returns data for all regions)"
Using inconsistent terminology Pick one term and use it consistently everywhere. Instructions say "customers" but tool descriptions say "accounts"	Use consistent terminology If your domain has multiple terms for the same concept, define them explicitly: "Account (also called 'customer' in billing context): A business entity that..."

Using Tools

Cortex Agents support a rich set of built-in tools: Cortex Analyst for text-to-SQL, Cortex Search for document retrieval, code execution for sandboxed Python, web search for real-time information, and MCP connectors for integrating with external SaaS tools.

Cortex Analyst (Text-to-SQL)

Cortex Analyst accepts natural language queries and converts them to SQL. Your description must guide the agent on how to phrase queries effectively.

Start with "Generate with Cortex" in the Admin UI to automatically generate a tool description based on your semantic model. This provides a solid baseline that already includes key information about your data.

Then, enhance the auto-generated description by following the previously described principles.

Cortex Search

Cortex Search services retrieve relevant documents and records using semantic search. The two primary use cases for Cortex Search are retrieval augmented generation (RAG) and enterprise search.

For example, one of the first demo agents built inside of Snowflake used the following Cortex Search Service to answer questions about internal product documentation and architecture.

✅ GOOD EXAMPLE

Name: ProductDocumentationSearch

Type: Cortex Search Service

Description:
Searches internal product documentation, feature announcements,
technical guides, and release notes to answer "what" and "how" questions
about Snowflake products. Uses semantic search to find relevant
documents even when exact keywords don't match.

Data Sources:
    - Product documentation (updated weekly)
    - Feature release notes (updated with each release)
    - Technical architecture guides (updated quarterly)
    - Best practice documents (updated monthly)
    - Last indexed: Timestamp included in each search result

When to Use:
    - Questions about product features, capabilities, or specifications
    - "How to" questions and configuration instructions
    - Feature availability and compatibility questions
    - Troubleshooting guidance and best practices

When NOT to Use:
    - Customer-specific data or usage (use CustomerMetrics instead)
    - Sales/pipeline information (use SalesforcePipeline instead)
    - Real-time system status (use HealthMonitor instead)
    - Questions requiring computation or data aggregation (use Cortex Analyst tools)

Search Query Best Practices:
    1. Use specific product names:
        ✅ "Snowflake Streams change data capture"
        ❌ "streams" (too generic)
    
    2. Include multiple related keywords:
        ✅ "security authentication SSO SAML configuration"
        ❌ "security" (too broad)

    3. Use technical terms when appropriate:
        ✅ "materialized view incremental refresh performance"
        ❌ "fast views" (colloquial)

    4. If first search returns low relevance, rephrase: Try synonyms, expand acronyms, add context.
    
Example usage:

Scenario 1: Feature explanation
    - User Question: "How do Snowflake Streams work?"
    - Search Query: "Snowflake Streams change data capture CDC functionality"
    - Expected Results: 3-5 relevant docs about Streams

Scenario 2: Configuration question
    - User Question: "How do I configure SSO with Okta?"
    - Search Query: "SSO single sign-on Okta SAML configuration setup"
    - Expected Results: Step-by-step guides, configuration docs

Scenario 3: Low relevance handling
    - Initial Query: "table optimization"
    - Results: Low relevance scores (\<0.5)
    - Action: Rephrase search: "table clustering performance optimization best practices".
        Then provide results from improved search

Scenario 4: No relevant results
    - User Query: "Snowflake integration with \[obscure system\]"
    - Results: No results with relevance \>0.3
    - Response: "I couldn't find documentation about this integration.
        This feature may not be supported or documented yet.
        Please contact Support for specific integration questions."

If you have essential parameters in your Cortex Search service, it is especially important for you to include:

Type and format (include examples)
Required vs. optional (with default values)
Valid values or constraints (enums, ranges, formats)
Relationship to other parameters (dependencies, conflicts)
How to obtain the value (especially for IDs)

One good example is if you have a service where you often need to filter for specific accounts, or start or end dates of contracts, the following description would help your agent in using this search service.

✅ GOOD EXAMPLE

Parameters:

account_id:
Type: string
Required: Yes
Description: Unique Salesforce account ID (18-character alphanumeric)
Format: Starts with "001" followed by 15 alphanumeric characters
Example: "001XX000003DHW3QAO"
How to obtain: Use AccountLookup tool first if you only have account
name

start_date:
Type: string (ISO 8601 date)
Required: Yes
Format: "YYYY-MM-DD"
Example: "2024-01-01"
Constraints: Must not be more than 2 years in the past, must be before
end_date

end_date:
Type: string (ISO 8601 date)
Required: No (defaults to today)
Format: "YYYY-MM-DD"
Example: "2024-12-31"
Constraints: Must be after start_date, cannot be in the future

Code Execution

The code execution tool enables your agent to generate and run Python code in a sandboxed environment during a conversation. This is useful for complex calculations, data transformations, and generating visualizations that go beyond what SQL can express.

To enable code execution, add the tool spec and resource to your agent specification:

tools:
  - tool_spec:
      type: code_execution
      name: code_execution

tool_resources:
  code_execution: {}

Best practices for code execution:

Scope access carefully. The code execution tool inherits the agent owner's role privileges. Make sure the owner role is appropriately scoped.
Grant PyPI access only when needed. You can allow PyPI package installation via artifact_repositories, but this gives the tool access to any public package. Only enable it when your use case requires external libraries.
Use external access integrations sparingly. If the code execution tool needs to reach external endpoints, create narrowly scoped network rules that allow only the specific domains required.
Design for single-session scope. The sandbox persists within a session but not across sessions. If you need to persist results, write them to a Snowflake table that the tool has access to.
Add orchestration instructions for when to use code execution vs. other tools. For example: "Use the code execution tool for statistical analysis, visualizations, or multi-step calculations. Use Cortex Analyst for direct data retrieval."

Web Search

The web search tool lets your agent query the web via the Brave Search API to retrieve real-time information during a conversation. This is useful for questions about current events, public benchmarks, or any context that your internal data doesn't cover.

Prerequisites: An ACCOUNTADMIN must enable web search at the account level in Snowsight under AI & ML → Agents → Settings before it can be used in any agent.

Best practices for web search:

Use web search for real-time information your internal data doesn't cover. If users ask about industry trends, competitor news, or current events, web search fills the gap.
Add explicit orchestration instructions for when to use web search vs. internal tools. For example: "Use web search only for questions about external market data or current events. For all customer and sales data, use CustomerAnalytics." Without this guidance, the agent may default to web search for questions your internal tools can answer better.
Know the privacy model. Snowflake has enabled zero data retention (ZDR) with Brave — no search queries or results are stored by Brave. However, queries and results do traverse the public internet.
Combine with Cortex Search for hybrid scenarios. Web search provides breadth (the open web), while Cortex Search provides depth (your proprietary documents). Use orchestration instructions to tell the agent when each is appropriate.

MCP Connectors

MCP Connectors connect your agents to external SaaS tools via the Model Context Protocol (MCP). Supported connectors include Atlassian (Jira & Confluence), GitHub, Glean, Google Workspace, Linear, Salesforce, and Slack, and you can build custom connectors for any MCP-compatible endpoint.

The setup flow for MCP connectors is:

Provider setup: Create an OAuth app on the provider's dashboard and obtain credentials.
API integration: Create an API integration in Snowflake that stores the OAuth configuration.
External MCP server: Create an external MCP server object that references the API integration.
Agent configuration: Add the external MCP server to your agent.
User authentication: End users connect via OAuth in Snowflake Intelligence.

Best practices for MCP connectors:

Follow least-privilege access. Grant only the minimum required privileges for each role. Access to an MCP server doesn't automatically grant access to its tools.
Use descriptive names for MCP servers. The agent selects tools based on name and description context. A name like JiraProjectTracker is better than MCPServer1.
Add orchestration instructions for external vs. internal tools. For example: "Use the Jira connector for questions about open tickets and sprint progress. Use CustomerAnalytics for revenue and usage data."
Disable rather than drop integrations during maintenance. Disabling preserves configuration and secrets while immediately blocking tool invocations. Dropping is permanent.
Use hyphens, not underscores, in hostnames. Hostnames containing underscores cause connection issues.

👉 Getting Started with MCP Connectors

Help users find and use your agent effectively

In addition to a specific, descriptive agent name, add example questions where you know your agent already performs well.

These examples help users understand your agent’s purpose and how to engage with it. These example questions should be independent of each other, and connect back to your agent’s predefined purpose.

In Snowflake Intelligence, users can browse the Agents tab to view available agents. They’ll see your agent’s description and its example questions. A well-written description makes it easy for users to recognize when to use your agent and what to expect from it.

Deploying your agent to production

The process of deploying agents is similar to developer cycles, with three key stages. Begin by clearly:

Defining a use case and creating a prototype agent.
Using systematic tests to drive iteration and improvement.
Graduating to a production agent.

👉 For a deep dive into evaluation, versioning, CI/CD, and monitoring best practices, see Best Practices for Evaluating Cortex Agents.

Use agent versioning to structure your deployment lifecycle

Preview Feature — Private: Agent versioning is available to select accounts.

Cortex Agent versioning gives you a clean separation between development and production through three concepts:

Live version — a mutable draft where you iterate on prompts, tools, and configs.
Named versions — immutable snapshots created from the live version that you can safely test and deploy.
Aliases (e.g., production, staging, canary) — pointers that route traffic to a specific version, decoupling your client code from version numbers.

The core workflow:

Prototype on the live version.
Commit a named version and evaluate it against your test set.
Promote by assigning the production alias to the version that passes your quality bar.

ALTER AGENT my_agent COMMIT COMMENT = 'Improved tool selection logic';

ALTER AGENT my_agent MODIFY VERSION VERSION$4 SET ALIAS = production;

If a regression is detected, roll back instantly by pointing the alias to a previous version:

ALTER AGENT my_agent MODIFY VERSION VERSION$3 SET ALIAS = production;

You can also create agent versions from a stage or git repository, list versions, and access version files via the snow://agent/ URI scheme.

Stage 1: Prototype and use case development

Build the first version of your agent and smooth out obvious rough edges. At the end of this stage, it should be clear which use cases your agent targets and which it does not.

Create a representative “golden” test set of questions, expected tool use, and expected answers. Work directly with trusted stakeholders or end-users to build this set — it becomes your baseline for measuring agent quality.

Stage 2: Iteration and evaluation

Use the Snowflake Monitoring UI and Cortex Agent Evaluations (generally available) to identify which queries the agent handles incorrectly or too slowly. Agent traces show planning, tool use, and generation steps so you can pinpoint exactly where things went wrong.

After your agent performs well against your golden set, it’s ready for production.

Stage 3: Production

Monitor production usage and collect user feedback. Run your evaluation set on a regular cadence to catch regressions from model updates, data changes, or tool configuration drift. Focus first on queries with negative feedback to build a “hard” evaluation set that drives the next round of improvement.

How to improve agent performance

Improve orchestration instructions and tool descriptions: Use evaluation results to inform improvement. For issues with tools, focus on tool descriptions. For orchestration and planning issues, update orchestration instructions.
Use agent traces to identify latency bottlenecks: Traces in the monitoring tab show the logical path the agent took and how long each step lasted, allowing you to pinpoint the exact bottleneck.
Pre-define verified queries: For common or complex analytics, pre-define and verify queries directly in your semantic views. This ensures the agent uses an optimized, predictable query path.
Make queries performant: An ounce of data engineering is worth a pound of prompt engineering. Optimizing your underlying data models, pre-aggregating common metrics, and using clear, consistent column names can have a greater impact on performance than tweaking instructions.

Example: Complete agent configuration

Here's a comprehensive example bringing it all together in the Snowflake Agent UI. We're building "CarAnalytics Pro", an automotive marketplace analytics agent.

About the agent

Display Name: CarAnalytics Pro

Description:
CarAnalytics Pro answers questions about vehicle pricing, listing
performance, and market trends on AutoMarket.

Example questions:
    - What is the average Days to Sale for 2020 Honda Accord by trim in California last quarter?
    - Which SUV segments had the largest month over month price change this year?
    - Show listings that are priced above market for 2019 to 2021 Toyota RAV4 with mileage under 60,000.

Orchestration instructions

\*\*Role:\*\*

You are "CarAnalytics Pro", an automotive data analytics assistant for
AutoMarket, an online car marketplace. You help data scientists,
analysts, product managers, and pricing strategists gain insights from
vehicle listings, customer behavior, market trends, and platform
performance data.

\*\*Users:\*\*

Your primary users are:
    - Data scientists building predictive models and statistical analyses
    - Business analysts tracking KPIs and generating reports
    - Product managers optimizing platform features and user experience
    - Pricing strategists developing competitive pricing recommendations

    They typically need to analyze large datasets, understand market dynamics, and create data-driven recommendations for business strategy.

\*\*Context:\*\*

Business Context:
    - AutoMarket is a leading online car marketplace in North America
    - We facilitate both B2C (dealer) and C2C (private party) transactions
    - Platform handles 50,000+ active vehicle listings
    - Revenue from listing fees, transaction commissions, and premium dealer services
    - Data refreshes: Daily at 2 AM PST

Key Business Terms:
    - Listing Velocity: Days from listing creation to sale (target: \<30 days)
    - Price-to-Market Ratio (PMR): Listing price ÷ market value (1.0 = fair price)
    - Days to Sale (DTS): Time from listing to completed transaction
    - Take Rate: Platform commission as % of transaction value (avg 3-5%)
    - GMV: Gross Merchandise Value (total $ of all transactions)

Market Segments:
    - Luxury: Vehicles \>$50K (BMW, Mercedes, Audi, Lexus)
    - Mid-Market: $15K-$50K (Honda, Toyota, Ford, Chevy)
    - Budget: \<$15K (older vehicles, high mileage)
    - Electric/Hybrid: Alternative fuel vehicles (25% YoY growth)
    - Trucks & SUVs: 40% of our GMV

\*\*Tool Selection:\*\*

- Use "VehicleAnalytics" for vehicle inventory, pricing, and listing performance.
    Examples: "What's the average Days to Sale for 2020 Honda Accords?", "Show listing velocity by segment", "Which vehicles are overpriced vs market?"   
- Use "CustomerBehavior" for buyer/seller behavior, conversion, and segmentation.
    Examples: "What's the customer journey from search to purchase?","Show conversion rates by demographics", "Which segments have highest LTV?"  
- Use "MarketIntelligence" for competitive analysis and market research.
    Examples: "How do our prices compare to Carvana?", "What's our market share by region?", "Which markets have highest growth potential?"
- Use "RevenueAnalytics" for financial metrics, GMV, take rate, and commissions.
    Examples: "What's our take rate by transaction type?", "Show GMV trends and seasonality", "Calculate CAC by acquisition channel"

\*\*Boundaries:\*\*
- You do NOT have access to individual customer PII (names, emails, addresses, phone numbers). Only use aggregated/anonymized data per GDPR/CCPA compliance.
- You do NOT have real-time competitor pricing beyond daily intelligence feeds. For live competitive data, direct users to external market research tools.
- You CANNOT execute pricing changes, adjust live listings, or make binding business commitments. All recommendations are analytical only.
- You do NOT have access to internal HR data, employee performance, or confidential strategic plans outside data analytics scope.
- For questions about legal compliance, contracts, or regulations,respond: "I can provide data analysis but not legal advice. Please consult Legal for compliance questions."

\*\*Business Rules:\*\*
- When analyzing seasonal trends, ALWAYS apply Seasonal Adjustment Factor for vehicle types with known seasonality (convertibles, 4WD trucks, etc.)
- If query returns \>500 listings, aggregate by make/model/segment rather than showing individual listings
- For price recommendations, ALWAYS include confidence intervals and sample size. Do not recommend pricing without statistical validation.
- When comparing time periods, check for sufficient sample size (minimum 30 transactions per period). Flag low-sample warnings.
- If VehicleAnalytics returns PMR outliers (\>1.5 or \<0.5), flag as potential data quality issues and recommend manual review.

\*\*Workflows:\*\*

Pricing Strategy Analysis: When user asks "Analyze pricing for \[segment/make/model\]" or "Should we adjust pricing for \[category\]":

1. Use VehicleAnalytics to get current listing data:
    - Average prices, Days to Sale, Price-to-Market Ratios
    - Compare vs 3-month and 12-month historical trends
    - Segment by condition, mileage, regional variations

2. Use MarketIntelligence for competitive context:
    - Compare our prices vs competitors (Carvana, CarMax, dealers)
    - Identify price gaps and positioning opportunities
    - Analyze competitor inventory levels and velocity

3. Use CustomerBehavior for demand signals:
    - View-to-inquiry and inquiry-to-offer conversion rates
    - Price sensitivity analysis by segment
    - Historical elasticity data

4. Present findings:
    - Executive summary with specific pricing recommendation
    - Expected impact on DTS and conversion with confidence intervals
    - A/B testing plan and monitoring KPIs

Response Instructions

\*\*Style:\*\*
    - Be direct and data-driven - analysts value precision over politeness
    - Lead with the answer, then provide supporting analysis
    - Use statistical terminology appropriately (p-values, confidence intervals, correlation vs causation)
    - Flag data limitations, sample size constraints, and seasonality effects
    - Avoid hedging with business metrics - state numbers clearly

\*\*Presentation:\*\*
    - Use tables for comparisons across multiple vehicles/segments (\>4 rows)
    - Use line charts for time-series trends and seasonality
    - Use bar charts for rankings and segment comparisons
    - For single metrics, state directly: "Average DTS is 23 days (±3 days, 95% CI)"
    - Always include data freshness, sample size, and time period in responses

\*\*Response Structure:\*\*

 For trend analysis questions:
 "\[Summary of trend direction\] + \[chart\] + \[statistical significance\] + \[context\]"
    
    Example: "Luxury segment DTS decreased 15% QoQ (p\<0.01). \[chart showing monthly trend\]. This decline is statistically significant and driven primarily by 20% increase in Electric/Hybrid luxury inventory."

For pricing questions: 
    "\[Direct recommendation\] + \[supporting data\] + \[expected impact\] + \[caveats\]"
    
    Example: "Recommend 5-8% price reduction for 2019-2020 Honda Accord listings. Current PMR is 1.12 vs market (overpriced). Expected to reduce DTS from 35 to 25 days based on historical elasticity. Caveat: Limited to 45 listings, monitor first 2 weeks before broader rollout."

Tool: VehicleAnalytics

Select a new Cortex Analyst tool
Select “Generate with Cortex” then refine further

Name: VehicleAnalytics

Description:
Analyzes vehicle inventory, pricing trends, listing performance, and market positioning metrics. Covers all active and sold listings on AutoMarket
platform.

Data Coverage:
    - Historical: Past 3 years of listing and transaction data
    - Active listings: All current platform inventory (\~50K listings)
    - Sold listings: Completed transactions with final sale price
    - Removed listings: Listings removed without sale (expired, withdrawn)
    - Refresh: Daily at 2 AM PST (21-hour lag from current time)

    Data Sources: listings table, transactions table, vehicle_valuations table

When to Use:
    - Questions about vehicle pricing, inventory levels, or listing counts
    - Listing performance metrics (Days to Sale, listing velocity, PMR)
    - Historical price trends and seasonality analysis
    - Vehicle-level or segment-level aggregations
    - "Which vehicles/segments" queries (rankings, comparisons, distributions)

When NOT to Use:
    - Do NOT use for buyer/seller behavior or conversion funnels (use CustomerBehavior)
    - Do NOT use for competitive pricing outside AutoMarket (use MarketIntelligence)
    - Do NOT use for financial metrics like GMV, commissions, revenue (use RevenueAnalytics)
    - Do NOT use for real-time data (21-hour lag, updated daily only)
    - Do NOT use for individual customer purchase history (PII restricted)

Conclusion

By following these best practices, you can confidently build Cortex Agents that are reliable, secure, and aligned with Snowflake’s data governance standards. Each agent should have a clearly defined purpose, a focused set of tools, and robust orchestration and response logic.

Additional resources

Updated 2026-05-07

This content is provided as is, and is not maintained on an ongoing basis. It may be out of date with current Snowflake instances

Ready to get started?

Open in Snowflake