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
• Generating an evaluation dataset (JSON) to test an agent in the Aura console's Evaluation feature

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.

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 in .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:

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:

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 401: re-run Step 1. If 404: verify AURA_PROJECT_ID. Stop and report.

---

Step 3 — List Existing Agents

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.

If 401: re-run Step 1. If 404: verify AURA_ORG_ID/AURA_PROJECT_ID. Stop and report.

---

Step 4 — Fetch Graph Schema

Requires NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD in .env.

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.

Take answers from request and schema; ask about gaps. Do NOT guess tool types or parameters.

1. "What questions should this agent answer?"
2. "Which nodes or relationships matter most?" — match against schema.json → node_props
3. "Do users search by a specific property value?" → CypherTemplate
4. "Any counting, grouping, or date-range questions?" → Text2Cypher
5. "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: provider/model from request, else ask ("Which embedding provider and model?"); supported models → references/REFERENCE.md → Embedding Provider Options. Dimension from index (vector.dimensions). Do NOT guess provider/model.

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 or rel_props and use it as data_type. If the property has low_cardinality: true, the parameter description should 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 should include valid values when low cardinality.

SimilaritySearch configuration — values from request; dimension from index; ask about gaps; then draft tool config:

Field	What to ask	Source
provider	"openai" or "vertexai"?	Request, else user confirms
model	Which model?	Request, else 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. Skip review if user said go ahead or request gives full config; state config, proceed.

---

Step 6 — Create Agent

Minimum required config:

{
  "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 (skip if user already asked to create with these details):

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

Response includes id (save as AURA_AGENT_ID), endpoint_link. No MCP URL in response; if is_mcp_enabled: https://mcp.neo4j.io/agent?project_id=<project_id>&agent_id=<agent_id> — see references/REFERENCE.md → External Access.

---

Step 7 — Invoke Agent (Test)

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):

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:

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

Show to user and confirm before running:

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:

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

Returns 202 Accepted.

---

Step 10 — Generate Evaluation Dataset

Creates an importable evaluation dataset (max 50 questions) for Aura's Agent Evaluation feature. Read references/evaluation-dataset-guide.md first — it defines format, tool_type mapping, question budget and category rules.

1. Export the real agent definition (never draft from a description alone — LLMs invent plausible tool calls):

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

   Ensure schema.json exists (Step 4).
2. List tools (name, type, parameters, descriptions) and propose the per-category plan (≤ 50 total). Categories:
   1. Core Factual (counts, aggregates, filters, comparisons, AND/NOT)
   2. Per-tool probing — per non-Text2Cypher tool: one it should nail, one edge case on a hypothesised limit, one exploiting a structural gap confirmed in its config
   3. Semantic search — exact-match + paraphrased/conceptual (only if a similaritySearch tool exists)
   4. Multi-tool composition — each chains 2–4 tools
   5. Text2Cypher stress — 5.1 2–3 hop/aggregation, 5.2 WITH/OPTIONAL compound, 5.3 shortest path/variable-length, 5.4 zero-record (hallucination) questions, 5.5 schema questions
3. Derive every expected answer by running Cypher against the database (driver with .env creds). No guessed answers. Keep Cypher + gap rationale in eval_dataset.provenance.json.
4. Write eval_dataset.json and validate:

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

5. Show the user category counts and samples. Warn: questions are read-only after saving in the console and datasets have no version history, so confirm before they import (Agent → Evaluation).

---

Tool Configuration

CypherTemplate

Pre-defined parameterized queries for repeated, predictable lookups.

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

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

{
  "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
scripts/validate_eval_dataset.py	Validate an evaluation dataset JSON (optionally against agent.json)

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
• Eval dataset: ≤ 50 questions, expected answers from DB queries, tool calls validated against agent.json (Step 10)