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 default_table_prefix 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

Feature access

This feature is currently available by request. Please contact the team at graph-analytics-snowflake@neo4j.com to enable access to this experimental functionality.

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.

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.

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,
  default_table_prefix VARCHAR
);

Table 1. Parameters
Name	Type	Optional	Description
agent_name	VARCHAR	no	Unique identifier for the agent instance
default_table_prefix	VARCHAR	no	Database and schema prefix for table references used by the agent as input to and output from graph algorithms.

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 (results_observer__{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

USE ROLE ACCOUNTADMIN;
-- Create database and schema
CREATE DATABASE IF NOT EXISTS AN_AGENT_DEMO_DB;
USE DATABASE AN_AGENT_DEMO_DB;
CREATE SCHEMA IF NOT EXISTS A_SCHEMA;
USE SCHEMA A_SCHEMA;

-- Create a consumer role for users of the Graph Analytics application
CREATE ROLE IF NOT EXISTS USER_ROLE;
GRANT APPLICATION ROLE Neo4j_Graph_Analytics.app_user TO ROLE USER_ROLE;
SET MY_USER = (SELECT CURRENT_USER());
GRANT ROLE USER_ROLE TO USER IDENTIFIER($MY_USER);
-- Set the default role for the user to the consumer role
ALTER USER IDENTIFIER($MY_USER) SET DEFAULT_ROLE = USER_ROLE;
-- Grants needed for the app to read consumer data stored in tables and views
USE DATABASE AN_AGENT_DEMO_DB;
CREATE DATABASE ROLE IF NOT EXISTS DB_ROLE;
GRANT USAGE ON DATABASE AN_AGENT_DEMO_DB TO DATABASE ROLE DB_ROLE;
GRANT USAGE ON SCHEMA AN_AGENT_DEMO_DB.A_SCHEMA TO DATABASE ROLE DB_ROLE;
GRANT SELECT ON ALL TABLES IN SCHEMA AN_AGENT_DEMO_DB.A_SCHEMA TO DATABASE ROLE DB_ROLE;
GRANT SELECT ON ALL VIEWS IN SCHEMA AN_AGENT_DEMO_DB.A_SCHEMA TO DATABASE ROLE DB_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA AN_AGENT_DEMO_DB.A_SCHEMA TO DATABASE ROLE DB_ROLE;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA AN_AGENT_DEMO_DB.A_SCHEMA TO DATABASE ROLE DB_ROLE;
GRANT CREATE TABLE ON SCHEMA AN_AGENT_DEMO_DB.A_SCHEMA TO DATABASE ROLE DB_ROLE;
GRANT DATABASE ROLE DB_ROLE TO APPLICATION Neo4j_Graph_Analytics;
GRANT DATABASE ROLE DB_ROLE TO ROLE USER_ROLE;
-- Grant warehouse usage
GRANT USAGE ON WAREHOUSE <default_warehouse> TO ROLE USER_ROLE;
GRANT USAGE ON WAREHOUSE <default_warehouse> TO APPLICATION Neo4j_Graph_Analytics;
-- Grant Cortex Agent User role
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE USER_ROLE;
-- Grant AI Observability Events Lookup role
GRANT APPLICATION ROLE SNOWFLAKE.AI_OBSERVABILITY_EVENTS_LOOKUP TO ROLE USER_ROLE;

Then, create the agent instance.

The feature must be enabled in your account to make create_agent procedure available. See Feature access for more details.

Example of Creating the Agent

-- Use the consumer role to create the agent
USE ROLE USER_ROLE;
USE DATABASE AN_AGENT_DEMO_DB;
USE SCHEMA A_SCHEMA;

---
<Enable experimental features if not already done>

-- Create the agent
CALL Neo4j_Graph_Analytics.experimental.create_agent(
  'Neo4j_Graph_Analytics_Agent',
  'AN_AGENT_DEMO_DB.A_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>

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.

Notes and Limitations

Editing available results in the semantic view

The AVAILABLE_RESULTS__{agent_name} table contains the list of results that the agent includes in the semantic view. You can view, delete, or modify entries in this table as needed. After making changes, call the _UPDATE_SEMANTIC_VIEW procedure to refresh the semantic view and reflect the changes.

Example of Modifying Available Results

-- View available results
SELECT * FROM Neo4j_Graph_Analytics.EXPERIMENTAL.AVAILABLE_RESULTS__NEW_AGENT;

-- Let a specific result table should no longer be included in the semantic view
-- For example, removing RESULT_PAGE_RANK_C3P5WY table from the semantic view
DELETE FROM Neo4j_Graph_Analytics.EXPERIMENTAL.AVAILABLE_RESULTS__NEW_AGENT
WHERE CONFIGURATION ILIKE '%RESULT_PAGE_RANK_C3P5WY%';

-- Update the semantic view to reflect changes
CALL Neo4j_Graph_Analytics.EXPERIMENTAL._UPDATE_SEMANTIC_VIEW('Neo4j_Graph_Analytics_Agent');

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.