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 in

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. 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 : Set in .env : 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: Show output to user. Ask: "Which instance should the agent connect to?" Then write to .env : 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 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 . 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: 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 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: Show config to user and confirm before running: Response includes id (save as AURA AGENT ID ), endpoint link , mcp endpoint link . Step 7 — Invoke Agent (Test) raw prints full JSON including reasoning chain and token usage. Direct curl (uses token from Step 1): Step 8 — Update Agent (Partial PATCH) Create patch JSON with only the fields to change: Show to user and confirm before running: Step 9 — Delete Agent IRREVERSIBLE. Configuration permanently removed. Show to user and wait for explicit confirmation before running: Returns 202 Accepted. Tool Configuration CypherTemplate Pre defined parameterized queries for repeated, predictable lookups. 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 . provider / model combinations: see [references/REFERENCE.md](references/REFERENCE.md). Text2Cypher Natural language → Cypher. Use as fallback for aggregation and discovery. 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