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
• AURACLIENTID and AURACLIENTSECRET from console.neo4j.io → Account Settings → API Credentials
• AURAORGID, AURAPROJECTID — see Step 2; AURAINSTANCEID — 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 AURACLIENTID/AURACLIENTSECRET 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/{AURAORGID}/projects/{AURAPROJECTID}

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 AURAINSTANCEID — 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 AURAPROJECTID. 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 AURAORGID/AURAPROJECTID. Stop and report.

Step 4 — Fetch Graph Schema

Requires NEO4JURI, NEO4JUSERNAME, 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](references/authoring-guide.md).

Ask the user these questions. 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: 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:

CypherTemplate parameters: for each parameter, read auradatatype from schema.json → nodeprops or relprops and use it as datatype. If the property has lowcardinality: 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 hasfulltextindex: 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:

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:

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

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

Response includes id (save as AURAAGENTID), endpointlink, mcpendpoint_link.

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.

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 → nodeprops[Label][prop].lowcardinality is true, the description field must end with the exact values from schema.json → nodeprops[Label][prop].values. This applies to relationship properties in relprops 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](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

Scripts

All scripts load credentials from .env automatically. Run with uv run python3 <script>.

fetch_schema.py parameters:

manage_agent.py parameters:

invoke_agent.py parameters:

Checklist

• AuraDB instance running, knowledge graph loaded
• "Generative AI assistance" + "Aura Agent" enabled in org/project settings
• .env populated: AURACLIENTID, AURACLIENTSECRET, AURAORGID, AURAPROJECTID, AURAINSTANCEID, NEO4JURI, NEO4JPASSWORD
• .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 datatype taken from schema.json auradata_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)
• AURAAGENTID saved from create response
• Agent invoked and response verified (Step 7)
• Update/Delete confirmed by user before execution