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. 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.
Description

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
Description

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;

Then, create the agent instance. .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>

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.

Notes and Limitations

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.