与 Cortex Agent 集成

此功能为实验性功能，可能会在不另行通知的情况下发生更改。

概述

本应用程序提供了与 Cortex Agent 功能的集成。该代理通过自动化配置生成、执行和结果管理，简化了使用图算法的过程。该代理提供了多项关键功能：

  • 配置构建：协助用户构建配置，并直接在应用程序内执行算法调用。

  • 算法参考：提供有关可用算法的参考信息，包括说明、参数详情和预期输出。

  • 结果集成：将语义视图与算法计算完成后生成的结果进行连接。

  • 动态创建语义视图：自动根据用作分析算法输入的数据创建语义视图。

每个代理实例均独立运行；不同名称的代理不会干扰彼此的数据或结果。working_schema 参数定义了代理用于图算法输入和输出的表引用的数据库和架构前缀。

有关该代理的演练，请观看此视频。

重要免责声明

默认角色使用

Cortex Agent 在默认用户角色下运行并使用默认仓库。有关详细信息，请参阅 Snowflake 文档页面。

确保默认角色具有与代理交互并访问所需资源所需的权限。有关配置必要权限的指南，请参考 Agent 实验性使用设置部分中的使用示例。

请勿使用任何特权角色（例如 ACCOUNTADMIN）作为默认角色，因为这可能导致安全风险。将默认角色的访问权限限制为仅限代理所需的资源和权限。

模型可用性

默认情况下，代理使用 claude-sonnet-4-5 模型。请确保您的区域可以使用此模型。如果您的区域无法使用该模型，请通过设置 CORTEX_ENABLED_CROSS_REGION 账户参数来启用跨区域模型访问。有关详细信息，请参阅故障排除。

关键特性与功能

配置构建与执行

代理协助构建完整的算法配置，并提供有关算法的信息。一旦配置构建完成，代理即可自动执行算法并管理结果。

通过 Cortex Analyst 进行结果观察

代理提供了一个 Cortex Analyst 工具，允许用户查询和探索算法结果，以及用于图投影的原始表。此工具利用语义视图，该视图由代理动态创建和维护。语义视图为查询输入图数据和计算结果提供了一个统一的接口，使得在原始图结构的背景下进行算法输出分析变得无缝且高效。

支持的算法

代理可以帮助配置和执行以下算法：

  • 中心度 (Centrality)：PageRank、中介中心度 (Betweenness Centrality)、度中心度 (Degree Centrality)

  • 社区检测 (Community Detection)：Louvain、Leiden、WCC（弱连通分量）、三角形计数 (Triangle Count)

  • 路径查找 (Path Finding)：Dijkstra、Dijkstra 单源、Delta Stepping

  • 相似度 (Similarity)：节点相似度 (Node Similarity)、KNN (K-最近邻)

  • 嵌入 (Embeddings)：Node2Vec、FastRP、HashGNN

  • 聚类 (Clustering)：K-Means

语义视图结构

代理维护一个语义视图 (GRAPH_ANALYTICS_SV__{agent_name})，其中包含：

  • 输入表：数据布局中定义的节点和关系表

  • 结果表：具有计算属性的算法输出表

  • 关系：结果表与输入节点表之间的外键引用

  • 事实与维度：来自输入表和结果的列，按分析类别分类

当您运行算法或修改数据布局时，语义视图会自动更新。

API 参考

CREATE_AGENT

创建并配置一个新的代理实例，配备语义视图管理和算法执行所需的必要基础设施。

语法
CALL Neo4j_Graph_Analytics.experimental.create_agent(
  agent_name VARCHAR,
  source_schema VARCHAR,
  working_schema VARCHAR
);
表 1. 参数
名称 类型 可选 描述

agent_name

VARCHAR

否

代理实例的唯一标识符。代理名称必须以字母或下划线开头，后跟字母、数字、下划线或美元符号。

source_schema

VARCHAR

否

用作图算法输入的表的数据库和架构前缀。

working_schema

VARCHAR

否

代理为存储结果而创建的表的数据库和架构前缀。

CREATE_AGENT 过程执行以下操作：

  • 使用编排设置和工具规范配置代理

  • 创建用于存储算法配置和结果的代理专用表

  • 为代理初始化语义视图 (graph_analytics_sv__{agent_name})

  • 为应用程序角色设置必要的权限

DROP_AGENT

移除代理实例并清理所有关联资源，包括代理创建的表和语义视图。

语法
CALL Neo4j_Graph_Analytics.experimental.drop_agent(
  agent_name VARCHAR
);
表 2. 参数
名称 类型 可选 描述

agent_name

VARCHAR

否

要删除的代理实例的唯一标识符

此过程将从系统中彻底移除代理及其所有关联资源。销毁后，如果需要，可以重复使用代理名称来创建新的代理实例。

使用示例

初始设置

在使用代理之前，必须创建代理并配置必要的权限。

设置所需权限 — 模板
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}}');

让我们看一个设置所需权限并创建代理的示例。

设置所需权限
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;

然后，创建代理实例。

创建代理的示例
-- =============================================================================
-- 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'
);

与代理交互

创建代理后，可以通过 Snowflake 的代理界面与之交互。

AI & ML → Agents → <Agent_Name>

或

AI & ML → Snowflake Intelligence

代理能够理解有关图算法的自然语言请求，并且可以：

  • 帮助确定针对特定任务应使用哪种算法

  • 根据您的要求构建完整的算法配置

  • 使用正确的参数执行算法

  • 通过动态更新的 Cortex Analyst 工具处理结果

语义视图为输入图数据和计算结果提供了一个统一的接口，使得在背景中分析算法输出变得简单。

提示词示例

以下是您可以与代理一起使用的一些提示词示例：

  • "有哪些可用的图算法？"

  • "描述我的源数据并建议一个图模型"

  • "在我的机场数据上运行 PageRank"

  • "使用 Louvain 在我的网络中查找社区"

  • "计算爱丁堡机场和利马机场之间的最短路径"

  • "我的图中哪些节点最中心？"

  • "运行中介中心度并向我显示前 10 个结果"

分析结果

运行算法后，您可以直接查询语义视图，或通过代理使用 Cortex Analyst：

直接查询语义视图
-- 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;
使用代理进行分析

您还可以要求代理使用自然语言分析结果：

  • "向我显示按 PageRank 得分排名的前 10 个节点及其名称"

  • "哪些社区的成员最多？"

  • "我的结果中平均路径长度是多少？"

注意事项与限制

编辑语义视图中的可用结果

AVAILABLE_RESULTS_{agent_name} 表包含了代理包含在语义视图中的算法结果列表。DATA_LAYOUT_{agent_name} 表包含了输入图表的数据布局配置。您可以根据需要查看、删除或修改这些表中的条目。进行更改后，调用带有 NULL 参数的 _UPDATE_GRAPH_ANALYTICS_SEMANTIC_VIEW 过程以刷新语义视图。

修改可用结果的示例
-- 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
);

代理隔离

每个代理实例独立运行。在 Cortex Analyst 工具方面，线程并不隔离，这意味着同一代理的所有线程共享相同的语义视图。这种隔离确保了不同的代理不会干扰彼此的数据或结果。若要实现隔离，请使用新的 agent_name 创建一个新的代理实例，或重新创建现有实例。

故障排除

如果您收到以下错误：

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

请要求账户管理员设置参数 CORTEX_ENABLED_CROSS_REGION。

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