# Snowflake Cortex Agents & Tools

The **Snowflake Cortex Agents & Tools** plugin allows you to connect and interact with Snowflake Cortex Agents, Cortex Search, and Cortex Analyst services directly within Dataiku.

## Concept

This plugin integrates Snowflake's generative AI capabilities into the Dataiku ecosystem, offering two primary workflows: orchestrating full Snowflake-managed agents or equipping standard Dataiku agents with specialized Cortex tools.

### Key Features

* **Agent Orchestration:** Interact with Snowflake-managed agents that handle planning, tool use, and reflection directly from Dataiku.
* **Cortex Search:** Enable agents to retrieve relevant documents from Snowflake stages using a Cortex Search service.
* **Cortex Analyst:** Empower agents to ask business questions of structured tables using Cortex Analyst Text-to-SQL capabilities backed by Semantic Views or Models.
* **Agent Discovery:** Automatically fetches and lists available Cortex Agents from your Snowflake database and schema.
* **Secure Authentication:** Uses Snowflake OAuth 2.0 for secure connections to Cortex services.

## 📋 Prerequisites

### Dataiku Requirements

* **Dataiku DSS version**: Recommended 14.3.0 or later (token refresh capabilities optimized for 14.4+).  
* **Python version**: 3.11+

### Snowflake Requirements

* **Snowflake Connection**: A Dataiku connection to Snowflake configured with **OAuth 2.0** (required for Cortex Analyst and Agents).  
* **Cortex Services**:  
  * For Agents: A pre-existing Cortex Agent created in Snowflake.  
  * For Search: A configured Cortex Search service with a document corpus.  
  * For Analyst: A Semantic View or Semantic Model (`.yaml`) uploaded to a Snowflake stage.

## 📦 Installation

- Follow the Dataiku guide to [install plugins](https://doc.dataiku.com/dss/latest/plugins/installing.html)  
- The plugin will create a code environment with the following dependencies:

```shell
snowflake-snowpark-python[pandas]
aiohttp

```

## 🎯 Usage

### Option 1: Snowflake Cortex Agent

Use this option to connect to an agent that is already defined and running inside Snowflake.

#### Create Agent in Project

1. Go to your Dataiku project.  
2. Navigate to **Agents & GenAI Models** → **\+ New Agent**.  
3. Select **Snowflake Cortex Agent**.  
   ![Fig 1. Create a new Cortex Agent](images/cortex_agents_create.png)

#### Configure Agent

* **Snowflake Connection**: Select your OAuth-enabled Snowflake connection.  
* **Cortex Agent Database & Schema**: Enter the location of your agent in Snowflake (e.g., `SNOWFLAKE_INTELLIGENCE`, `AGENTS`).  
* **Cortex Agent Name**: Select from the dropdown of available agents. The list allows you to choose from agents existing in the specified schema.  
* **Advanced**: Configure network timeouts, max retries, and retry delays.  
  ![Fig 2. Configure the Cortex Agent](images/cortex_agents_config.png)

#### Test Agent

Use the **Chat** tab to test your agent. The agent will process natural language, utilize its registered tools (like Search or Analyst), and return a response with citations.

### Option 2: Cortex Tools

Use this option to add Snowflake capabilities to a standard Dataiku Agent.

#### Add Tools to Agent

1. Create a **Visual Agent** or **Code Agent** in Dataiku.  
2. Add a new tool and search for:  
* **Snowflake Cortex Search**: For document retrieval.  
* **Snowflake Cortex Analyst**: For structured data analysis (Text-to-SQL).

#### Configure Tools

* **Cortex Search Tool**: Requires the Service Name, Max Documents to retrieve, and the columns to search/return.  
  ![Fig 3. Configure the Cortex Search tool](images/cortex_search_tool_config.png)  
* **Cortex Analyst Tool**: Requires the path to a **Semantic View** (e.g., `DB.SCHEMA.VIEW`) or a **Semantic Model File** (e.g., `@DB.SCHEMA.STAGE/model.yaml`).  
  ![Fig 4. Configure the Cortex Analyst Tool](images/cortex_analyst_tool_config.png)

## 🚧 Limitations

* **Authentication**: The Cortex Analyst and Cortex Agent APIs strictly require an **OAuth** connection to Snowflake.  
* **Semantic Models**: Cortex Analyst requires a well-defined Semantic Model (YAML or View) to function correctly; it cannot query raw tables without this layer.
