neo4j-aura-agent-skill
Manages Neo4j Aura Agents via the v2beta1 REST API — create, list, get, update, delete,
neo4j-contrib · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add neo4j-contrib/neo4j-skills --skill neo4j-aura-agent-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_IDandAURA_CLIENT_SECRETfrom console.neo4j.io → Account Settings → API CredentialsAURA_ORG_ID,AURA_PROJECT_ID— see Step 2;AURA_INSTANCE_ID— resolved interactively in Step 2 if not already set- Python env:
uv syncin skill directory (orpip install neo4j neo4j-graphrag requests python-dotenv) .envandschema.jsonin.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.
- "What questions should this agent answer?"
- "Which nodes or relationships matter most?" — match against
schema.json → node_props - "Do users search by a specific property value?" → CypherTemplate
- "Any counting, grouping, or date-range questions?" → Text2Cypher
- "Search for semantically simila