neo4j-aura-agent-skill

What this skill does

## 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.

```bash
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**:
```bash
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:

```bash
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

```bash
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`.

```bash
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](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:
```json
{
  "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:**
```bash
uv run python3 scripts/manage_agent.py create --config agent-config.json
```

Response includes `id` (save as `AURA_AGENT_ID`), `endpoint_link`, `mcp_endpoint_link`.

---

## Step 7 — Invoke Agent (Test)

```bash