Neo4j Aura Agent:入门教程
使用 Neo4j Aura Agent 在几分钟内构建并部署知识图谱智能体。本教程将引导您从零开始创建一个员工知识图谱智能体,演示如何通过本体驱动的 AI 实现智能体自动构建,并通过 REST API 和模型上下文协议 (MCP) 进行安全部署。
视频演示
本入门教程重现了下方视频中展示的演示内容。您可以观看视频获取全流程的可视化指南,也可以按照本指南中的步骤进行操作。
| 该视频提供了构建和部署 Aura Agent 的完整可视化演示。请结合本文字教程中的详细说明和代码示例进行学习。 |
概述
在本教程中,您将:
-
设置一个包含员工知识图谱的 Neo4j AuraDB 数据库
-
利用自动化构建功能生成 AI 智能体
-
配置 GraphRAG 工具(Cypher 模板、Text2Cypher、相似度搜索)
-
使用复杂查询测试您的智能体
-
通过经过身份验证的 REST 和 MCP 端点部署到生产环境
-
[可选] 使用 MCP 与 Claude 集成
完成时间: 30-45 分钟
先决条件
在开始之前,请确保您已具备以下条件:
-
一个 Neo4j Aura 账户(可在 https://console.neo4j.io 获取免费层级)
-
对知识图谱和 Neo4j 有基本了解
-
一个现代网络浏览器
架构
Neo4j Aura Agent 平台提供:
Graph RAG 工具
-
Cypher 模板: 预配置的查询,带有可选参数,用于特定领域的检索
-
Text2Cypher: 动态查询生成,用于灵活的数据访问
-
相似度搜索: 基于向量的节点属性语义搜索
部署选项
-
REST API: 基于令牌 (Token) 的身份验证,用于编程访问
-
MCP 服务器: 与 AI 客户端(Claude、Cursor、ChatGPT 等)的 OAuth 安全集成
AI 智能体功能
-
思维链推理,并在推理选项卡和响应中提供完整的可解释性
-
针对复杂查询的多工具调用
第 1 部分:数据库设置
第 1 步:访问 Aura 控制台
-
导航至 Aura 控制台:https://console.neo4j.io/
-
使用您的 Aura 凭据登录
-
为您的 Aura 组织启用 生成式 AI 辅助 (Generative AI assistance)
-
点击您的组织设置
-
开启 启用 GenAI 辅助 (Enable GenAI assistance)
-
-
为您的数据库启用 安全性→工具身份验证 (Security→Tool authentication)
第 2 步:创建并还原数据库
创建 AuraDB 实例
如果您还没有实例
-
在 Aura 控制台中,点击 创建实例 (Create Instance)
-
选择您偏好的层级(本教程使用免费层级即可)
-
命名您的实例:
employee-graph -
等待实例状态显示为 RUNNING(运行中)
-
在提示时保存您的凭据
-
连接 URI
-
用户名(通常为
neo4j) -
密码
-
下载数据库备份
-
下载员工数据备份文件:employee-data.backup
-
将其保存到您可以轻松访问的位置
从备份还原
-
在 Aura 控制台中,找到您的
employee-graph实例 -
点击实例旁边的 三个点 (⋮) 菜单
-
选择 备份与还原 (Backup & Restore)
-
点击 从备份还原 (Restore from backup)
-
上传您下载的
employee-data.backup文件 -
等待还原过程完成
-
准备就绪后,您的实例将恢复为 RUNNING 状态
要了解这些数据是如何从原始简历 PDF 和 CSV 文件创建的,请参阅此存储库(模块 1 和 2)
第 3 步:了解员工知识图谱
已还原的数据库包含一个员工知识图谱,包含:
节点类型
-
Person (人员) - 员工及其元数据、简历文本和相应的文本嵌入
-
Skill (技能) - 能力(Python、Java、机器学习等)
-
Thing (事物) - 即项目 - 已完成和正在进行的项目
-
Domain (领域) - 业务领域(AI、Web、DevOps)
-
WorkType (工作类型) - 工作类型(代码、研究)
关系类型
-
(:Person)-[:KNOWS]→(:Skill)- 员工技能,包括熟练程度和经验年限 -
(:Person)-[:BUILT|LED|MANAGED|OPTIMIZED|PUBLISHED|SHIPPED|WON]→(:Thing)- 参与的事物,包括角色和持续时间 -
(:Thing)-[:IN]→(:Domain)- 按业务领域分类的项目 -
(:Thing)-[:OF]→(:WorkType)- 按工作类型分类的项目
验证您的数据
-
在 Aura 控制台中,点击实例旁边的 打开 (Open)(或 查询 (Query) 按钮)
-
这将打开 Neo4j 查询工具
-
运行此查询以验证数据是否加载正确
MATCH (n)
RETURN labels(n)[0] as NodeType, count(n) as Count
ORDER BY Count DESC
您应该看到涵盖所有五种节点类型(Person, Skill, Thing, Domain, WorkType)的数据。
要直观地探索图谱
MATCH p=()-[*]->()
RETURN p LIMIT 100
这展示了图谱的一个样本,其中路径连接了人员、技能、项目、领域和工作类型
第 2 部分:创建您的智能体
第 1 步:导航至智能体
-
在 Aura 控制台中,找到左侧导航栏中的 数据服务 (Data Services) 部分
-
点击 智能体 (Agents)
-
点击 AI 创建 (Create with AI)
第 2 步:AI 创建
填写表单
实例
-
选择您的
employee-graph数据库
提示词
Create an Employee Knowledge Assistant responsible for skills analysis, talent search, and team formation at Cyberdyne Systems.
Skills Analysis example questions:
- How many Python developers do I have?
- Can you summarize my technical talent and skills distribution and the types of things people are working on. Feel Free to include ?
Person Similarities: ex: Who is most similar to Lucas Martinez?
Collaboration & teams: ex: Which individuals have collaborated to deliver the most AI Things?
You do not need to ask user permission before using a specific tool. It is implied that you have permission. The user cannot offer expert guidance into what tools to use.
It is important to have Cypher templates to judge similarity through skills and accomplishments/projects in the graph rather than using similarity search. Also ensure aggregation and counting questions do not leverage similarity search but the other tool options instead.
Text2Cypher should be a very last fallback option - only for dead simple aggregation queries. To ensure we have enough coverage in cypher templates, let's also create cypher template aggregation queries for counting People on Skill, and relationship type for people-[]-thing and for people-[]-thing by Domain and Worktype.
向量嵌入
-
勾选“此实例包含向量嵌入 (This instance contains vector embeddings)”框
-
选择“OpenAI”作为嵌入提供商
-
选择“text-embedding-ada-002”作为嵌入模型
生成智能体
-
点击 创建 (Create)
-
等待几分钟,平台将:
-
抓取并分析您的图谱模式
-
生成智能体名称、描述和系统提示指令
-
创建量身定制的 GraphRAG 工具
-
第 3 步:检查生成的智能体
生成完成后,您将看到一个带有名称、描述和提示指令的智能体
还会有一组 智能体工具 (Agent tools),包含三种类型
1. Cypher 模板
用于常见操作的预配置查询。应该有多个此类模板。以下是一些示例(由于是 AI 生成,您的结果可能会略有不同)
统计拥有某项技能的人数
MATCH (p:Person)-[:KNOWS]->(s:Skill {name: $skillName})
RETURN count(p) AS numberOfPeople
查找拥有最多共享技能的人
MATCH (p1:Person {name: $personName})-[:KNOWS]->(s:Skill)<-[:KNOWS]-(p2:Person)
WHERE p1 <> p2
RETURN p2.name AS SimilarPerson, count(s) AS SharedSkills
ORDER BY SharedSkills DESC LIMIT 10
第 3 部分:测试您的智能体
第 1 步:简单查询
用一个简单直接的问题进行测试
How many Python developers do we have?
预期行为
-
智能体选择
Count People with SkillCypher 模板或等效工具 -
使用参数
skill_name: "Python"执行 -
返回:“28 名 Python 开发人员”
第 2 步:复杂查询
测试多工具查询执行
Can you summarize my technical talent and skills distribution and the types of things people are working on?
预期行为
-
智能体进行多次工具调用,涉及 Text2Cypher 和可能的某些查询模板
响应示例
Cyberdyne Systems has a diverse technical talent pool with a strong distribution across various skills and project types.
**Technical Talent and Skills Distribution:**
The most prevalent skills within the company are:
* **Python:** 28 individuals
* **SQL:** 16 individuals
* **AWS:** 15 individuals
* **Team Management:** 14 individuals
* **Machine Learning:** 11 individuals
* **Project Management:** 11 individuals
* **Docker:** 10 individuals
* **Kubernetes:** 9 individuals
* **Data Engineering:** 8 individuals
Other notable skills include Computer Vision (7), Deep Learning (6), Natural Language Processing (6), TensorFlow (6), Data Analysis (6), Java (6), JavaScript (6), Leadership (6), PyTorch (5), React (5), Statistics (4), Google Cloud Platform (4), and Go (4). There are also individuals with expertise in Business Intelligence (3), Product Strategy (3), R Programming Language (2), Product Management (2), Swift (2), Kotlin (2), Cloud Architecture (2), Node.js (2), Data Science (1), Scikit-learn (1), Scala (1), Azure (1), TypeScript (1), Django (1), and Flask (1).
**Types of Things People are Working On (Projects):**
**By Work Type:**
* **SYSTEM:** 28 individuals
* **PRODUCT:** 23 individuals
* **TEAM:** 21 individuals
* **CODE:** 13 individuals
* **PROCESS:** 13 individuals
* **PROJECT:** 12 individuals
* **RESEARCH:** 12 individuals
* **INFRASTRUCTURE:** 9 individuals
* **AWARD:** 7 individuals
**By Project Domain:**
* **AI:** 18 individuals
* **ANALYTICS:** 8 individuals
* **CLOUD:** 8 individuals
* **DATA\_ENGINEERING:** 8 individuals
* **WEB:** 8 individuals
* **DATABASE:** 5 individuals
* **MICROSERVICES:** 5 individuals
* **DEVOPS:** 4 individuals
* **PLATFORM:** 4 individuals
* **SECURITY:** 4 individuals
* **MOBILE:** 2 individuals
**By Project Engagement Type:**
* **BUILT:** 30 individuals
* **LED:** 28 individuals
* **SHIPPED:** 23 individuals
* **OPTIMIZED:** 13 individuals
* **PUBLISHED:** 12 individuals
* **MANAGED:** 10 individuals
* **WON:** 7 individuals
第 3 步:查看推理链
点击 推理 (Reasoning) 选项卡以查看:
-
完整的思维链过程
-
每次带参数的工具调用
-
查询执行详情
-
结果是如何合成的
推理链示例
可以展开每个工具调用以查看输入和输出
推理步骤也可以展开,以显示智能体的思考过程
第 4 步:[可选] 更新、测试和迭代智能体
您可以选择添加、删除和编辑工具。请务必点击右上角的“更新智能体 (Update agent)”按钮保存智能体,以保留您的工作。请参阅 GitHub Readme 获取更多您可以尝试的 Cypher 模板工具和 Text2Query 提示词,以及向智能体提问的其他问题建议。
第 4 部分:将智能体部署到 REST 和 MCP
第 1 步:启用外部访问
-
在 Aura 智能体配置中,点击 外部访问 (External Access)
-
开启 启用 MCP 服务器 (Enable MCP server)
点击“更新智能体 (Update Agent)”。
几分钟内,您将获得经过身份验证的 REST API 和 MCP 服务器的公共端点,以便以编程方式调用智能体。
第 2 步:测试 MCP 服务器
您可以使用 MCP Inspector 或任何支持 OAuth 的 AI 客户端测试 MCP 服务器。在此示例中,我们将使用 Claude [https://claude.ai/new^] 作为演示。
请注意,如果您不是 Claude 管理员,则需要权限才能添加连接器。
在 Aura 控制台中复制您的 MCP 服务器端点。
在 Claude 中,从 设置/连接器 (Settings/Connectors) 使用 添加自定义连接器 (Add custom connector)。为连接器命名(例如“Expert Agent”),在“远程 MCP 服务器 URL (Remote MCP server URL)”字段中添加复制的端点,然后点击 添加 (Add)。
使用 Aura 凭据登录。Claude 会打开一个弹出窗口,要求您登录 aura-mcp,点击 继续 (Continue),并 接受 (Accept) 进入登录页面。使用您登录 Aura 控制台时使用的相同凭据。
验证您的 MCP 服务器。在 Claude 中创建一个新聊天,并确认您的智能体已启用。尝试以下问题:
-
“我有多少名 Python 开发人员?”
-
“你能总结一下我的技术人才和技能分布,以及人们正在从事的项目类型吗?欢迎包含简单的图表。”
第 3 步:测试 REST API
要通过 REST API 访问,您必须先生成 Aura API 密钥。
-
进入您的账户设置页面,找到
API Keys -
点击
Generate API Key,为其命名,并记下您的新Client ID和Client Secret -
请妥善保管
Client ID和密钥。不要分享给他人。
从“智能体”选项卡复制您的 API 外部端点
有了这些,您现在可以测试 API。要从终端快速测试,请运行以下命令
export CLIENT_ID=<enter your Client ID here>
export CLIENT_SECRET=<enter your Client Secret here>
export ENDPOINT_URL=<enter your agent endpoint URL>
获取 Aura API 令牌
export BEARER_TOKEN=$(curl -s --request POST 'https://api.neo4j.io/oauth/token' \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' | jq -r .access_token)
通过智能体 API 端点向您的智能体提问
curl --request POST "$ENDPOINT_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $BEARER_TOKEN" \
-d '{"input": "how many Python developers do I have?"}' --max-time 60 \
| jq .
您的智能体回复应如下所示
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 1116 100 1066 100 50 274 12 0:00:04 0:00:03 0:00:01 286
{
"content": [
{
"thinking": "Okay, here's what I'm thinking. I need to figure out how many Python developers there are. My initial understanding is that this means counting all the people who list \"Python\" as a skill. Therefore, the core of this task seems straightforward. The `Count_People_with_Skill` tool appears to be exactly the right instrument for this. I'll need to use the `skillName` argument, and in this case, the value will clearly be 'Python'. Simple as that, I'm off to get my count.\n",
"type": "thinking"
},
{
"id": "pyd_ai_853912b80104475e916e85b92d6ee591",
"input": {
"skillName": "Python"
},
"name": "Count_People_with_Skill",
"type": "cypher_template_tool_use"
},
{
"output": {
"keys": [
"numberOfPeople"
],
"records": [
{
"numberOfPeople": 28
}
],
"summary": {}
},
"tool_use_id": "pyd_ai_853912b80104475e916e85b92d6ee591",
"type": "cypher_template_tool_result"
},
{
"text": "You have 28 Python developers.",
"type": "text"
}
],
"end_reason": "FINAL_ANSWER_PROVIDED",
"role": "assistant",
"status": "SUCCESS",
"type": "message",
"usage": {
"request_tokens": 919,
"response_tokens": 77,
"total_tokens": 996
}
}
结论
您已成功使用 Neo4j Aura Agent 构建并部署了一个知识图谱智能体!您现在可以:
-
✓ 在几分钟内从图谱本体中创建智能体
-
✓ 利用多种 GraphRAG 工具
-
✓ 通过安全的 REST 和 MCP 端点进行部署
-
✓ 与 Claude 和其他 AI 客户端集成
资源
-
有关 Neo4j Aura Agent 的更深入详情,请参阅文档
-
更多示例会持续添加到 GitHub 存储库 中
-
Neo4j Aura Agent 网页和开发者指南包含了概述以及更多视频和学习资源的链接