neo4j-aura-agent-skill

使用场景

• 在现有 AuraDB 实例上创建或配置 Aura Agent
• 为 Agent 添加／更新工具（CypherTemplate、SimilaritySearch、Text2Cypher）
• 部署 Agent 以供外部访问（REST API 端点或 MCP 服务）
• 通过 REST API 使用自然语言查询调用 Agent
• 列出、读取或删除项目中的现有 Agent
• 生成评估数据集（JSON），以便在 Aura 控制台的 Evaluation 功能中测试 Agent

不适用场景

• 创建／管理 AuraDB 实例 → neo4j-aura-provisioning-skill
• 创建向量索引 → neo4j-vector-index-skill
• 直接运行 Cypher → neo4j-cypher-skill
• 构建 Aura Graph Analytics 会话 → neo4j-aura-graph-analytics-skill

---

什么是 Aura Agents

基于 AuraDB 构建的 GraphRAG Agent——通过三种工具类型回答自然语言问题：

• CypherTemplate — 用于可预测查询的参数化查询
• SimilaritySearch — 在 VECTOR 索引上进行向量相似度搜索
• Text2Cypher — 将自然语言转换为 Cypher，用于聚合和发现

无需编写应用代码，即可通过自然语言向用户或应用开放图数据。可通过 REST 或 MCP 端点访问；支持单轮和多轮对话。如需完全控制 Cypher、低延迟查询或直接写入，请改用 neo4j-cypher-skill。

---

前提条件

• 已运行并加载知识图谱的 AuraDB 实例
• 已在 Organization 设置中启用 "Generative AI assistance"
• 已在项目中启用 "Aura Agent"
• 已在项目／Security 级别启用 "Tool authentication"
• 项目管理员权限
• 从 console.neo4j.io → Account Settings → API Credentials 获取 AURA_CLIENT_ID 和 AURA_CLIENT_SECRET
• AURA_ORG_ID、AURA_PROJECT_ID — 参见第 2 步；如果尚未设置，AURA_INSTANCE_ID 会在第 2 步中交互式解析
• Python 环境：在技能目录中运行 uv sync（或运行 pip install neo4j neo4j-graphrag requests python-dotenv）
• 将 .env 和 schema.json 添加到 .gitignore

---

第 1 步 — 验证身份验证

仅手动验证凭证——脚本会在内部调用 get_token()。

TOKEN=$(curl -s --request POST 'https://api.neo4j.io/oauth/token' \
  --user "${AURA_CLIENT_ID}:${AURA_CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  | jq -r '.access_token')
echo "Token: ${TOKEN:0:20}..."

如果令牌为空：检查 .env 中的 AURA_CLIENT_ID／AURA_CLIENT_SECRET。停止并报告。 令牌有效期：3600 s。遇到 401／403 时重新运行。

---

第 2 步 — 解析 Organization 和 Project ID

从控制台 URL 获取（最快）：打开 console.neo4j.io → 导航到某个项目。URL 格式： /organizations/{AURA_ORG_ID}/projects/{AURA_PROJECT_ID}

编程方式备用方案：

curl -s https://api.neo4j.io/v1/tenants \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {id, name}'
# tenant id maps to AURA_PROJECT_ID

在 .env 中设置：

AURA_ORG_ID=<organization-id>
AURA_PROJECT_ID=<project-id>

检查 AURA_INSTANCE_ID — 如果已在 .env 中设置，请跳过此步骤的其余部分。

如果尚未设置，请列出可用实例并让用户选择：

curl -s "https://api.neo4j.io/v1/instances?tenantId=${AURA_PROJECT_ID}" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, name, status, region, type}'

向用户显示输出。询问：“Agent 应连接到哪个实例？” 然后写入 .env：

AURA_INSTANCE_ID=<chosen-instance-id>
NEO4J_URI=neo4j+s://<chosen-instance-id>.databases.neo4j.io

如果列表为空：此项目中不存在 AuraDB 实例——没有实例就无法创建 Aura Agent。停止并报告。 如果返回 401：重新运行第 1 步。如果返回 404：验证 AURA_PROJECT_ID。停止并报告。

---

第 3 步 — 列出已有 Agent

uv run python3 scripts/manage_agent.py list   # Linux/macOS
uv run python scripts\manage_agent.py list    # Windows

输出：Agent ID、名称、启用状态、端点 URL。

如果返回 401：重新运行第 1 步。如果返回 404：验证 AURA_ORG_ID／AURA_PROJECT_ID。停止并报告。

---

第 4 步 — 获取图架构

.env 中必须包含 NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD。

uv run python3 scripts/fetch_schema.py   # Linux/macOS
uv run python scripts\fetch_schema.py    # Windows

保存为 schema.json。输出：节点／关系类型数量、节点标签及带类型的属性（包含 Aura data_type）、关系模式、VECTOR 索引。

数据检查关卡 — 如果出现以下情况，脚本会报错退出，且不会写入 schema.json：

• 节点少于 2 个，或
• 关系类型为 0 个

如果未通过检查：请先向数据库加载数据，再继续。停止并报告。 如果出现 ServiceUnavailable：检查 NEO4J_URI 是否使用 neo4j+s://；实例必须处于 running 状态。停止并报告。 如果出现 neo4j-graphrag not found：运行 uv add neo4j-graphrag。停止并报告。

在第 5 步之前阅读 schema.json。

---

步骤 5 — 发现用例

设计工具之前，请阅读 references/authoring-guide.md。

根据请求和架构获取答案；针对缺失信息提问。切勿猜测工具类型或参数。

1. “此 Agent 应回答哪些问题？”
2. “哪些节点或关系最重要？”——对照 schema.json → node_props
3. “用户会按特定属性值搜索吗？” → CypherTemplate
4. “有没有计数、分组或日期范围相关的问题？” → Text2Cypher
5. “要搜索语义相似的文本吗？” → 检查 schema.json → metadata → vector_index
   • 未找到 VECTOR 索引：告知用户；跳过 SimilaritySearch；先委托给 neo4j-vector-index-skill
   • 找到 VECTOR 索引：使用请求中指定的提供商/模型，否则提问（“使用哪个嵌入提供商和模型？”）；支持的模型 → references/REFERENCE.md → Embedding Provider Options。维度取自索引（vector.dimensions）。切勿猜测提供商/模型。

工具选择：

用例	工具
按特定属性值查找	cypherTemplate
语义文本搜索	similaritySearch
聚合、计数、开放式问题	text2cypher

CypherTemplate 参数：对于每个参数，从 schema.json → node_props 或 rel_props 中读取 aura_data_type，并将其用作 data_type。如果属性的 low_cardinality: true，参数的 description 应列出有效值——从 schema.json 的 values 数组中复制。例如："description": "要筛选的协议类型。有效值：\"Distributor Agreement\"、\"License Agreement\"、\"NDA\""。具有 has_fulltext_index: true 的属性尤其可能作为筛选目标；如果其基数较低，则应包含有效值。

SimilaritySearch 配置——值取自请求；dimension 取自索引；针对缺失信息提问；然后起草工具配置：

字段	要询问的内容	来源
provider	“使用 "openai" 还是 "vertexai"？”	请求；否则由用户确认
model	使用哪个模型？	请求；否则由用户从 references/REFERENCE.md → Embedding Provider Options 中选择
dimension	输出维度是多少？	如果模型可配置则必填（参见表格）；固定维度的模型使用表中值

index：使用 schema.json → metadata → vector_index 中 state = ONLINE 的 name。dimension 必须与同一索引条目中的 vector.dimensions 匹配。

信号清单：对于工具或用户所述问题中出现的每个标签或关系，在系统提示词中编写一个信号块。模板和规则请参见 references/authoring-guide.md → Signals inventory。

起草配置 JSON → 展示给用户审核 → 确认 → 继续步骤 6。如果用户已表示可以继续，或请求已提供完整配置，则跳过审核；说明配置并继续。

---

步骤 6 — 创建 Agent

最低必需配置：

{
  "name": "My Agent",
  "description": "Answers questions about the graph",
  "dbid": "<AURA_INSTANCE_ID>",
  "is_private": false,
  "tools": [
    {
      "type": "text2cypher",
      "name": "Query Graph",
      "description": "Translates natural language questions into Cypher queries"
    }
  ]
}

运行前向用户展示配置并确认（如果用户已要求按这些详情创建，则跳过）：

uv run python3 scripts/manage_agent.py create --config agent-config.json

响应包含 id（保存为 AURA_AGENT_ID）和 endpoint_link。响应中不包含 MCP URL；如果 is_mcp_enabled：https://mcp.neo4j.io/agent?project_id=<project_id>&agent_id=<agent_id> — 参见 references/REFERENCE.md → External Access。

---

步骤 7 — 调用 Agent（测试）

uv run python3 scripts/invoke_agent.py --agent-id "$AURA_AGENT_ID" "What can you help me with?"

--raw 会打印完整 JSON，包括推理链和令牌用量。

直接使用 curl（使用步骤 1 中的令牌）：

curl -s -X POST \
  "https://api.neo4j.io/v2beta1/organizations/${AURA_ORG_ID}/projects/${AURA_PROJECT_ID}/agents/${AURA_AGENT_ID}/invoke" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"input": "What can you help me with?"}'

---

步骤 8 — 更新 Agent（部分 PATCH）

创建仅包含要更改字段的补丁 JSON：

{ "system_prompt": "Updated instructions.", "is_mcp_enabled": true }

运行前向用户展示并确认：

uv run python3 scripts/manage_agent.py update --agent-id "$AURA_AGENT_ID" --config patch.json

---

步骤 9 — 删除 Agent

不可逆操作。配置将被永久移除。

运行前向用户展示并等待明确确认：

uv run python3 scripts/manage_agent.py delete --agent-id "$AURA_AGENT_ID"

返回 202 Accepted。

---

第 10 步 — 生成评估数据集

为 Aura 的 Agent Evaluation 功能创建可导入的评估数据集（最多 50 个问题）。请先阅读 references/evaluation-dataset-guide.md——其中定义了格式、tool_type 映射、问题数量上限和类别规则。

1. 导出真实的 Agent 定义（切勿仅根据描述起草——大模型会编造看似合理的工具调用）：

   uv run python3 scripts/manage_agent.py get --agent-id "$AURA_AGENT_ID" > agent.json
   

   确保 schema.json 存在（第 4 步）。
2. 列出工具（名称、类型、参数、描述），并提出各类别的计划（总计 ≤ 50）。类别：
   1. 核心事实类（计数、聚合、筛选、比较、AND/NOT）
   2. 逐工具探测——每个非 Text2Cypher 工具：一个应能正确回答的问题、一个针对假设限制的边界案例、一个利用其配置中已确认结构性缺口的问题
   3. 语义搜索——精确匹配 + 改写/概念类问题（仅当存在 similaritySearch 工具时）
   4. 多工具组合——每个问题串联 2–4 个工具
   5. Text2Cypher 压力测试——5.1 2–3 跳/聚合，5.2 WITH/OPTIONAL 复合查询，5.3 最短路径/可变长度，5.4 零记录（幻觉）问题，5.5 架构问题
3. 通过对数据库运行 Cypher 来推导每个预期答案（使用 .env 凭据的驱动程序）。不得猜测答案。将 Cypher 和缺口理由保存在 eval_dataset.provenance.json 中。
4. 编写 eval_dataset.json 并验证：

   uv run python3 scripts/validate_eval_dataset.py eval_dataset.json --agent agent.json
   

5. 向用户展示各类别的问题数量和示例。警告：数据集导入控制台后，问题将只能读取，无法修改，且数据集没有版本历史记录，因此请在导入前（Agent → Evaluation）进行确认。

---

工具配置

CypherTemplate

用于重复、可预测查询的预定义参数化查询。

{
  "type": "cypherTemplate",
  "name": "<descriptive name>",
  "description": "<what it looks up and when to use it>",
  "enabled": true,
  "config": {
    "template": "MATCH (n:Label {prop: $param}) RETURN n",
    "parameters": [
      {
        "name": "param",
        "data_type": "<string|integer|number|boolean — from schema.json aura_data_type>",
        "description": "<what the parameter represents. If low_cardinality=true in schema.json, append: Valid values: \"val1\", \"val2\", ...>"
      }
    ]
  }
}

低基数规则：如果 schema.json → node_props[Label][prop].low_cardinality 为 true，则 description 字段必须以 schema.json → node_props[Label][prop].values 中的确切值结尾。此规则也适用于 rel_props 中的关系属性。

SimilaritySearch

需要 VECTOR 索引（state = ONLINE）。从 schema.json → metadata → vector_index 获取索引名称。

{
  "type": "similaritySearch",
  "name": "<descriptive name>",
  "description": "<what text it searches and when to use it>",
  "enabled": true,
  "config": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "index": "<name from schema.json metadata.vector_index[state=ONLINE].name>",
    "top_k": 5,
    "dimension": "<vector.dimensions from schema.json metadata.vector_index options.indexConfig>",
    "post_processing_cypher": "<optional: Cypher to enrich similarity results with related nodes>"
  }
}

provider/model 组合请参阅 references/REFERENCE.md。

Text2Cypher

将自然语言转换为 Cypher。用作聚合和探索的备用方案。

{
  "type": "text2cypher",
  "name": "<descriptive name>",
  "description": "<what questions it handles — and explicitly what it should NOT handle>",
  "enabled": true
}

---

常见错误

错误	原因	修复方法
401 Unauthorized	令牌已过期	重新运行第 1 步
创建时出现 403 Forbidden	不是项目管理员	申请管理员权限
400 Bad Request	工具配置无效或缺少必填字段	检查 type 拼写：cypherTemplate、similaritySearch、text2cypher
404 Not Found	组织/项目/Agent ID 错误	重新运行 list 以验证 ID
使用 SimilaritySearch 创建时出现 400	缺少向量索引	先创建索引——使用 neo4j-vector-index-skill
Agent 未返回结果	top_k 太低或索引为空	提高 top_k；确认索引已填充

---

脚本

所有脚本都会自动从 .env 加载凭据。使用 uv run python3 <script> 运行。

脚本	用途
scripts/fetch_schema.py	从 AuraDB 获取图架构；保存到 schema.json
scripts/manage_agent.py	CRUD：列出、创建、获取、更新、删除 Agent
scripts/invoke_agent.py	向 Agent 发送自然语言查询
scripts/validate_eval_dataset.py	验证评估数据集 JSON（可选与 agent.json 对照）

fetch_schema.py 参数：

参数	类型	必填	默认值
NEO4J_URI	env	是	—
NEO4J_USERNAME	env	否	neo4j
NEO4J_PASSWORD	env	是	—
NEO4J_DATABASE	env	否	neo4j

manage_agent.py 参数：

参数	类型	必填	环境变量回退值
AURA_CLIENT_ID	env	是	—
AURA_CLIENT_SECRET	env	是	—
--org-id	arg	否	AURA_ORG_ID
--project-id	arg	否	AURA_PROJECT_ID
--agent-id	arg	get/update/delete	AURA_AGENT_ID
--config	arg	create/update	—

invoke_agent.py 参数：

参数	类型	必填	环境变量回退值
AURA_CLIENT_ID	env	是	—
AURA_CLIENT_SECRET	env	是	—
--org-id	arg	否	AURA_ORG_ID
--project-id	arg	否	AURA_PROJECT_ID
--agent-id	arg	是	AURA_AGENT_ID
query	positional	是	—
--raw	flag	否	—

---

检查清单

• AuraDB 实例处于 running 状态，知识图谱已加载
• 已在组织／项目设置中启用“Generative AI assistance”和“Aura Agent”
• 已填入 .env：AURA_CLIENT_ID、AURA_CLIENT_SECRET、AURA_ORG_ID、AURA_PROJECT_ID、AURA_INSTANCE_ID、NEO4J_URI、NEO4J_PASSWORD
• .env 和 schema.json 已添加到 .gitignore
• 已验证身份验证（步骤 1）
• 已确认组织／项目 ID（步骤 2）
• 已通过 list 确认 API 连通性（步骤 3）
• 已获取并检查 schema.json（步骤 4）——数据门槛已通过（≥2 个节点，≥1 种关系类型）
• 已与用户确认用例（步骤 5）
• CypherTemplate data_type 取自 schema.json aura_data_type
• SimilaritySearch index 取自 schema.json metadata.vector_index（state=ONLINE）
• 已向用户展示 Agent 配置并获得确认（步骤 6）
• 必需字段齐全：name、description、dbid、is_private、tools（至少 1 个）
• 已从创建响应中保存 AURA_AGENT_ID
• 已调用 Agent 并验证响应（步骤 7）
• 执行前已获得用户对更新／删除操作的确认
• 评估数据集：≤ 50 个问题，预期答案来自数据库查询，工具调用已根据 agent.json 验证（步骤 10）