neo4j-aura-agent-skill

When to Use

Creating or configuring an Aura Agent on an existing AuraDB instance
Adding/updating tools (CypherTemplate, SimilaritySearch, Text2Cypher) to an agent
Deploying an agent for external access (REST API endpoint or MCP server)
Invoking an agent with natural language queries via REST API
Listing, reading, or deleting existing agents in a project

When NOT to Use

Creating/managing AuraDB instances →
```
neo4j-aura-provisioning-skill
```
Creating vector indexes →
```
neo4j-vector-index-skill
```
Running Cypher directly →
```
neo4j-cypher-skill
```
Building Aura Graph Analytics sessions →
```
neo4j-aura-graph-analytics-skill
```

What are Aura Agents

GraphRAG agents on top of AuraDB — answer natural language questions via three tool types:

CypherTemplate — parameterized queries for predictable lookups
SimilaritySearch — vector similarity search over a VECTOR index
Text2Cypher — natural language → Cypher for aggregations and discovery

Expose your graph via natural language to users or apps without application code. Accessible as REST or MCP endpoint; single- and multi-turn. For full Cypher control, low-latency lookups, or direct writes — use

neo4j-cypher-skill

instead.

Prerequisites

Running AuraDB instance with knowledge graph loaded
"Generative AI assistance" enabled in Organization settings
"Aura Agent" toggled on in the project
"Tool authentication" enabled at project/Security level
Project admin access
```
AURA_CLIENT_ID
```
and
```
AURA_CLIENT_SECRET
```
from console.neo4j.io → Account Settings → API Credentials
```
AURA_ORG_ID
```
,
```
AURA_PROJECT_ID
```
— see Step 2;
```
AURA_INSTANCE_ID
```
— resolved interactively in Step 2 if not already set

Python env:

uv sync

in skill directory (or

pip install neo4j neo4j-graphrag requests python-dotenv

)

```
.env
```
and
```
schema.json
```
in
```
.gitignore
```

Step 1 — Verify Auth

Manual credential verification only — scripts call

get_token()

internally.

bash

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}..."

If blank token: verify

AURA_CLIENT_ID

AURA_CLIENT_SECRET

.env

. Stop and report. Token TTL: 3600 s. Re-run on 401/403.

Step 2 — Resolve Organization & Project IDs

From console URL (fastest): open console.neo4j.io → navigate to a project. URL pattern:

/organizations/{AURA_ORG_ID}/projects/{AURA_PROJECT_ID}

Programmatic fallback:

bash

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

Set in

.env

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

Check
AURA_INSTANCE_ID
— if it is already set in

.env

, skip the rest of this step.

If not set, list available instances and ask the user to choose:

bash

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

Show output to user. Ask: "Which instance should the agent connect to?" Then write to

.env

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

If the list is empty: no AuraDB instances exist in this project — an Aura Agent cannot be created without one. Stop and report. If

: re-run Step 1. If

: verify

AURA_PROJECT_ID

. Stop and report.

Step 3 — List Existing Agents

bash

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

Output: agent IDs, names, enabled status, endpoint URLs.

: re-run Step 1. If

: verify

AURA_ORG_ID

AURA_PROJECT_ID

. Stop and report.

Step 4 — Fetch Graph Schema

Requires

NEO4J_URI

NEO4J_USERNAME

NEO4J_PASSWORD

.env

bash

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

Saves

schema.json

. Output: node/rel-type counts, node labels + typed properties (with Aura

data_type

), relationship patterns, VECTOR indexes.

Data gate — script exits with error and does NOT write

schema.json

if:

fewer than 2 nodes, OR
zero relationship types

If gate fails: load data into the database before proceeding. Stop and report. If

ServiceUnavailable

: check

NEO4J_URI

uses

neo4j+s://

; instance must be

running

. Stop and report. If

neo4j-graphrag not found

uv add neo4j-graphrag

. Stop and report.

Read

schema.json

before Step 5.

Step 5 — Discover Use Cases

Before designing tools, read references/authoring-guide.md.

Ask the user these questions. Do NOT guess tool types or parameters.

"What questions should this agent answer?"
"Which nodes or relationships matter most?" — match against
```
schema.json → node_props
```
"Do users search by a specific property value?" → CypherTemplate
"Any counting, grouping, or date-range questions?" → Text2Cypher
"Search for semantically similar text?" → check
```
schema.json → metadata → vector_index
```
- No VECTOR index found: inform user; skip SimilaritySearch; delegate to
```
neo4j-vector-index-skill
```
  first
- VECTOR index found: ask the user — "Which embedding provider and model should be used? What output dimension?" See supported models in
```
references/REFERENCE.md → Embedding Provider Options
```
  . Do NOT guess or default.

Tool selection:

Use Case	Tool
Lookup by specific property value	`cypherTemplate`
Semantic text search	`similaritySearch`
Aggregation, counting, open-ended	`text2cypher`

CypherTemplate parameters: for each parameter, read

aura_data_type

from

schema.json → node_props

rel_props

and use it as

data_type

. If the property has

low_cardinality: true

, the parameter

description

MUST list the valid values — copy them from the

values

array in

schema.json

. Example:

"description": "Agreement type to filter by. Valid values: \"Distributor Agreement\", \"License Agreement\", \"NDA\""

. Properties with

has_fulltext_index: true

are especially likely to be filter targets and must include valid values when low cardinality.

SimilaritySearch configuration — ask the user for all three before drafting the tool config:

Field	What to ask	Source
`provider`	"openai" or "vertexai"?	User confirms
`model`	Which model?	User picks from `references/REFERENCE.md → Embedding Provider Options`
`dimension`	What output dimension?	Required if model is configurable (see table); fixed models use the table value

index

: use

name

from

schema.json → metadata → vector_index

where

state = ONLINE

dimension

must match

vector.dimensions

in the same index entry.

Signals inventory: for each label or relationship that appears in a tool or the user's stated questions, write a signal block in the system prompt. See

references/authoring-guide.md → Signals inventory

for the template and rules.

Draft config JSON → show to user for review → confirm → proceed to Step 6.

Step 6 — Create Agent

Minimum required config:

json

{
  "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"
    }
  ]
}

Show config to user and confirm before running:

bash

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

Response includes

id

(save as

AURA_AGENT_ID

endpoint_link

mcp_endpoint_link

Step 7 — Invoke Agent (Test)

bash

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

--raw

prints full JSON including reasoning chain and token usage.

Direct curl (uses token from Step 1):

bash

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?"}'

Step 8 — Update Agent (Partial PATCH)

Create patch JSON with only the fields to change:

json

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

Show to user and confirm before running:

bash

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

Step 9 — Delete Agent

IRREVERSIBLE. Configuration permanently removed.

Show to user and wait for explicit confirmation before running:

bash

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

Returns 202 Accepted.

Tool Configuration

CypherTemplate

Pre-defined parameterized queries for repeated, predictable lookups.

json

{
  "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\", ...>"
      }
    ]
  }
}

Low-cardinality rule: if

schema.json → node_props[Label][prop].low_cardinality

true

, the

description

field must end with the exact values from

schema.json → node_props[Label][prop].values

. This applies to relationship properties in

rel_props

too.

SimilaritySearch

Requires a VECTOR index (

state = ONLINE

). Get index name from

schema.json → metadata → vector_index

json

{
  "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

combinations: see references/REFERENCE.md.

Text2Cypher

Natural language → Cypher. Use as fallback for aggregation and discovery.

json

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

Common Errors

Error	Cause	Fix
`401 Unauthorized`	Token expired	Re-run Step 1
`403 Forbidden` on create	Not a project admin	Request admin access
`400 Bad Request`	Invalid tool config or missing required field	Check `type` spelling: `cypherTemplate` , `similaritySearch` , `text2cypher`
`404 Not Found`	Wrong org/project/agent ID	Re-run `list` to verify IDs
`400` on create with SimilaritySearch	Vector index missing	Create index first — use `neo4j-vector-index-skill`
Agent returns no results	`top_k` too low or index empty	Increase `top_k` ; verify index is populated

Scripts

All scripts load credentials from

.env

automatically. Run with

uv run python3 <script>

Script	Purpose
`scripts/fetch_schema.py`	Fetch graph schema from AuraDB; save to `schema.json`
`scripts/manage_agent.py`	CRUD: list, create, get, update, delete agents
`scripts/invoke_agent.py`	Send a natural language query to an agent

fetch_schema.py parameters:

Parameter	Type	Required	Default
`NEO4J_URI`	env	Yes	—
`NEO4J_USERNAME`	env	No	`neo4j`
`NEO4J_PASSWORD`	env	Yes	—
`NEO4J_DATABASE`	env	No	`neo4j`

manage_agent.py parameters:

Parameter	Type	Required	Env fallback
`AURA_CLIENT_ID`	env	Yes	—
`AURA_CLIENT_SECRET`	env	Yes	—
`--org-id`	arg	No	`AURA_ORG_ID`
`--project-id`	arg	No	`AURA_PROJECT_ID`
`--agent-id`	arg	get/update/delete	`AURA_AGENT_ID`
`--config`	arg	create/update	—

invoke_agent.py parameters:

Parameter	Type	Required	Env fallback
`AURA_CLIENT_ID`	env	Yes	—
`AURA_CLIENT_SECRET`	env	Yes	—
`--org-id`	arg	No	`AURA_ORG_ID`
`--project-id`	arg	No	`AURA_PROJECT_ID`
`--agent-id`	arg	Yes	`AURA_AGENT_ID`
`query`	positional	Yes	—
`--raw`	flag	No	—

Checklist

AuraDB instance
```
running
```
, knowledge graph loaded
"Generative AI assistance" + "Aura Agent" enabled in org/project settings

.env

populated:

AURA_CLIENT_ID

AURA_CLIENT_SECRET

AURA_ORG_ID

AURA_PROJECT_ID

AURA_INSTANCE_ID

NEO4J_URI

NEO4J_PASSWORD

```
.env
```
and
```
schema.json
```
in
```
.gitignore
```
Auth verified (Step 1)
Org/Project IDs confirmed (Step 2)
API connectivity confirmed via
```
list
```
(Step 3)
```
schema.json
```
fetched and reviewed (Step 4) — data gate passed (≥2 nodes, ≥1 rel type)
Use cases confirmed with user (Step 5)
CypherTemplate
```
data_type
```
taken from
```
schema.json aura_data_type
```
SimilaritySearch
```
index
```
from
```
schema.json metadata.vector_index
```
(state=ONLINE)
Agent config shown to user and confirmed (Step 6)
Required fields present:
```
name
```
,
```
description
```
,
```
dbid
```
,
```
is_private
```
,
```
tools
```
(min 1)
```
AURA_AGENT_ID
```
saved from create response
Agent invoked and response verified (Step 7)
Update/Delete confirmed by user before execution

neo4j-aura-agent-skill

NPX Install

Tags

SKILL.md Content

When to Use

When NOT to Use

What are Aura Agents

Prerequisites

Step 1 — Verify Auth

Step 2 — Resolve Organization & Project IDs

Step 3 — List Existing Agents

Step 4 — Fetch Graph Schema

Step 5 — Discover Use Cases

Step 6 — Create Agent

Step 7 — Invoke Agent (Test)

Step 8 — Update Agent (Partial PATCH)

Step 9 — Delete Agent

Tool Configuration

CypherTemplate

SimilaritySearch

Text2Cypher

Common Errors

Scripts

Checklist