Cortex Agents¶

Overview¶

Cortex Agents is a fully managed agentic platform for building and running AI agents within Snowflake’s governed environment. An agent reasons over a request, plans the work, calls tools, executes code, and generates a response, without requiring you to build or operate your own orchestration loop, runtime, or sandbox infrastructure. Data access is governed by Snowflake privileges and the execution context of each configured tool.

Agents bring your structured and unstructured data together in a single governed workflow. They generate SQL over structured data using Cortex Analyst semantic views and use Cortex Search to retrieve insights from unstructured sources, then reason over the combined results. You can extend what an agent can do with several types of tools:

• A built-in code execution tool that, when enabled, runs Python in a secure, isolated sandbox to process data and perform calculations.
• A Data to Chart tool that generates visualizations from data.
• Custom tools built from stored procedures and user-defined functions (UDFs) to call backend systems or implement your own business logic.
• Packaged agent skills, modular bundles of instructions and scripts that give an agent repeatable, task-specific capabilities.
• MCP connectors to remote Model Context Protocol (MCP) servers, letting agents discover and invoke tools hosted by providers such as Atlassian Jira, Salesforce, or your own applications.
• Web search for real-time information from the public internet.

Threads maintain conversation context across turns, so your client application doesn’t have to manage state. After deployment, you can monitor agents, collect end-user feedback, and run evaluations to continuously refine their behavior.

To answer a request, an agent follows a reasoning loop with three steps:

1. Plan: The agent parses the request and decides how to answer it. It can disambiguate a vague question (for example, “Tell me about Acme Supplies” might refer to products, location, or sales personnel), split a complex request into subtasks (for example, “What are the differences between contract terms for Acme Supplies and Acme Stationery?”), and choose which tool to use for each part.
2. Use tools: The agent calls the tools it selected, such as Cortex Analyst for structured data, Cortex Search for unstructured data, or the code execution tool to process results.
3. Reflect and respond: The agent evaluates the results from each tool to decide what to do next, whether that’s asking a clarifying question, calling another tool, or generating a final response. This loop lets the agent handle complex, multi-step questions while staying within Snowflake’s secure perimeter.

The agent repeats this loop as needed within a single request.

You define an agent as a reusable object that bundles its model, tools, and orchestration instructions. Create one in Snowsight, with the Cortex Agents SQL commands, or through the REST API, then integrate it into your application using the REST API. You guide its behavior with natural-language instructions, and you can choose the language model that powers it or let Snowflake select one automatically. In addition to calling agents from your own applications through the REST API, users can interact with them in Snowflake CoWork and Cortex Code.

For tutorials to help you get started, see Cortex Agents tutorials.

Key concepts¶

Cortex Agents is built around the following concepts:

Models¶

When creating an agent, we recommend selecting auto for the model. With this option, Cortex automatically selects the highest quality model for your account, and quality improves as new models become available.

Model and feature availability can vary by region and georegion. For the list of available models, see Model availability.

How it works¶

Building with Cortex Agents follows a five-step lifecycle:

1. Create an agent: Define the agent object in Snowsight, with SQL, or through the REST API, including its name, model, and instructions. See Create an agent.
2. Add tools: Configure the tools the agent can use and the resources each tool needs, such as semantic views, search services, and warehouses. See Add tools.
3. Test the agent: Prompt the agent in the Snowsight playground and refine its tools and instructions until it responds as expected. See Test the agent.
4. Integrate it into your application: Call the agent through the agent:run REST API, using threads to maintain conversation context. Users can also interact with agents directly in Snowflake CoWork and Cortex Code. See Cortex Agents Run API.
5. Monitor, evaluate, and iterate: Review threads, logs, and traces, collect end-user feedback as ratings and free-text comments, and run evaluations to refine the agent over its lifecycle. See Monitor Cortex Agent requests and Cortex Agent evaluations.

If you want to experiment before creating an agent object, you can call agent:run directly and pass the agent configuration with every request. See Create and manage agents.

When to use Cortex Agents¶

Cortex Agents is best for workloads that need:

• Reasoning across structured and unstructured data: Questions whose answers combine SQL results over semantic views with retrieval from documents and other unstructured sources.
• Multi-step task execution: Requests that the agent must break into subtasks, route to different tools, and reflect on intermediate results.
• Minimal infrastructure: No orchestration loop, runtime, or sandbox to build or operate; Snowflake manages all of it.
• Governance: Data access controlled by your existing Snowflake roles and privileges, inside Snowflake’s secure perimeter.
• Stateful conversations: Threads that persist context across turns without client-side state management.

Tools¶

Cortex Agents support the following tools:

For how to add and configure each tool, see Create and manage agents.

Access control and authentication¶

Calling an agent requires the SNOWFLAKE.CORTEX_USER or SNOWFLAKE.CORTEX_AGENT_USER database role, privileges on the agent object, and privileges on the objects used by the agent’s tools. Cortex Agents determines session permissions from the querying user’s default role. Requests to the Cortex Agents API must include an authorization token.

For the full requirements, including role setup, privilege tables, and authentication methods, see Access control and authentication.

Limitations¶

Cortex Agents APIs are not supported from within a Streamlit in Snowflake (SiS) application using a warehouse runtime. To call Cortex Agents APIs from a SiS app, use a container runtime instead. For more information, see Runtime environments for Streamlit apps.

Cost considerations¶

Cortex Agents incur charges for orchestration and for the tools the agent uses:

• Orchestration is charged based on the tokens used.
• Cortex Analyst is charged per token.
• Cortex Search charges depend on the size of the index and the time it has persisted.
• Custom tools incur warehouse costs, which depend on the size of the warehouse and how long it runs.

For more information, see the Snowflake Service Consumption Table.

Legal notices¶

Where your configuration of Cortex Agents uses a model provided on the Model and Service Flow-down Terms, your use of that model is further subject to the terms for that model on that page.

The data classification of inputs and outputs are as set forth in the following table.

For additional information, refer to Snowflake AI and ML.