Skip to main content
Contextual AI enables you to create enterprise-grade AI agents grounded in your documents and data. In just a few steps, you can install Contextual AI as a native Snowflake app and create powerful AI agents in the security of your Snowflake environment. You can access Contextual AI native Snowflake app using the following methods:

​
Installation

Get started by installing Contextual AI from the Snowflake Marketplace and activating it in Snowsight.

​
Activating the Contextual AI app in Snowflake

  1. Log in to Snowflake and search for Contextual AI from the homepage.
You can also go to the Snowflake Marketplace and search for Contextual AI there.
  1. Select Contextual AI Platform from the search results.
  2. Click the Start trial button on the installation page.
  3. Click Configure after the app finishes installing.
  4. Click the Grant button to give CREATE COMPUTE POOL and BIND SERVICE ENDPOINT privileges to the Contextual AI app.
  5. Click Activate in the Snowsight UI to begin using the Contextual AI app in your Snowflake environment.
Note: This step may take up to 1 hour to process. You’ll get an email from Snowflake when installation is complete and the app is ready to use.

​
Contextual AI Agent Setup

  1. Go to Catalog -> Apps to verify that the Contextual AI app has finished installing. The status of the app should display Installed.
  1. Click on Contextual AI Platform to view its app catalog page.
  2. Click Launch App to run the Contextual AI app and log in with your Snowflake credentials.
Note: The first user accessing the app is automatically designated as the Admin User, so we recommend having your team’s administrator be the one to load it first.
  1. Click the + New Agent button on the top right of the Agents page. You will see the Contextual AI dashboard and the place where you’ll create your first AI Agent and its new datastore.
  2. On the Create Agent page, give your agent a unique Agent Name and Description.
  3. Make sure the Create a new datastore radio button is selected. This will tell Contextual AI to create an accompanying datastore with the same name as your agent.
  4. Click the Create button at the bottom of the page to save your configuration and create your agent.

​
Adding Knowledge to Your Agent’s Datastore

You now need to add knowledge to your agent’s datastore to make it grounded in real world knowledge for responding to your prompts.
  1. Click Datastores on the left-hand side and locate your agent’s newly created datastore.
  2. Click the Documents button on the right-hand side of your agent’s datastore.
  3. Select the Ingest tab to upload a document (for example, a Microsoft Word or PDF file).
  4. Drag and drop or select a file to upload and click the Start Uploading button. The system will automatically begin processing it in the background. This process extracts information from your documents and prepares them for future retrieval by your agents.
  1. Wait until your document has been uploaded and processed. Contextual AI will indicate that your document is done with the Processed status indicator.
  2. Click the Agents button on the left-hand side followed by your agent’s tile to start interacting with your agent.
  3. Your agent can now access and reference the knowledge from your uploaded documents during conversations. Try asking your agent a question in the prompt window.

​
Using the Contextual AI REST API

Contextual AI provides a REST API for programmatic interaction with your agents and datastore. After you have created and configured an agent and its datastore through the UI, you can integrate it into your applications and workflows using API endpoints. API Access in the Contextual AI Native App requires obtaining the API endpoint of your instance, which can be found by running this Snowflake query in a Snowflake worksheet or via the Snowflake CLI: 
CALL CONTEXTUAL_NATIVE_APP.CORE.GET_API_ENDPOINT()
You will receive a response formatted as a URL: xxxxx-xxxxx-xxxxx.snowflakecomputing.app. This URL value is the backend API endpoint for your application. To create the full API endpoint, you will need to prepend https:// to the backend API endpoint from your application and then append /v1 at the end. An example of how to do this in Python: 
SF_BASE_URL = 'xxxxx-xxxxx-xxxxx.snowflakecomputing.app' # what you will receive from GET_API_ENDPOINT()
BASE_URL = f'https://{SF_BASE_URL}/v1' # using python3 f-string formatting
For authentication, instead of using an API key, the Snowflake Native App version of Contextual AI uses a Snowflake token, which can be retrieved using the following Python code: 
ctx = snowflake.connector.connect(
   user="",# snowflake account user
   password='', # snowflake account password
   account="organization-account", # format: <organization>-<account> (e.g., myorg-account123)
   session_parameters={
      'PYTHON_CONNECTOR_QUERY_RESULT_FORMAT': 'json'
   })

# Obtain a session token.
token_data = ctx._rest._token_request('ISSUE')
token_extract = token_data['data']['sessionToken']

# Create a request to the ingress endpoint with authz.
api_key = f'\"{token_extract}\"'
Once you have your API key, you can combine the steps above to create a Contextual AI client in Python that is configured to use your Contextual AI Native App in Snowflake to make programmatic queries to your agents. 
SF_BASE_URL = 'xxxxx-xxxxx-xxxxx.snowflakecomputing.app' # what you will receive from GET_API_ENDPOINT()
BASE_URL = f'https://{SF_BASE_URL}/v1'

ctx = snowflake.connector.connect( # type: ignore
   user="",# snowflake account user
   password='', # snowflake account password
   account="organization-account", # snowflake organization and account <Organization>-<Account>
   session_parameters={
      'PYTHON_CONNECTOR_QUERY_RESULT_FORMAT': 'json'
   })

# Obtain a session token.
token_data = ctx._rest._token_request('ISSUE') # type: ignore
token_extract = token_data['data']['sessionToken'] # type: ignore

# Create a request to the ingress endpoint with authz.
api_key = f'\"{token_extract}\"'

client = ContextualAI(api_key=api_key, base_url=BASE_URL)

# get list of agents to test API
agents = [a for a in client.agents.list()]
Note: We recommend using the Contextual AI Python SDK to interact with the API. An example script of our Python SDK and Snowflake Native App can be found here.