Agent for CortexAI

Upgrading from a previous release? EXPERIMENTAL.CREATE_AGENT has been removed. Use GRAPH.CREATE_AGENT to create agents, and EXPERIMENTAL.DROP_AGENT to clean up any agents created before the migration. See Migrating from the EXPERIMENTAL API for upgrade steps.

Overview

The application provides Neo4j Agent — an agent that can be integrated with:

  • Cortex AI (search, analyst, document parsing) and security for building custom AI apps.

  • Snowflake Intelligence, an agentic UI application powered by Cortex that allows business users to converse with, analyze, and act on data via natural language.

In either context, the agent simplifies working with graph algorithms by automating the creation of views required to project the graph, select the appropriate algorithm to solve the problem, generate the required configuration, execute the job, and manage the results.

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 source_schema parameter specifies the read-only database and schema containing the source data tables. The working_schema parameter specifies the database and schema where the agent creates views and writes algorithm results.

A walkthrough of the agent is available in this video.

Prerequisites

Before creating an agent, ensure the following requirements are met:

  • Neo4j Graph Analytics is installed in your Snowflake account.

  • Snowflake Cortex is enabled for your account. Cortex Agents require access to Cortex AI features; contact your account administrator if unsure.

  • A virtual warehouse is available and the role you use has USAGE privilege on it. The agent uses the default warehouse of the calling role.

  • The CORTEX_AGENT_USER database role must be granted to the role that will interact with the agent:

    GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE <your_role>;

  • Cross-region model access may be required if claude-sonnet-4-5 is not available in your region. See Troubleshooting for details.

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 Initial 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, ArticleRank, Betweenness Centrality, Degree Centrality

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

  • Path Finding: Dijkstra, Dijkstra Single Source, Delta Stepping, Yen’s

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

  • Embeddings: Node2Vec, FastRP, HashGNN

  • Machine Learning: GraphSAGE Node Classification (training and prediction), GraphSAGE Node Embedding (training and prediction)

  • Clustering: K-Means

  • Flow: Maximum Flow, Minimum Cost Maximum Flow

You can always ask the agent directly for the up-to-date list of supported algorithms.

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.

Application Schemas

The agent feature spans three dedicated schemas within the application:

Schema Purpose

GRAPH

Public API. Contains CREATE_AGENT and DROP_AGENT — the procedures you call to manage agent instances.

AGENT_TOOLS

Internal tools used by the agent during conversations (run algorithms, create views, update the semantic view, etc.). These procedures are not intended for direct use, but are accessible if needed for advanced scenarios.

AGENT_ARTEFACTS

Stores objects created and managed by the agent: the context table, config table, and semantic view for each agent instance. Objects here are named with the agent name as a suffix, e.g. AGENT_CONTEXT__MY_AGENT.

Example fully qualified names for an agent named MY_AGENT installed as NEO4J_GRAPH_ANALYTICS:

  • NEO4J_GRAPH_ANALYTICS.GRAPH.CREATE_AGENT

  • NEO4J_GRAPH_ANALYTICS.AGENT_ARTEFACTS.GRAPH_ANALYTICS_SV__MY_AGENT

  • NEO4J_GRAPH_ANALYTICS.AGENT_ARTEFACTS.AGENT_CONTEXT__MY_AGENT

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.graph.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.graph.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 removes the agent and its internal artefacts from the AGENT_ARTEFACTS schema:

  • The agent object itself

  • The AGENT_CONTEXT__{agent_name} table (algorithm and data layout configurations)

  • The AGENT_CONFIG__{agent_name} table (agent settings)

  • The GRAPH_ANALYTICS_SV__{agent_name} semantic view

Result tables and views created in working_schema during algorithm runs are not deleted. Those are user data and must be cleaned up manually if no longer needed.

After dropping, 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}}.GRAPH.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.graph.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, the recommended way to explore results is through the agent’s Cortex Analyst tool using natural language. The agent automatically keeps the semantic view up to date after each algorithm run.

Using the Agent for Analysis

Ask the agent directly in 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?"

Inspecting the Semantic View Structure

To see which tables and columns the semantic view exposes, use DESCRIBE:

DESCRIBE SEMANTIC VIEW Neo4j_Graph_Analytics.AGENT_ARTEFACTS.GRAPH_ANALYTICS_SV__NEO4J_GRAPH_ANALYTICS_AGENT;

Result tables written to working_schema can also be queried directly:

SELECT * FROM AGENT_DATA.RESULT_SCHEMA.RESULT_PAGE_RANK_C3P5WY
ORDER BY PAGERANK DESC
LIMIT 10;

Notes and Limitations

Editing available results in the semantic view

The AGENT_CONTEXT__{agent_name} table stores all algorithm result configurations and data layout configurations used to build the semantic view. Each row has a tag column (the algorithm tag for results, e.g. wcc, page_rank, or data_layout for graph projection configuration) and a configuration JSON column. You can view, delete, or modify entries in this table as needed. After making changes, call AGENT_TOOLS._UPDATE_GRAPH_ANALYTICS_SEMANTIC_VIEW with your agent name, the appropriate algorithm tag or data_layout, and the configuration JSON needed for that update so the semantic view can be recreated.

Example of Modifying Available Results
-- View all context entries (algorithm results and data layouts)
SELECT * FROM Neo4j_Graph_Analytics.AGENT_ARTEFACTS.AGENT_CONTEXT__NEO4J_GRAPH_ANALYTICS_AGENT;

-- View only algorithm results
SELECT * FROM Neo4j_Graph_Analytics.AGENT_ARTEFACTS.AGENT_CONTEXT__NEO4J_GRAPH_ANALYTICS_AGENT
WHERE TAG != 'data_layout';

-- View only data layout configurations
SELECT * FROM Neo4j_Graph_Analytics.AGENT_ARTEFACTS.AGENT_CONTEXT__NEO4J_GRAPH_ANALYTICS_AGENT
WHERE TAG = 'data_layout';

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

-- Refresh the semantic view to reflect changes (replace tag and configuration JSON to match your edit)
CALL Neo4j_Graph_Analytics.AGENT_TOOLS._UPDATE_GRAPH_ANALYTICS_SEMANTIC_VIEW(
  'Neo4j_Graph_Analytics_Agent',
  '<tag>',
  '<configuration_json>'
);

Migrating from the EXPERIMENTAL API

The agent management procedures have moved from the EXPERIMENTAL schema to the GRAPH schema. EXPERIMENTAL.CREATE_AGENT has been removed. EXPERIMENTAL.DROP_AGENT is retained solely to clean up agents created before the migration, because their artefacts reside in the AGENT_EXPERIMENTAL schema which GRAPH.DROP_AGENT does not touch.

Agents created with EXPERIMENTAL.CREATE_AGENT must be recreated using the new API because their internal specification references removed procedures.

Dropping and recreating an agent does not delete result tables in working_schema. After recreating the agent, re-run the algorithms or add the previous results back to the agent context so the semantic view is rebuilt.

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';