Neo4j Aura Agent Skill

3.13


[project]
name = "neo4j-aura-agent-skill"
version = "0.1.0"
description = "Scripts for creating and managing Neo4j Aura Agents via the v2beta1 REST API"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "neo4j>=6.1.0",
    "neo4j-graphrag>=1.15.0",
    "python-dotenv>=1.2.2",
    "requests>=2.33.1",
]


# neo4j-aura-agent-skill

Create, configure, and invoke [Neo4j Aura Agents](https://neo4j.com/docs/aura/aura-agent/) — GraphRAG agents backed by an AuraDB knowledge graph.

## What this skill does

- Fetches the graph schema from AuraDB and annotates property types for tool design
- Guides tool selection (CypherTemplate, SimilaritySearch, Text2Cypher) based on use cases and schema
- Creates and manages Aura Agents via the v2beta1 REST API
- Sets system prompts and agent visibility (private/public, REST/MCP)
- Invokes agents with natural language queries and parses responses

## Requirements

- Running AuraDB instance with knowledge graph loaded
- "Generative AI assistance" + "Aura Agent" enabled in Aura org settings
- Project admin access
- `AURA_CLIENT_ID` and `AURA_CLIENT_SECRET` from console.neo4j.io → API Credentials
- Organization ID and Project ID from the Aura console URL

## Install dependencies

```bash
uv sync
```

## Quick start

```bash
# Fetch graph schema and detect vector indexes
uv run python3 scripts/fetch_schema.py

# List existing agents
uv run python3 scripts/manage_agent.py list

# Create an agent from a config file
uv run python3 scripts/manage_agent.py create --config agent-config.json

# Invoke the agent
uv run python3 scripts/invoke_agent.py --agent-id "$AURA_AGENT_ID" "What can you help me with?"
```

## Files

| File | Purpose |
|---|---|
| `SKILL.md` | Agent-readable operational playbook |
| `scripts/fetch_schema.py` | Fetch graph schema from AuraDB; save to `schema.json` |
| `scripts/manage_agent.py` | CRUD operations (list/create/get/update/delete) |
| `scripts/invoke_agent.py` | Send queries to a deployed agent |
| `references/REFERENCE.md` | Full API schema, embedding providers, response formats |


# Aura Agent Authoring Guide

Best practices for system prompts, tool names, tool descriptions, and parameter descriptions.
The agent's LLM reads all of these at inference time to decide which tool to call and how to answer.
Quality here determines routing accuracy and answer quality.

---

## System Prompt

### Purpose
Defines the agent's identity, scope, and behavior constraints. Supplements — does not replace — tool descriptions.

### Rules

**Role sentence** — one sentence: domain + expertise level.
```
✅ "You are a specialist assistant for commercial contract analysis using a knowledge graph."
❌ "You are a helpful AI assistant."
```

**Supported use cases** — bullet list of what it can answer. Keeps LLM from fabricating capabilities.
```
✅ "You can: look up agreements by party or type, find similar clause language, identify contracts expiring within a date range."
❌ (omitting this — LLM will guess its own scope)
```

**Explicit boundaries** — state what it cannot do; do not rely on tool absence alone.
```
✅ "You cannot modify data, generate contract drafts, or access documents outside the knowledge graph."
❌ (omitting this — LLM may attempt tasks outside its tools)
```

**Tool preference order** — tell it which tool to try first for specific lookups. Without this, LLM defaults to Text2Cypher for everything.
```
✅ "For lookups by a known ID or property value, prefer CypherTemplate tools over the Text2Cypher tool."
```

**Uncertainty handling** — tell it to say so when it cannot answer. Prevents hallucination.
```
✅ "If you cannot find an answer using the available tools, say so explicitly. Do not guess."
```

**Output format** — specify structure when the use case demands it.
```
✅ "Always include the source node ID or property in your answer so users can verify."
✅ "For comparisons across multiple items, use a table."
```

**Citation rule** — tell it to reference graph d