Agentic Queries

What is an agentic query?

An agentic query is a two-phase operation:

1. Vector phase — find the top-K nodes most similar to your query text using Cloudflare Vectorize
2. Graph phase — from each similarity hit, run a depth-limited traversal to surface related context nodes

The result gives an AI agent both the semantically relevant entry points and the structured relationships around them — in one round trip.

Query embedding ──▶ Vectorize (top-K hits)
                          │
                          ▼
                 Traversal from each hit
                          │
                          ▼
              Merged context: nodes + edges

Tip

This pattern eliminates the separate “retrieve then traverse” step common in manual RAG pipelines. The graph engine handles both in a single Durable Object call.

API

POST /graphs/{graphId}/agentic-query
Content-Type: application/json

{
  "query": "Who are Alice's colleagues at technology companies?",
  "topK": 5,
  "depth": 2,
  "direction": "outbound"
}

Parameters

Field	Type	Default	Description
query	string	required	Natural language or semantic query text
topK	number	5	Number of vector similarity hits
depth	number	2	Traversal depth from each hit
direction	string	outbound	Edge direction for traversal
nodeType	string	all	Filter vector search to a specific node type

Response

{
  "query": "Who are Alice's colleagues at technology companies?",
  "vectorHits": [
    { "nodeId": "node_alice", "score": 0.94, "type": "Person" }
  ],
  "context": {
    "nodes": [
      { "id": "node_alice", "type": "Person", "data": { "name": "Alice" } },
      { "id": "node_bob",   "type": "Person", "data": { "name": "Bob" } },
      { "id": "node_acme",  "type": "Company","data": { "name": "Acme Inc" } }
    ],
    "edges": [
      { "type": "WORKS_AT", "sourceId": "node_alice", "targetId": "node_acme" },
      { "type": "WORKS_AT", "sourceId": "node_bob",   "targetId": "node_acme" }
    ]
  },
  "tokenEstimate": 320
}

Embedding node data

For vector search to work, nodes must have embeddings stored. The API accepts an embedding field when creating or updating a node:

POST /graphs/{graphId}/nodes/Person
{
  "id": "node_alice",
  "data": { "name": "Alice", "title": "Engineer" },
  "embedding": [0.021, -0.043, 0.102, ...]
}

Embeddings are stored in the Durable Object and synced to Cloudflare Vectorize automatically.

Use in an AI agent

import { GraphDBClient } from "@graphdb-labs/sdk";

const client = new GraphDBClient({ apiKey: process.env.GRAPHDB_API_KEY });

const context = await client.agenticQuery(graphId, {
  query: userMessage,
  topK: 5,
  depth: 2,
});

// Pass context.nodes + context.edges as grounding to your LLM
const response = await llm.complete({
  system: `You are a helpful assistant. Use this graph context:\n${JSON.stringify(context)}`,
  user: userMessage,
});