Skip to content

Commit 9810e43

Browse files
jexpjexp
committed
Added Aura Agents Page
1 parent 7fbb526 commit 9810e43

File tree

2 files changed

+162
-0
lines changed

2 files changed

+162
-0
lines changed

‎modules/genai-ecosystem/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
**** https://neo4j.com/labs/genai-ecosystem/google-cloud-demo[GraphRAG with Google Vertex AI^]
1111

1212
*** Neo4j GenAI Product Integrations
13+
**** xref:aura-agent.adoc[Aura GraphRAG Agents]
1314
**** xref:graphrag-python.adoc[GraphRAG Python Package]
1415
**** https://python.langchain.com/docs/integrations/providers/neo4j[LangChain Neo4j (Vendor Supported Package)^]
1516
**** xref:vector-search.adoc[Vector Index and Search]

‎modules/genai-ecosystem/pages/aura-agent.adoc‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
= Aura GraphRAG Agents
2+
include::_graphacademy_llm.adoc[]
3+
:slug: aura-agent
4+
:author:
5+
:category: genai-ecosystem
6+
:tags: graphrag, agent, vector search, text2cypher
7+
:neo4j-versions: aura
8+
:page-pagination:
9+
:page-product: aura
10+
11+
Aura Agent, in early access from Oct 2025, is an agent-creation platform that enables users to rapidly build, test, and deploy AI agents grounded by their own enterprise data in AuraDB.
12+
It provides end-to-end automated orchestration and AIOps for graph-based knowledge retrieval.
13+
The platform abstracts away the complexity of integrating diverse LLM and agentic frameworks, GraphRAG retrieval patterns, text-to-query generation (via specialized Text2Cypher models), and secure agent-serving infrastructure.
14+
15+
image::https://dist.neo4j.com/wp-content/uploads/20250929164049/aura-agent-tools-e1759250930497.png[]
16+
17+
Among the key capabilities of Aura Agent:
18+
19+
* Agent creation in the Aura console with a no-/low-code agent builder
20+
* Agent retrieval tools for pre-defined graph query templates, vector similarity search, and text to query
21+
* Agent testing via a playground chat UI
22+
* Secure agent deployment for consumption by downstream apps via an authenticated endpoint, with MCP support coming soon
23+
24+
== Prerequisites
25+
26+
You can use Aura Agent with the following Aura offerings
27+
28+
* AuraDB Free
29+
* AuraDB Pro (incl. Pro Trial)
30+
* AuraDB Business Critical
31+
32+
The database must not be paused to use it in an agent.
33+
34+
You need to have *"GenAI Asisstance" enabled* in your Aura Organization, then Aura Agents should be visible in the sidebar.
35+
36+
== Getting Started
37+
38+
Navigate to the Agents entry in the sidebar, select "Create Agent" and provide
39+
40+
* Title
41+
* Description
42+
* Instructions
43+
44+
And most critically your Aura database to run on (requirements see above).
45+
46+
You can test your agent continually in the chat on the right hand side.
47+
48+
Then start adding *specific tools* to your agent to give it the capabilities to retrieve certain subsets of data or convert user questions into Cypher queries.
49+
Currently the agent only supports _read only_ queries against the database.
50+
51+
Don't forget to save your agent, when you're satisfied with the current state.
52+
53+
image::https://dist.neo4j.com/wp-content/uploads/20250930120034/test-agent-aura-console.png[]
54+
55+
You can choose to share your agent internally with other project members, or make it available *externally* through an API (currentl REST, soon MCP and A2A).
56+
57+
== Available Tools
58+
59+
=== Cypher Template Tool
60+
61+
The *Cypher Template Tool*, executes a parameterized, read-only Cypher statement against the database and returns the results directly to the agent.
62+
63+
You need to provide a _name_ and _description_ of the tool for the agent to use and _cypher_ query and an optional set of parameters.
64+
65+
Some notes:
66+
67+
* make sure to return only relevant information from the query
68+
* best return only select node and relationship attributes (text, numbers)
69+
* don't return embeddings or graph elements like node / relationship / paths
70+
* try to de-duplicate the results
71+
* limit the results to 10 to 50 rows so that the agent/LLM is not overwhelmed with too much irrelevant information
72+
* test the Cypher statements of your tools beforehand to ensure that they work correctly
73+
74+
image::https://dist.neo4j.com/wp-content/uploads/20250930112819/get-contract-details-tool.png[]
75+
76+
=== Text2Cypher Tool
77+
78+
The "Text2Cypher" allows the agent to retrieve data dynamically that is either not covered by other tools or more structural in nature (like aggregations).
79+
80+
The infrastructure will pass the _text from the tool invocation_, together with the retrieved database _schema_ and the _text2cypher system prompt_ to a fine-tuned model to generate a suitable Cypher statement to execute.
81+
82+
For this tool you only need to provide a _description_ and _instructions_.
83+
84+
The instructions should cover:
85+
86+
* When to use the Text2Cypher tool (and when not)
87+
* Specific aspects about your database, domain
88+
* Relevant entities and especially information about searchable categorical properties, e.g. shape of identifiers
89+
* Which attributes are suitable for aggregation
90+
91+
=== Vector Similarity Tool
92+
93+
The *Vector Similarity Tool* allows to find nodes in your graph by vector similarity.
94+
95+
Besides a description you provide
96+
97+
* Embedding Model Provider (Vertex AI, OpenAI)
98+
* Embedding Model
99+
* Vector Index Name
100+
* Top-K results
101+
102+
And the tool will then embed the input text from the agent, perform the vector search and return the top-k results to the agent for processing.
103+
104+
== API Usage
105+
106+
To integrate the Aura Agent into yours system, you can make it available externally, so it is callable via a REST API.
107+
108+
Besides the `ENDPOINT_URL` you also need `CLIENT_ID` and `CLIENT_SECRET` as https://neo4j.com/docs/aura/aura-cli/initial-configuration/[API keys from your User Profile^], to create short lived session tokens.
109+
110+
The example code below uses https://jqlang.org/[`jq`] for command line JSON processing.
111+
112+
[source,shell]
113+
----
114+
export CLIENT_ID="..."
115+
export CLIENT_SECRET="..."
116+
export ENDPOINT_URL="https://api.neo4j.io/v2beta1/projects/.../agents/.../invoke"
117+
118+
# assign bearer token to environment variable
119+
export BEARER_TOKEN=$(curl -s --request POST 'https://api.neo4j.io/oauth/token' \
120+
--user "$CLIENT_ID:$CLIENT_SECRET" \
121+
--header 'Content-Type: application/x-www-form-urlencoded' \
122+
--data-urlencode 'grant_type=client_credentials' | \
123+
jq -r .access_token)
124+
125+
#invoke endpoint
126+
curl --request POST \
127+
"$ENDPOINT_URL" \
128+
-H 'Content-Type: application/json' \
129+
-H 'Accept: application/json' \
130+
-H "Authorization: Bearer $BEARER_TOKEN" \
131+
-d '{"input": "<YOUR AGENT QUESTION>"}' \
132+
--max-time 60 | jq .
133+
----
134+
135+
////
136+
# get bearer token
137+
curl --request POST 'https://api.neo4j.io/oauth/token' \
138+
--user "$CLIENT_ID:$CLIENT_SECRET" \
139+
--header 'Content-Type: application/x-www-form-urlencoded' \
140+
--data-urlencode 'grant_type=client_credentials'
141+
142+
{"access_token":"eyJh....","expires_in":3600,"token_type":"Bearer"}
143+
////
144+
145+
The example repository contains example code for https://github.com/neo4j-product-examples/knowledge-graph-agent/tree/main/code/contract-review-mcp[wrapping the REST API into an MCP server].
146+
147+
== Resources
148+
149+
* https://neo4j-aura.canny.io/changelog/aura-agent-preview[Aura Agent Feedback^]
150+
* https://github.com/neo4j-product-examples/knowledge-graph-agent/blob/main/contract-review.md[Example Agents Repository^] - Contract Review, Know Your Customer (KYC)
151+
* https://neo4j.com/blog/genai/build-context-aware-graphrag-agent/[Neo4j Aura Agent: Create Your Own GraphRAG Agent in Minutes^]
152+
* https://docs.google.com/document/d/1c2w3JM7IoDMOjBY50twMtNgY2Q3VrNtM7dQQPGolxw0/edit?tab=t.0#heading=h.ygp8gdk80zp5[Aura Agent FAQ^]
153+
* https://graphacademy.neo4j.com/courses/workshop-genai/[GraphAcademy Workshop^]
154+
155+
// * https://www.youtube.com/watch?v=edYZ8AZXsKQ[Aura Agent Livestream^]
156+
157+
=== Aura Agent Livestream
158+
159+
++++
160+
<iframe width="560" height="315" src="https://www.youtube.com/embed/edYZ8AZXsKQ?si=Xmroq0kZfhpNbwii" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
161+
++++

0 commit comments

Comments
 (0)