Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

neo4j-aura-agent-skill

Manages Neo4j Aura Agents via the v2beta1 REST API — create, list, get, update, delete,

neo4j-contrib · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add neo4j-contrib/neo4j-skills --skill neo4j-aura-agent-skill

About this skill


name: neo4j-aura-agent-skill description: Manages Neo4j Aura Agents via the v2beta1 REST API — create, list, get, update, delete, and invoke Aura agents backed by an AuraDB instance. Use when configuring Aura Agent tools (CypherTemplate, SimilaritySearch, Text2Cypher), setting system prompts, deploying agents to REST or MCP endpoints, or invoking agents with natural language queries. Covers OAuth2 auth, organization/project scoping, tool parameter schemas, and InvokeAgentResponse format. Does NOT cover AuraDB instance provisioning — use neo4j-aura-provisioning-skill. Does NOT cover vector index creation — use neo4j-vector-index-skill. version: 1.0.3 allowed-tools: Bash WebFetch

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.

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.

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 simila
Read the complete source ↗