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:

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:

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.