Snowflake Agent¶

The Snowflake Agent is a third-party agent hosted on the Snowflake platform. It is built on top of Snowflake's Cortex agents and enables business teams to interact with their data through natural language. Cortex agents leverage generative AI tailored to an organization's specific data and terminology, allowing users to query and analyze data intuitively. By utilizing this foundation, the Snowflake Agent provides a seamless and intuitive data interaction experience.

Our AI Refinery SDK enables effortless integration with a user's customized Snowflake Agent through the SnowflakeAgent class. This integration unlocks the full potential of the Cortex Agent, enhancing performance and functionality within the AI Refinery platform.

Creating Snowflake Agents ¶

Users can customize a Snowflake Agent through the Snowflake platform. To create an agent, follow these steps:

Sign Up for and Log In to your user account on Snowflake.
Proceed (or ask your account admin) to enable required privileges for your account to be able to create Cortex agents on Snowflake platform.
Obtain your account's Programmatic Access Token (PAT) as the required credential. You will need this to configure your agent in AIR later.
Create a Cortex agent and connect it to your database(s). You can configure one or multiple Cortex Search and Cortex Analyst services for your Cortex agent, to handle queries related to both structured and unstructured data.
Obtain your account's base URL. You can find that under your account details on Snowflake platform. The format of that URL is as follows:
```
https://{your-account-identifier}.snowflakecomputing.com
```
You will also need this to configure your Snowflake agent in AIR later.
Test your Cortex agent on the Snowflake platform to interact with your data, explore the data tables or unstructured data sources it can access, and gain insights into its capabilities.

Onboarding Snowflake Agent¶

To use the Snowflake agents through our AI Refinery SDK, users need the following parameters:

Variable	Description	Required
`snowflake_password`	Mapping to the name of the environment variable that holds your PAT password.	Yes
`snowflake_services`	List of Cortex services that are configured for your Cortex Agent.	Yes
`snowflake_model`	Name of the underlying LLM model to use with this Cortex agent.	Yes
`snowflake_base_url`	Address of your Snowflake account's base URL.	Yes
`sql_timeout`	Timeout in seconds for execution of any SQL statement.	No
`system_prompt`	The instructions that the Cortex agent model follows when it generates the response.	No
`snowflake_experimental`	Experimental flags passed to the Cortex agent.	No
`snowflake_tool_choice`	The configuration used to select the tools for the Cortex agent.	No
`thought_process_tracing`	Optional variable for monitoring the thought processing steps of the Cortex Agent.	No
`contexts`	Allows for the provision of additional information during communication with the `Snowflake Agent`.	No

Workflow Overview¶

The workflow of the SnowflakeAgent class consists of four components:

Initialization: A Cortex agent is created on the Snowflake platform and is registered in AI Refinery with the specified configuration.
Sending a Query: A user query is forwarded from AI Refinery to the Cortex Agent running on the Snowflake platform.
Snowflake-side Processing: The Cortex Agent answers the user's query, either with a verbal response or with the generation of a SQL query. If a SQL command is generated, an SQL request is forwarded from AI Refinery to the SQL execution endpoint of Snowflake platform. The execution of that query will return either a numerical value or tabular data that answer the user's query.
Receiving and Parsing the Response: The SnowflakeAgent returns the processed results as its final response to AI Refinery.

Usage and Quickstart¶

To quickly set up an AI Refinery project with a SnowflakeAgent, users should begin by creating their own Cortex agent in Snowflake, as outlined earlier. Once the agent is prepared, utilize the YAML configuration template provided below to integrate it into the AI Refinery project. Specifically, ensure the following configurations are included:

Add a utility agent with agent_class: SnowflakeAgent under utility_agents.
Ensure the agent_name you chose for your SnowflakeAgent is listed in the agent_list under orchestrator.

Template YAML Configuration of SnowflakeAgent¶

See the YAML template below for the SnowflakeAgent configuration.

orchestrator:
  agent_list:
    - agent_name: "Snowflake Agent"  # The name you choose for your Snowflake agent. 

utility_agents:
  - agent_class: SnowflakeAgent
    agent_name: "Snowflake Agent"  # The name you choose for your Snowflake agent
    agent_description: "The Snowflake Agent can answer questions regarding orders recorded in the Snowflake databases."
    config:
      snowflake_password: "SNOWFLAKE_PASSWORD" # Required: Environment variable holding SNOWFLAKE Programmatic Access Token (PAT)
      snowflake_services:  # Required: Dictionary containing the information of the Cortex services configured for this Cortex Agent.
        search:  # Required: List of the required Cortex Search services.
          - name: <name of the service>  # Required: Arbitrary name you choose for this Cortex Search service.
            database: <database name>  # Required: Name of the database of this Cortex Search service.
            db_schema: <schema name>  # Required: Name of the schema of this Cortex Search service.
            service_name: <name of the Cortex Search>  # Required: Name of the Cortex Search service as recorded on the Snowflake platform.
        analyst:  # Required: List of the required Cortex Analyst services.
          - name: <name of the service>  # Required: Arbitrary name you choose for this Cortex Analyst service.
            database: <database name>  # Required: Name of the database of this Cortex Analyst service.
            db_schema: <schema name>  # Required: Name of the schema of this Cortex Analyst service.
            stage: <stage name>  # Required: Name of the stage of this Cortex Analyst service.
            file_name: <file name>  # Required: Name of the schema of this Cortex Analyst service.
            warehouse: <warehouse name>  # Required: Name of the warehouse of this Cortex Analyst service.
            user_role: <user role>  # Required: User role that has access to this Cortex agent. 
      snowflake_model: <LLM model>  # Required: Name of the LLM model to use with this Snowflake Cortex agent.
      snowflake_base_url: <account's base url>  # Required: Base URL Address of your Snowflake account.
      sql_timeout: <timeout in seconds>  # Optional: Timeout in seconds for execution of any SQL statement (default: 10).
      system_prompt: <response instructions>  # Optional: The instructions that the Cortex agent follows when it generates the response.
      snowflake_experimental: <experimental flags>  # Optional: Experimental flags passed to the Cortex agent (default: {}).
      snowflake_tool_choice: <tool choice>  # Optional: Configuration used to select the tools for the Cortex agent (default: "auto").
      thought_process_tracing: <tracing flag>  # Optional: Boolean flag for monitoring the thought process steps of the Cortex agent (default: False).
      contexts: # Optional additional agent contexts
        - "date"
        - "chat_history"