Integration with Cortex Agent

This feature is experimental and may change without notice.

Overview

The application provides integration with the Cortex Agent feature. This agent simplifies the process of working with graph algorithms by automating configuration generation, execution, and result management. The agent provides several key capabilities:

  • Configuration Building: Assists users in building configurations and executing calls to run algorithms directly within the application.

  • Algorithm Reference: Provides reference information about available algorithms, including descriptions, parameter details, and expected outputs.

  • Result Integration: Connects semantic views with results generated after algorithm computations are complete.

  • Dynamic Semantic View Creation: Automatically creates semantic views from data used as input for analytics algorithms.

Each agent instance operates in isolation; agents with different names do not interfere with each other’s data or results. The working_schema parameter defines the database and schema prefix for table references used by the agent as input to and output from graph algorithms.

A walkthrough of the agent is available in this video.

Important Disclaimers

Default role usage

The Cortex Agent operates under the default user role and uses default warehouse. See the Snowflake documentation page for details.

Ensure that the default role has the necessary permissions to interact with the agent and access the required resources. Refer to the usage example in the section Agent Experimental Usage Setup for guidance on configuring the necessary permissions.

Do not use any privileged roles (e.g., ACCOUNTADMIN) as the default role, as this may lead to security risks. Limit the default role access to only the required resources and permissions for the agent.

Model availability

By default, the agent uses the claude-sonnet-4-5 model. Ensure that this model is available in your region. If it is not available in your region, enable cross-region model access by setting the CORTEX_ENABLED_CROSS_REGION account parameter. See Troubleshooting for details.

Key Features and Capabilities

Configuration Building and Execution

The agent assists in constructing complete algorithm configurations and provides information about the algorithm. Once a configuration is built, the agent can execute the algorithm and manage the results automatically.

Result Observation via Cortex Analyst

The agent provides a Cortex Analyst tool that allows users to query and explore algorithm results together with the original tables used for graph projection. This tool leverages a semantic view, dynamically created and maintained by the agent. The semantic views provide a unified interface for querying both input graph data and computed results, enabling seamless analysis of algorithm outputs in the context of the original graph structure.

Supported Algorithms

The agent can help configure and execute the following algorithms:

  • Centrality: PageRank, Betweenness Centrality, Degree Centrality

  • Community Detection: Louvain, Leiden, WCC (Weakly Connected Components), Triangle Count

  • Path Finding: Dijkstra, Dijkstra Single Source, Delta Stepping

  • Similarity: Node Similarity, KNN (K-Nearest Neighbors)

  • Embeddings: Node2Vec, FastRP, HashGNN

  • Clustering: K-Means

Semantic View Structure

The agent maintains a semantic view (GRAPH_ANALYTICS_SV__{agent_name}) that includes:

  • Input tables: Node and relationship tables defined in the data layout

  • Result tables: Algorithm output tables with computed properties

  • Relationships: Foreign key references between result tables and input node tables

  • Facts and Dimensions: Columns from both input tables and results, categorized for analytics

The semantic view is automatically updated when you run algorithms or modify the data layout.

API Reference

CREATE_AGENT

Creates and configures a new agent instance with the necessary infrastructure for semantic view management and algorithm execution.

Syntax
CALL Neo4j_Graph_Analytics.experimental.create_agent(
  agent_name VARCHAR,
  source_schema VARCHAR,
  working_schema VARCHAR
);
Table 1. Parameters
Name Type Optional Description

agent_name

VARCHAR

no

Unique identifier for the agent instance. Agent name must start with a letter or underscore, followed by letters, digits, underscores, or dollar signs.

source_schema

VARCHAR

no

Database and schema prefix for tables used as input to graph algorithms.

working_schema

VARCHAR

no

Database and schema prefix for tables created by the agent to store results.

The CREATE_AGENT procedure performs the following operations:

  • Configures the agent with orchestration settings and tool specifications

  • Creates agent-specific tables for storing algorithm configurations and results

  • Initializes a semantic view for the agent (graph_analytics_sv__{agent_name})

  • Sets up necessary permissions for the application role

DROP_AGENT

Removes an agent instance and cleans up all associated resources, including tables and semantic views created by the agent.

Syntax
CALL Neo4j_Graph_Analytics.experimental.drop_agent(
  agent_name VARCHAR
);
Table 2. Parameters
Name Type Optional Description

agent_name

VARCHAR

no

Unique identifier for the agent instance to drop

This procedure completely removes the agent and all its associated resources from the system. After destruction, the agent name can be reused to create a new agent instance if needed.

Usage Examples

Initial Setup

Before using the agent, you must create the agent and configure the necessary permissions.

Setting the Required Permissions — TEMPLATE
USE ROLE ACCOUNTADMIN;

-- Create database
CREATE DATABASE IF NOT EXISTS {{WORKING_DATABASE_NAME}};
USE DATABASE {{WORKING_DATABASE_NAME}};

-- Create consumer role
CREATE ROLE IF NOT EXISTS {{CONSUMER_ROLE}};
GRANT APPLICATION ROLE {{APP_NAME}}.app_admin TO ROLE {{CONSUMER_ROLE}};
GRANT APPLICATION ROLE {{APP_NAME}}.app_user TO ROLE {{CONSUMER_ROLE}};

SET MY_USER = (SELECT CURRENT_USER());
GRANT ROLE {{CONSUMER_ROLE}} TO USER IDENTIFIER($MY_USER);

-- Create working schema (for views and results)
CREATE SCHEMA IF NOT EXISTS {{WORKING_DATABASE_NAME}}.{{WORKING_SCHEMA}};

-- Create database role for app access
USE DATABASE {{SOURCE_DATABASE_NAME}};
CREATE DATABASE ROLE IF NOT EXISTS {{DB_ROLE}};

-- Grant database role permissions
GRANT USAGE ON DATABASE {{SOURCE_DATABASE_NAME}} TO DATABASE ROLE {{DB_ROLE}};
GRANT USAGE ON SCHEMA {{SOURCE_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};
GRANT USAGE ON DATABASE {{WORKING_DATABASE_NAME}} TO DATABASE ROLE {{DB_ROLE}};
GRANT USAGE ON SCHEMA {{WORKING_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};

-- Source schema: read-only
GRANT SELECT ON ALL TABLES IN SCHEMA {{SOURCE_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};
GRANT SELECT ON ALL VIEWS IN SCHEMA {{SOURCE_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};
GRANT SELECT ON FUTURE TABLES IN SCHEMA {{SOURCE_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};
GRANT SELECT ON FUTURE VIEWS IN SCHEMA {{SOURCE_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};

-- Working schema: read + write
GRANT SELECT ON FUTURE TABLES IN SCHEMA {{WORKING_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};
GRANT SELECT ON FUTURE VIEWS IN SCHEMA {{WORKING_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};
GRANT CREATE TABLE ON SCHEMA {{WORKING_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};
GRANT CREATE VIEW ON SCHEMA {{WORKING_SCHEMA_FQ}} TO DATABASE ROLE {{DB_ROLE}};

-- Grant database role to app and consumer role
GRANT DATABASE ROLE {{DB_ROLE}} TO APPLICATION {{APP_NAME}};
GRANT DATABASE ROLE {{DB_ROLE}} TO ROLE {{CONSUMER_ROLE}};
GRANT DATABASE ROLE {{DB_ROLE}} TO ROLE ACCOUNTADMIN;

-- Consumer role database access
GRANT USAGE ON DATABASE {{SOURCE_DATABASE_NAME}} TO ROLE {{CONSUMER_ROLE}};
GRANT USAGE ON DATABASE {{WORKING_DATABASE_NAME}} TO ROLE {{CONSUMER_ROLE}};
GRANT USAGE ON SCHEMA {{SOURCE_SCHEMA_FQ}} TO ROLE {{CONSUMER_ROLE}};
GRANT USAGE ON SCHEMA {{WORKING_SCHEMA_FQ}} TO ROLE {{CONSUMER_ROLE}};
GRANT SELECT ON FUTURE TABLES IN SCHEMA {{SOURCE_SCHEMA_FQ}} TO ROLE {{CONSUMER_ROLE}};
GRANT SELECT ON FUTURE TABLES IN SCHEMA {{WORKING_SCHEMA_FQ}} TO ROLE {{CONSUMER_ROLE}};
GRANT SELECT ON FUTURE VIEWS IN SCHEMA {{WORKING_SCHEMA_FQ}} TO ROLE {{CONSUMER_ROLE}};

-- Cortex agent permissions
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE {{CONSUMER_ROLE}};

-- =============================================================================
-- Create Agent
-- =============================================================================

USE ROLE {{CONSUMER_ROLE}};
USE SCHEMA {{WORKING_SCHEMA_FQ}};
USE WAREHOUSE {{WAREHOUSE_NAME}};

CALL {{APP_NAME}}.EXPERIMENTAL.CREATE_AGENT('{{AGENT_NAME}}', '{{SOURCE_SCHEMA_FQ}}', '{{WORKING_SCHEMA_FQ}}');

Let’s see an example of setting up the required permissions and creating an agent.

Setting the Required Permissions
USE ROLE ACCOUNTADMIN;

-- Create database
CREATE DATABASE IF NOT EXISTS AGENT_DATA;
USE DATABASE AGENT_DATA;

-- Create consumer role
CREATE ROLE IF NOT EXISTS AGENT_DEMO_ROLE;
GRANT APPLICATION ROLE NEO4J_GRAPH_ANALYTICS.APP_ADMIN TO ROLE AGENT_DEMO_ROLE;
GRANT APPLICATION ROLE NEO4J_GRAPH_ANALYTICS.APP_USER TO ROLE AGENT_DEMO_ROLE;

SET MY_USER = (SELECT CURRENT_USER());
GRANT ROLE AGENT_DEMO_ROLE TO USER IDENTIFIER($MY_USER);

-- Create working schema (for views and results)
CREATE SCHEMA IF NOT EXISTS AGENT_DATA.RESULT_SCHEMA;

-- Create database role for app access
USE DATABASE AGENT_DATA;
CREATE DATABASE ROLE IF NOT EXISTS DEMO_AGENT_DB_ROLE;

-- Grant database role permissions
GRANT USAGE ON DATABASE AGENT_DATA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT USAGE ON SCHEMA AGENT_DATA.INPUT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT USAGE ON DATABASE AGENT_DATA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT USAGE ON SCHEMA AGENT_DATA.RESULT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;

-- Source schema: read-only
GRANT SELECT ON ALL TABLES IN SCHEMA AGENT_DATA.INPUT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT SELECT ON ALL VIEWS IN SCHEMA AGENT_DATA.INPUT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA AGENT_DATA.INPUT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA AGENT_DATA.INPUT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;

-- Working schema: read + write
GRANT SELECT ON FUTURE TABLES IN SCHEMA AGENT_DATA.RESULT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA AGENT_DATA.RESULT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT CREATE TABLE ON SCHEMA AGENT_DATA.RESULT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;
GRANT CREATE VIEW ON SCHEMA AGENT_DATA.RESULT_SCHEMA TO DATABASE ROLE DEMO_AGENT_DB_ROLE;

-- Grant database role to app and consumer role
GRANT DATABASE ROLE DEMO_AGENT_DB_ROLE TO APPLICATION NEO4J_GRAPH_ANALYTICS;
GRANT DATABASE ROLE DEMO_AGENT_DB_ROLE TO ROLE AGENT_DEMO_ROLE;
GRANT DATABASE ROLE DEMO_AGENT_DB_ROLE TO ROLE ACCOUNTADMIN;

-- Consumer role database access
GRANT USAGE ON DATABASE AGENT_DATA TO ROLE AGENT_DEMO_ROLE;
GRANT USAGE ON SCHEMA AGENT_DATA.INPUT_SCHEMA TO ROLE AGENT_DEMO_ROLE;
GRANT USAGE ON SCHEMA AGENT_DATA.RESULT_SCHEMA TO ROLE AGENT_DEMO_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA AGENT_DATA.INPUT_SCHEMA TO ROLE AGENT_DEMO_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA AGENT_DATA.RESULT_SCHEMA TO ROLE AGENT_DEMO_ROLE;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA AGENT_DATA.RESULT_SCHEMA TO ROLE AGENT_DEMO_ROLE;

-- Cortex agent permissions
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE AGENT_DEMO_ROLE;

Then, create the agent instance.

Example of Creating the Agent
-- =============================================================================
-- Create Agent
-- =============================================================================
USE ROLE AGENT_DEMO_ROLE;
USE SCHEMA AGENT_DATA.RESULT_SCHEMA;

-- Create the agent
CALL Neo4j_Graph_Analytics.experimental.create_agent(
  'Neo4j_Graph_Analytics_Agent',
  'AGENT_DATA.INPUT_SCHEMA',
  'AGENT_DATA.RESULT_SCHEMA'
);

Interacting with the Agent

Once the agent is created, you can interact with it through Snowflake’s agent interface.

AI & ML → Agents → <Agent_Name>

or

AI & ML → Snowflake Intelligence

The agent understands natural language requests about graph algorithms and can:

  • Help identify which algorithm to use for a specific task

  • Build complete algorithm configurations based on your requirements

  • Execute algorithms with the proper parameters

  • Work with results via the dynamically updated Cortex Analyst tool

The semantic view provides a unified interface to both input graph data and computed results, making it easy to analyze algorithm outputs in context.

Example Prompts

Here are some example prompts you can use with the agent:

  • "What graph algorithms are available?"

  • "Describe my source data and suggest a graph model"

  • "Run PageRank on my airports data"

  • "Find communities in my network using Louvain"

  • "Calculate the shortest path between Edinburgh and Lima airports"

  • "Which nodes are most central in my graph?"

  • "Run betweenness centrality and show me the top 10 results"

Analyzing Results

After running algorithms, you can query the semantic view directly or use Cortex Analyst through the agent:

Querying the Semantic View Directly
-- View the semantic view structure
DESCRIBE SEMANTIC VIEW Neo4j_Graph_Analytics.AGENT_EXPERIMENTAL.GRAPH_ANALYTICS_SV__NEO4J_GRAPH_ANALYTICS_AGENT;

-- Query algorithm results joined with input data
SELECT
  props.NAME,
  props.CITY,
  results.PAGERANK
FROM Neo4j_Graph_Analytics.AGENT_EXPERIMENTAL.GRAPH_ANALYTICS_SV__NEO4J_GRAPH_ANALYTICS_AGENT
WHERE results.PAGERANK IS NOT NULL
ORDER BY results.PAGERANK DESC
LIMIT 10;
Using the Agent for Analysis

You can also ask the agent to analyze results using natural language:

  • "Show me the top 10 nodes by PageRank score with their names"

  • "Which communities have the most members?"

  • "What is the average path length in my results?"

Notes and Limitations

Editing available results in the semantic view

The AVAILABLE_RESULTS{agent_name} table contains the list of algorithm results that the agent includes in the semantic view. The DATA_LAYOUT{agent_name} table contains the data layout configurations for the input graph tables. You can view, delete, or modify entries in these tables as needed. After making changes, call the _UPDATE_GRAPH_ANALYTICS_SEMANTIC_VIEW procedure with NULL parameters to refresh the semantic view.

Example of Modifying Available Results
-- View available results
SELECT * FROM Neo4j_Graph_Analytics.AGENT_EXPERIMENTAL.AVAILABLE_RESULTS__NEO4J_GRAPH_ANALYTICS_AGENT;

-- View data layouts
SELECT * FROM Neo4j_Graph_Analytics.AGENT_EXPERIMENTAL.DATA_LAYOUT__NEO4J_GRAPH_ANALYTICS_AGENT;

-- Remove a specific result table from the semantic view
-- For example, removing RESULT_PAGE_RANK_C3P5WY table
DELETE FROM Neo4j_Graph_Analytics.AGENT_EXPERIMENTAL.AVAILABLE_RESULTS__NEO4J_GRAPH_ANALYTICS_AGENT
WHERE CONFIGURATION ILIKE '%RESULT_PAGE_RANK_C3P5WY%';

-- Refresh the semantic view to reflect changes
CALL Neo4j_Graph_Analytics.EXPERIMENTAL._UPDATE_GRAPH_ANALYTICS_SEMANTIC_VIEW(
  'Neo4j_Graph_Analytics_Agent',
  'AGENT_DATA.RESULT_SCHEMA',
  NULL,
  NULL
);

Agent Isolation

Each agent instance operates in isolation. Threads are not isolated in terms of the Cortex Analyst tool, which means that all threads of the same agent share the same semantic view. This isolation ensures that different agents do not interfere with each other’s data or results. To achieve isolation, create a new agent instance with a new agent_name or re-create the existing one.

Troubleshooting

If you receive the following error:

  • Error: <model> is not authorized or not available in your region. Please switch your agent configuration to use `auto for automatic model selection.`

Ask the account administrator to set the parameter CORTEX_ENABLED_CROSS_REGION.

Example:
USE ROLE ACCOUNTADMIN;
-- Enable all available AI models for the account
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';