Neo4j Aura Agent Skill

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 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:

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:

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:

{
  "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:

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)

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

--raw prints full JSON including reasoning chain and token usage.

Direct curl (uses token from Step 1):

curl -s -X POST \
  "https://api.neo4j.io/v2beta1/organizations/${AURA_ORG_ID}/projects/${AURA_PROJECT_ID}/agents/${AURA_AGENT_ID}/invoke" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"input": "What can you help me with?"}'

---

Step 8 — Update Agent (Partial PATCH)

Create patch JSON with only the fields to change:

{ "system_prompt": "Updated instructions.", "is_mcp_enabled": true }

Show to user and confirm before running:

uv run python3 scripts/manage_agent.py update --agent-id "$AURA_AGENT_ID" --config patch.json

---

Step 9 — Delete Agent

IRREVERSIBLE. Configuration permanently removed.

Show to user and wait for explicit confirmation before running:

uv run python3 scripts/manage_agent.py delete --agent-id "$AURA_AGENT_ID"

Returns 202 Accepted.

---

Tool Configuration

CypherTemplate

Pre-defined parameterized queries for repeated, predictable lookups.

{
  "type": "cypherTemplate",
  "name": "<descriptive name>",
  "description": "<what it looks up and when to use it>",
  "enabled": true,
  "config": {
    "template": "MATCH (n:Label {prop: $param}) RETURN n",
    "parameters": [
      {
        "name": "param",
        "data_type": "<string|integer|number|boolean — from schema.json aura_data_type>",
        "description": "<what the parameter represents. If low_cardinality=true in schema.json, append: Valid values: \"val1\", \"val2\", ...>"
      }
    ]
  }
}

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.

{
  "type": "similaritySearch",
  "name": "<descriptive name>",
  "description": "<what text it searches and when to use it>",
  "enabled": true,
  "config": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "index": "<name from schema.json metadata.vector_index[state=ONLINE].name>",
    "top_k": 5,
    "dimension": "<vector.dimensions from schema.json metadata.vector_index options.indexConfig>",
    "post_processing_cypher": "<optional: Cypher to enrich similarity results with related nodes>"
  }
}

provider/model combinations: see references/REFERENCE.md.

Text2Cypher

Natural language → Cypher. Use as fallback for aggregation and discovery.

{
  "type": "text2cypher",
  "name": "<descriptive name>",
  "description": "<what questions it handles — and explicitly what it should NOT handle>",
  "enabled": true
}

---

Common Errors

---

Scripts

All scripts load credentials from .env automatically. Run with uv run python3 <script>.

fetch_schema.py parameters:

manage_agent.py parameters:

invoke_agent.py parameters:

---

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

Create, configure, and invoke Neo4j Aura Agents — 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

uv sync

Quick start

# 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

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 data, not LLM knowledge.

✅ "Base all answers on data retrieved from tools. Do not use your training knowledge about the domain."

Explain mode — when the user asks to explain an answer, the agent should go beyond restating results. Include this block in your system prompt:

✅ "If the user asks you to explain your answer:
    1. Describe how you determined the result — which tool you used, which nodes or relationships were traversed, and why.
    2. Suggest ways the user could ask a more precise or targeted question to get better results.
    3. If a CypherTemplate tool would answer this question more reliably than Text2Cypher, propose the template — include the Cypher query, parameter names, and data types.
    4. If a change to the data model (new property, index, or relationship type) would make this query faster or more accurate, describe it."

This pattern surfaces agent reasoning and turns every answer into an opportunity to improve the tools and data model over time.

Signals inventory — include a signals section in the prompt for each key label and relationship type relevant to the use cases. Without it, the agent sees node labels and properties but must infer their semantic meaning, valid values, and routing logic from the schema alone. A signals inventory makes that knowledge explicit.

Each signal entry should state:

• What the signal measures (semantic meaning)
• Where it lives in the graph (label, relationship pattern, property)
• Valid values (critical for filtering — especially low-cardinality properties)
• When to use it (which question types or ranking/filtering scenarios call for it)

Generate this section during Step 5 using the use case discussion and schema.json. For every label or relationship that appears in a tool or in the user's questions, write a signal block.

Template:

## <Domain> Signals

**<Signal Name>** — `(<StartLabel>)-[r:<REL_TYPE>]->(<EndLabel>)` (or `(<Label>)` for node properties)
- Property: `r.<propertyName>` (or `n.<propertyName>`)
- Values: `'value1'` | `'value2'` | `'value3'`
- When to use: <question types or ranking/filtering scenarios>

Example — recruiting domain:

## Candidate Quality Signals

**Skill Proficiency** — `(Person)-[hs:HAS_SKILL]->(Skill)`
- Property: `hs.proficiencyLevel`
- Values: `'expert'` | `'advanced'` | `'intermediate'` | `'beginner'`
- When to use: Ranking candidates, assessing readiness, computing skill depth scores

**Employment Status** — `(Person)`
- Property: `n.status`
- Values: `'active'` | `'inactive'` | `'pending'`
- When to use: Filtering to current employees or open candidates only

Rules:

• Include only labels/relationships that appear in the agent's tools or the user's stated questions — do not enumerate the entire schema
• Always include valid values for low-cardinality properties (copy from schema.json → values)
• If a property has has_fulltext_index: true, note that in the "When to use" line: "Supports full-text search"
• Keep each block to 4–6 lines; signal sections longer than ~300 words start to dilute the prompt budget

Anti-Patterns

---

Tool Names

Format: Verb + specific object. Max ~5 words.

Do NOT include the word "Tool" in a name — redundant and wastes the LLM's routing signal.

---

Tool Descriptions

The description is the primary signal the LLM uses to select a tool. It must answer three questions: 1. When to use this tool (trigger condition) 2. What it returns 3. When NOT to use it (prevents wrong selection when tools overlap)

Structure

Use [trigger condition]. Returns [what the output contains].
Do NOT use [exclusion condition] — use [alternative tool name] instead.

CypherTemplate

✅ "Use when the user asks for a specific agreement by its contract ID.
    Returns party names, agreement type, effective date, and expiration date.
    Do NOT use for aggregations or open-ended discovery — use the aggregation tool instead."

❌ "Runs MATCH (a:Agreement {contract_id: $contract_id}) and returns agreement data."
   (describes the Cypher, not the use case — LLM cannot route from this)

Rules:

• Describe the question pattern, not the query mechanics
• Name the key parameter in plain language ("by its contract ID", "by city name")
• If a filter parameter has a fixed set of valid values, state that in the description too: "Valid filter values are: 'Type A', 'Type B', 'Type C'"

SimilaritySearch

✅ "Use when the user wants to find nodes whose text is semantically similar to a phrase or sentence.
    Returns the top-K most similar results ranked by embedding distance.
    Do NOT use for exact property matches — use a CypherTemplate tool for those."

❌ "Performs vector search on the excerpt_embedding index."
   (mechanism, not use case)

Rules:

• Say what kind of text is embedded ("full clause text", "product descriptions", "support ticket summaries")
• Make clear this is approximate/semantic, not exact
• State the exclusion: exact-match queries belong in CypherTemplate

Text2Cypher

Text2Cypher is the most flexible tool — and the one most likely to be overused. The description must tightly bound its scope.

✅ "Use for open-ended discovery and aggregation: counting nodes, grouping by category,
    finding patterns not covered by other tools. Example questions: 'How many agreements
    exist per type?', 'Which organizations appear most frequently?'.
    Do NOT use for lookups by a known ID or property value — use the specific CypherTemplate
    tools for those. Do NOT use for similarity search — use the similarity search tool."

❌ "Translates natural language to Cypher."
   (says nothing about scope — LLM uses it for everything)

Rules:

• List 2–3 example questions it handles well — LLM uses these as routing anchors
• Always have at least two explicit exclusions naming the alternative tool
• Put this tool last in the tools array — LLM tries tools in order; Text2Cypher is the fallback

---

CypherTemplate Parameter Descriptions

Parameter descriptions are shown to the LLM when it needs to fill in a parameter value from the user's message. A poor description causes wrong values or failed extractions.

Rules

Always state what the parameter represents:

✅ "description": "The unique contract identifier, e.g. 'CUAD-001'"
❌ "description": "id"

Low-cardinality properties — always list valid values:

When schema.json → node_props[Label][prop].low_cardinality is true, copy the values array verbatim into the description. The LLM will normalize user input to a valid value.

✅ "description": "Clause type to filter by. Valid values: \"Anti-Assignment\", \"Exclusivity\", \"Governing Law\", \"IP Ownership Assignment\", \"License Grant\", \"Non-Compete\", \"Termination For Convenience\""

❌ "description": "The type of clause"
   (LLM guesses — may pass a value that matches no nodes)

Date parameters — include format:

✅ "description": "Effective date to filter from. Format: YYYY-MM-DD (e.g. '2023-01-01')"
❌ "description": "Start date"

ID parameters — say where the user gets the value:

✅ "description": "Contract ID from a prior 'Get Agreement' result or from the user's request"
❌ "description": "Contract ID"

Full-text indexed properties (has_fulltext_index: true in schema.json) — especially important to list valid values; the full-text index implies this property is a primary filter target.

Anti-Patterns

---

Tool Ordering

The LLM considers tools in array order when multiple tools could answer a question.

Recommended order: 1. Most specific CypherTemplate tools (exact lookups) 2. Broader CypherTemplate tools (filtered searches) 3. SimilaritySearch (if present) 4. Text2Cypher (always last — catches what others can't)

"tools": [
  { "type": "cypherTemplate", "name": "Get Agreement by ID", ... },
  { "type": "cypherTemplate", "name": "Get Agreements by Clause Type", ... },
  { "type": "similaritySearch", "name": "Find Similar Clause Text", ... },
  { "type": "text2cypher", "name": "Discover and Aggregate", ... }
]

---

Checklist Before Creating

• [ ] System prompt has: role sentence, supported use cases, explicit boundaries, tool preference order, uncertainty clause
• [ ] System prompt is ≤500 words
• [ ] Every tool name is a verb + specific object (no "Tool" suffix)
• [ ] Every tool description answers: when to use, what it returns, when NOT to use
• [ ] Every CypherTemplate tool names at least one exclusion with an alternative
• [ ] Text2Cypher is last in the tools array
• [ ] Text2Cypher description has ≥2 explicit exclusions
• [ ] Every parameter on a low-cardinality property lists all valid values verbatim
• [ ] Date/time parameters include format string
• [ ] ID parameters say where the user obtains the value

Aura Agent API Reference (v2beta1)

Full API specification: https://neo4j.com/docs/aura/platform/api/specification/aura_api_spec_v2beta1.yaml

Base URL

https://api.neo4j.io/v2beta1

Auth

All requests require a Bearer token obtained via:

POST https://api.neo4j.io/oauth/token
Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded
Body: grant_type=client_credentials

Token TTL: 3600 s. On 401/403: re-authenticate.

---

Agent Endpoints

---

CreateAgentRequest Schema

PatchAgentRequest Schema

All fields optional: name, description, system_prompt, dbid, is_private, is_mcp_enabled, tools, enabled.

---

Tool Schemas

CypherTemplate

{
  "type": "cypherTemplate",
  "name": "string (required)",
  "description": "string",
  "enabled": true,
  "config": {
    "template": "MATCH (n {id: $id}) RETURN n",
    "parameters": [
      {
        "name": "id",
        "data_type": "string",
        "description": "Node ID to look up (max 2000 chars)"
      }
    ]
  }
}

data_type enum: string | number | boolean | integer

SimilaritySearch

{
  "type": "similaritySearch",
  "name": "string (required)",
  "description": "string",
  "enabled": true,
  "config": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "index": "vector_index_name",
    "top_k": 5,
    "dimension": 1536,
    "post_processing_cypher": "OPTIONAL MATCH (node)<-[:HAS_EXCERPT]-(cc) RETURN node, score, cc"
  }
}

dimension must match the vector index dimension (vector.dimensions in schema.json → metadata.vector_index[].options.indexConfig). post_processing_cypher is optional — use it to traverse from matched nodes to related context nodes.

Text2Cypher

{
  "type": "text2cypher",
  "name": "string (required)",
  "description": "string",
  "enabled": true
}

---

Embedding Provider Options

Always confirm provider, model, and dimension with the user before writing a SimilaritySearch tool config. Do not default.

OpenAI (provider: "openai")

Vertex AI (provider: "vertexai")

---

AgentDetails Response Schema

{
  "id": "string",
  "name": "string",
  "description": "string",
  "system_prompt": "string",
  "dbid": "string",
  "project_id": "string",
  "organization_id": "string",
  "created_by": "string",
  "created_at": "datetime",
  "updated_at": "datetime",
  "is_private": false,
  "is_mcp_enabled": false,
  "enabled": true,
  "endpoint_link": "https://api.neo4j.io/v2beta1/organizations/.../invoke",
  "mcp_endpoint_link": "https://api.neo4j.io/v2beta1/organizations/.../mcp",
  "tools": [...]
}

---

InvokeAgentRequest

{ "input": "How many contracts are in the database?" }

Or multi-turn:

{
  "input": [
    { "role": "user", "content": "What contracts does Acme Corp have?" }
  ]
}

Note: Aura Agent does NOT store conversation history between requests. Include prior context in input array for multi-turn.

InvokeAgentResponse

{
  "id": "string",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "There are 510 contracts in the database." },
    { "type": "tool_use", "name": "Aggregation and Discovery Tool", "input": {...} },
    { "type": "tool_result", "content": [...] }
  ],
  "end_reason": "end_turn",
  "status": "completed",
  "usage": {
    "request_tokens": 245,
    "response_tokens": 87,
    "total_tokens": 332
  }
}

type enum: message | error

Error response:

{
  "type": "error",
  "error": {
    "message": "Agent not found",
    "type": "not_found",
    "status_code": 404
  }
}

---

HTTP Status Codes

---

Neo4j → Aura Agent Type Mapping

Used when reading schema.json to set data_type in CypherTemplate parameters. fetch_schema.py pre-computes the aura_data_type field on every property.

---

schema.json Structure

Output of scripts/fetch_schema.py. Extends get_structured_schema() with type annotations, cardinality enrichment, and index metadata.

{
  "node_props": {
    "Agreement": [
      {
        "property": "contract_id", "type": "INTEGER", "aura_data_type": "integer",
        "low_cardinality": false, "has_fulltext_index": false
      },
      {
        "property": "agreement_type", "type": "STRING", "aura_data_type": "string",
        "low_cardinality": true,
        "values": ["Distributor Agreement", "License Agreement", "NDA"],
        "has_fulltext_index": false
      }
    ],
    "ContractClause": [
      {
        "property": "type", "type": "STRING", "aura_data_type": "string",
        "low_cardinality": true,
        "values": ["Anti-Assignment", "Exclusivity", "Governing Law"],
        "has_fulltext_index": true
      }
    ]
  },
  "rel_props": {
    "IS_PARTY_TO": [
      {
        "property": "role", "type": "STRING", "aura_data_type": "string",
        "low_cardinality": true, "values": ["Buyer", "Seller"],
        "has_fulltext_index": false
      }
    ]
  },
  "relationships": [
    {"start": "Agreement", "type": "HAS_CLAUSE", "end": "ContractClause"},
    {"start": "Organization", "type": "IS_PARTY_TO", "end": "Agreement"}
  ],
  "metadata": {
    "node_count": 1240,
    "constraint": [...],
    "index": [...],
    "vector_index": [
      {
        "name": "excerpt_embedding",
        "type": "VECTOR",
        "labelsOrTypes": ["Excerpt"],
        "properties": ["embedding"],
        "state": "ONLINE",
        "options": {
          "indexConfig": {"vector.dimensions": 3072},
          "indexProvider": "vector-2.0"
        }
      }
    ],
    "fulltext_index": [
      {
        "name": "clause_type_fulltext",
        "type": "FULLTEXT",
        "labelsOrTypes": ["ContractClause"],
        "properties": ["type"],
        "state": "ONLINE"
      }
    ]
  }
}

Key fields:

• aura_data_type — Aura-compatible data_type value; use directly in CypherTemplate parameters
• low_cardinality — true if ≤50 distinct values; description MUST list valid values when true
• values — sorted list of distinct values; only present when low_cardinality: true
• has_fulltext_index — true if a FULLTEXT index covers this property; priority filter target
• metadata.vector_index — usable in SimilaritySearch; filter by state == "ONLINE"; use name as index, options.indexConfig["vector.dimensions"] as dimension
• metadata.fulltext_index — cross-referenced to set has_fulltext_index on matching properties

---

Geography Constraint

All Aura Agents run in europe-west1 (Belgium, GCP). Regardless of AuraDB instance region, agent inference happens in EU. Consider data residency requirements before storing PII in agent queries.

---

External Access (REST + MCP)

Enable via is_private: false and optionally is_mcp_enabled: true in the agent config.

External endpoint URL format:

https://api.neo4j.io/v2beta1/organizations/{orgId}/projects/{projectId}/agents/{agentId}/invoke

MCP server URL format:

https://api.neo4j.io/v2beta1/organizations/{orgId}/projects/{projectId}/agents/{agentId}/mcp

Both require the same OAuth2 bearer token. Use Aura API credentials (AURA_CLIENT_ID / AURA_CLIENT_SECRET) — not Neo4j database credentials.