neo4j-aura-agent-skill

使用する場合

• 既存の AuraDB インスタンスで Aura Agent を作成または設定する場合
• エージェントにツール（CypherTemplate、SimilaritySearch、Text2Cypher）を追加または更新する場合
• 外部アクセス用にエージェントをデプロイする場合（REST API エンドポイントまたは MCP サーバー）
• REST API 経由で自然言語クエリを使ってエージェントを呼び出す場合
• プロジェクト内の既存のエージェントを一覧表示、読み取り、または削除する場合
• Aura コンソールの Evaluation 機能でエージェントをテストするための評価データセット（JSON）を生成する場合

使用しない場合

• AuraDB インスタンスを作成・管理する → neo4j-aura-provisioning-skill
• ベクトルインデックスを作成する → neo4j-vector-index-skill
• Cypher を直接実行する → neo4j-cypher-skill
• Aura Graph Analytics セッションを構築する → neo4j-aura-graph-analytics-skill

---

Aura Agent とは

AuraDB 上の GraphRAG エージェントです。3 種類のツールを使って自然言語の質問に回答します。

• CypherTemplate — 予測可能な検索のためのパラメーター化クエリ
• SimilaritySearch — VECTOR インデックスを使ったベクトル類似検索
• Text2Cypher — 集計や探索のための自然言語 → Cypher 変換

アプリケーションコードを使わずに、自然言語を通じてグラフをユーザーやアプリに公開できます。REST または MCP エンドポイントとして利用でき、単一ターンと複数ターンに対応します。Cypher を完全に制御する場合、低レイテンシーの検索を行う場合、または直接書き込みを行う場合は、代わりに neo4j-cypher-skill を使用してください。

---

前提条件

• ナレッジグラフが読み込まれた稼働中の AuraDB インスタンス
• Organization 設定で「Generative AI assistance」が有効になっている
• プロジェクトで「Aura Agent」がオンになっている
• プロジェクト／Security レベルで「Tool authentication」が有効になっている
• プロジェクト管理者アクセス
• console.neo4j.io → Account Settings → API Credentials で取得した AURA_CLIENT_ID と AURA_CLIENT_SECRET
• AURA_ORG_ID、AURA_PROJECT_ID — Step 2 を参照してください。AURA_INSTANCE_ID — まだ設定されていない場合は、Step 2 で対話的に解決します
• Python 環境：スキルディレクトリで uv sync を実行します（または pip install neo4j neo4j-graphrag requests python-dotenv）
• .env と schema.json を .gitignore に追加します

---

Step 1 — 認証の確認

手動で認証情報を確認する場合にのみ使用します。スクリプトは内部で get_token() を呼び出します。

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}..."

トークンが空の場合：.env の AURA_CLIENT_ID／AURA_CLIENT_SECRET を確認してください。停止して報告してください。 トークンの有効期間：3600 秒。401／403 が発生した場合は再実行してください。

---

Step 2 — Organization ID と Project ID の解決

コンソール URL から取得する方法（最速）：console.neo4j.io を開き、プロジェクトに移動します。URL の形式： /organizations/{AURA_ORG_ID}/projects/{AURA_PROJECT_ID}

プログラムによる代替方法：

curl -s https://api.neo4j.io/v1/tenants \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {id, name}'
# tenant id maps to AURA_PROJECT_ID

.env に設定します：

AURA_ORG_ID=<organization-id>
AURA_PROJECT_ID=<project-id>

AURA_INSTANCE_ID を確認する — .env にすでに設定されている場合は、このステップの残りをスキップしてください。

設定されていない場合は、利用可能なインスタンスを一覧表示し、ユーザーに選択してもらいます：

curl -s "https://api.neo4j.io/v1/instances?tenantId=${AURA_PROJECT_ID}" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, name, status, region, type}'

出力をユーザーに表示します。**「エージェントを接続するインスタンスはどれですか？」**と尋ね、その後 .env に書き込みます：

AURA_INSTANCE_ID=<chosen-instance-id>
NEO4J_URI=neo4j+s://<chosen-instance-id>.databases.neo4j.io

一覧が空の場合：このプロジェクトには AuraDB インスタンスがありません。Aura Agent はインスタンスなしでは作成できません。停止して報告してください。 401 の場合：Step 1 を再実行してください。404 の場合：AURA_PROJECT_ID を確認してください。停止して報告してください。

---

Step 3 — 既存のエージェントを一覧表示

uv run python3 scripts/manage_agent.py list   # Linux/macOS
uv run python scripts\manage_agent.py list    # Windows

出力：エージェント ID、名前、有効状態、エンドポイント URL。

401 の場合：Step 1 を再実行してください。404 の場合：AURA_ORG_ID／AURA_PROJECT_ID を確認してください。停止して報告してください。

---

Step 4 — グラフスキーマの取得

.env に NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD が必要です。

uv run python3 scripts/fetch_schema.py   # Linux/macOS
uv run python scripts\fetch_schema.py    # Windows

schema.json を保存します。出力：ノード数／リレーションシップタイプ数、ノードラベルと型付きプロパティ（Aura の data_type を含む）、リレーションシップパターン、VECTOR インデックス。

データゲート — 以下の場合、スクリプトはエラーで終了し、schema.json を書き込みません：

• ノードが 2 未満、または
• リレーションシップタイプが 0

ゲートを通過できない場合：続行する前にデータベースにデータを読み込んでください。停止して報告してください。 ServiceUnavailable の場合：NEO4J_URI が neo4j+s:// を使用していることを確認してください。インスタンスは running である必要があります。停止して報告してください。 neo4j-graphrag not found の場合：uv add neo4j-graphrag を実行してください。停止して報告してください。

Step 5 の前に schema.json を読み込んでください。

---

ステップ 5 — ユースケースを特定する

ツールを設計する前に、references/authoring-guide.mdを読んでください。

リクエストとスキーマから回答を把握し、不明点があれば質問してください。ツールの種類やパラメーターを推測してはいけません。

1. 「このエージェントには、どのような質問に答えてほしいですか？」
2. 「最も重要なノードやリレーションシップはどれですか？」— schema.json → node_props と照合します
3. 「特定のプロパティ値で検索しますか？」→ CypherTemplate
4. 「集計、カウント、日付範囲に関する質問はありますか？」→ Text2Cypher
5. 「意味的に類似したテキストを検索しますか？」→ schema.json → metadata → vector_index を確認します
   • VECTOR インデックスが見つからない場合：ユーザーに伝え、SimilaritySearch をスキップします。まず neo4j-vector-index-skill に委任してください
   • VECTOR インデックスが見つかった場合：リクエストにプロバイダー／モデルの指定があれば使用し、なければ質問します（「どの埋め込みプロバイダーとモデルを使いますか？」）。対応モデルについては、references/REFERENCE.md → Embedding Provider Options を参照します。次元数はインデックスから取得します（vector.dimensions）。プロバイダー／モデルを推測してはいけません。

ツールの選択：

ユースケース	ツール
特定のプロパティ値による検索	cypherTemplate
意味検索	similaritySearch
集計、カウント、自由形式の質問	text2cypher

CypherTemplate のパラメーター：各パラメーターについて、schema.json → node_props または rel_props から aura_data_type を読み取り、data_type として使用します。プロパティに low_cardinality: true が設定されている場合、パラメーターの description に有効な値を列挙してください。値は schema.json の values 配列からコピーします。例："description": "Agreement type to filter by. Valid values: \"Distributor Agreement\", \"License Agreement\", \"NDA\""。has_fulltext_index: true が設定されたプロパティは、特にフィルター対象となる可能性が高いため、カーディナリティが低い場合は有効な値を含めてください。

SimilaritySearch の設定 — リクエストから値を取得し、インデックスから dimension を取得します。不明点があれば質問し、その後ツール設定を作成します。

フィールド	質問内容	情報源
provider	「"openai" と "vertexai" のどちらですか？」	リクエスト。指定がなければユーザーに確認
model	どのモデルですか？	リクエスト。指定がなければ、ユーザーが references/REFERENCE.md → Embedding Provider Options から選択
dimension	出力の次元数はいくつですか？	モデルで設定可能な場合は必須（表を参照）。固定モデルでは表の値を使用

index：state = ONLINE の schema.json → metadata → vector_index から name を使用します。dimension は、同じインデックスエントリーの vector.dimensions と一致している必要があります。

シグナルの一覧：ツールまたはユーザーが明示した質問に登場する各ラベルまたはリレーションシップについて、システムプロンプトにシグナルブロックを記述します。テンプレートとルールについては、references/authoring-guide.md → Signals inventory を参照してください。

設定 JSON を作成 → ユーザーに提示して確認 → 承認後にステップ 6 に進みます。ユーザーが続行を指示している場合、またはリクエストに完全な設定が含まれている場合は、確認を省略します。その場合は設定内容を提示し、続行します。

---

ステップ 6 — エージェントを作成する

最低限必要な設定：

{
  "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"
    }
  ]
}

実行前に設定をユーザーに提示し、確認してください（ユーザーがすでにこの内容での作成を依頼している場合は省略）：

uv run python3 scripts/manage_agent.py create --config agent-config.json

応答には id（AURA_AGENT_ID として保存）と endpoint_link が含まれます。応答に MCP URL は含まれません。is_mcp_enabled の場合：https://mcp.neo4j.io/agent?project_id=<project_id>&agent_id=<agent_id> — references/REFERENCE.md → External Access を参照してください。

---

ステップ 7 — エージェントを呼び出す（テスト）

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

--raw は、推論チェーンとトークン使用量を含む完全な JSON を出力します。

直接 curl を実行する場合（ステップ 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?"}'

---

ステップ 8 — エージェントを更新する（部分 PATCH）

変更するフィールドのみを含むパッチ JSON を作成します：

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

実行前にユーザーに提示し、確認してください：

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

---

ステップ 9 — エージェントを削除する

取り消しできません。設定は完全に削除されます。

実行前にユーザーに提示し、明示的な確認を待ってください：

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

202 Accepted が返されます。

---

ステップ 10 — 評価データセットを生成する

Aura のエージェント評価機能用に、インポート可能な評価データセット（質問は最大 50 件）を作成します。まず、references/evaluation-dataset-guide.md を読んでください。形式、tool_type の対応付け、質問数の上限、カテゴリのルールが定義されています。

1. 実際のエージェント定義をエクスポートします（説明だけをもとに作成しないでください。LLM はもっともらしいツール呼び出しをでっち上げます）。

   uv run python3 scripts/manage_agent.py get --agent-id "$AURA_AGENT_ID" > agent.json
   

   schema.json が存在することを確認します（ステップ 4）。
2. ツール（名前、種類、パラメーター、説明）を一覧表示し、カテゴリごとの計画（合計 ≤ 50 件）を提案します。カテゴリ：
   1. 中核的な事実確認（件数、集計、フィルター、比較、AND／NOT）
   2. ツールごとの検証 — Text2Cypher 以外の各ツールについて、正答できるはずの質問を 1 件、想定される制限に関するエッジケースを 1 件、設定で確認された構造的な不足を突く質問を 1 件
   3. セマンティック検索 — 完全一致＋言い換え／概念的な質問（similaritySearch ツールがある場合のみ）
   4. 複数ツールの組み合わせ — それぞれ 2～4 個のツールを連携させる
   5. Text2Cypher のストレステスト — 5.1 2～3 ホップ／集計、5.2 WITH／OPTIONAL の複合、5.3 最短経路／可変長、5.4 0 件の結果（ハルシネーション）に関する質問、5.5 スキーマに関する質問
3. すべての期待される回答を、データベースに対して Cypher を実行して導き出します（.env の認証情報を使うドライバーを使用）。回答を推測してはいけません。Cypher と不足の根拠を eval_dataset.provenance.json に保存します。
4. eval_dataset.json を作成し、検証します。

   uv run python3 scripts/validate_eval_dataset.py eval_dataset.json --agent agent.json
   

5. カテゴリごとの件数とサンプルをユーザーに提示します。コンソールで保存した後は質問を読み取り専用にでき、データセットにはバージョン履歴がないため、インポート前に確認するよう注意を促します（エージェント → 評価）。

---

ツールの設定

CypherTemplate

繰り返し使う予測可能な検索のための、事前定義済みパラメーター化クエリです。

{
  "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\", ...>"
      }
    ]
  }
}

カーディナリティが低い場合のルール：schema.json → node_props[Label][prop].low_cardinality が true の場合、description フィールドの末尾に schema.json → node_props[Label][prop].values の正確な値を記載する必要があります。このルールは rel_props のリレーションシッププロパティにも適用されます。

SimilaritySearch

VECTOR インデックスが必要です（state = ONLINE）。インデックス名は 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 の組み合わせについては、references/REFERENCE.md を参照してください。

Text2Cypher

自然言語 → Cypher。集計や探索のフォールバックとして使用します。

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

---

よくあるエラー

エラー	原因	対処方法
401 Unauthorized	トークンの有効期限切れ	ステップ 1 を再実行します
作成時の 403 Forbidden	プロジェクト管理者ではない	管理者アクセスをリクエストします
400 Bad Request	ツール設定が無効、または必須フィールドが不足	type のスペルを確認します：cypherTemplate、similaritySearch、text2cypher
404 Not Found	組織／プロジェクト／エージェント ID が間違っている	ID を確認するため list を再実行します
SimilaritySearch の作成時に 400	ベクトルインデックスがない	先にインデックスを作成します — neo4j-vector-index-skill を使用します
エージェントが結果を返さない	top_k が小さすぎる、またはインデックスが空	top_k を増やし、インデックスにデータが入力されていることを確認します

---

スクリプト

すべてのスクリプトは .env から認証情報を自動的に読み込みます。uv run python3 <script> で実行します。

スクリプト	目的
scripts/fetch_schema.py	AuraDB からグラフスキーマを取得し、schema.json に保存します
scripts/manage_agent.py	CRUD：エージェントの一覧表示、作成、取得、更新、削除
scripts/invoke_agent.py	自然言語のクエリをエージェントに送信します
scripts/validate_eval_dataset.py	評価データセットの JSON を検証します（任意で agent.json に照らして検証）

fetch_schema.py のパラメーター：

パラメーター	型	必須	デフォルト
NEO4J_URI	env	はい	—
NEO4J_USERNAME	env	いいえ	neo4j
NEO4J_PASSWORD	env	はい	—
NEO4J_DATABASE	env	いいえ	neo4j

manage_agent.py のパラメーター：

パラメーター	型	必須	環境変数の代替値
AURA_CLIENT_ID	env	はい	—
AURA_CLIENT_SECRET	env	はい	—
--org-id	arg	いいえ	AURA_ORG_ID
--project-id	arg	いいえ	AURA_PROJECT_ID
--agent-id	arg	get/update/delete	AURA_AGENT_ID
--config	arg	create/update	—

invoke_agent.py のパラメーター：

パラメーター	型	必須	環境変数の代替値
AURA_CLIENT_ID	env	はい	—
AURA_CLIENT_SECRET	env	はい	—
--org-id	arg	いいえ	AURA_ORG_ID
--project-id	arg	いいえ	AURA_PROJECT_ID
--agent-id	arg	はい	AURA_AGENT_ID
query	positional	はい	—
--raw	flag	いいえ	—

---

チェックリスト

• AuraDB インスタンスが running で、ナレッジグラフが読み込まれている
• 組織／プロジェクトの設定で「Generative AI assistance」と「Aura Agent」が有効になっている
• .env に AURA_CLIENT_ID、AURA_CLIENT_SECRET、AURA_ORG_ID、AURA_PROJECT_ID、AURA_INSTANCE_ID、NEO4J_URI、NEO4J_PASSWORD が設定されている
• .env と schema.json が .gitignore に含まれている
• 認証を確認済み（ステップ 1）
• 組織／プロジェクト ID を確認済み（ステップ 2）
• list による API 接続を確認済み（ステップ 3）
• schema.json を取得して確認済み（ステップ 4）— データの基準を満たしている（ノード 2 件以上、リレーションシップタイプ 1 件以上）
• ユーザーとユースケースを確認済み（ステップ 5）
• CypherTemplate の data_type に schema.json の aura_data_type を使用している
• SimilaritySearch の index に schema.json の metadata.vector_index を使用している（state=ONLINE）
• エージェント設定をユーザーに提示し、確認済み（ステップ 6）
• 必須フィールドが存在する：name、description、dbid、is_private、tools（1 件以上）
• 作成レスポンスから AURA_AGENT_ID を保存済み
• エージェントを呼び出し、レスポンスを確認済み（ステップ 7）
• 実行前にユーザーへ更新／削除の確認を取る
• 評価データセット：質問は 50 件以下、期待される回答は DB クエリから取得し、ツール呼び出しは agent.json に照らして検証済み（ステップ 10）