Graph RAG

Beta Feature

Graph RAG is currently in beta. Functionality, endpoints, and behavior may change in future releases.

Overview

Graph RAG extends traditional RAG by combining semantic search with knowledge graph retrieval, giving the agent access to both unstructured document content and structured entity/relationship data when generating responses. Under the hood, Graph RAG is powered by the Enterprise Context Engine (ECE).

The agent includes built-in hallucination detection that automatically validates responses against retrieved context and retries when hallucinations are detected.

Configuration

Create a Graph RAG agent:

{
    "name": "KnowledgeAssistant",
    "description": "Assistant with knowledge graph and document retrieval",
    "agentType": "graphRag",
    "notes": "Uses ECE for enriched answers with semantic and graph context",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "knowledgeGraphId": "7a0e6c74-7c62-4636-adbf-857340244e7d",
        "ontologyIds": ["9f8c1a2e-3b4d-4e5f-8a6b-7c8d9e0f1a2b"],
        "systemPrompt": "Context information is below.\n---------------------\n{context_str}\n---------------------\nGiven the context information and not prior knowledge, answer the query.\nQuery: {query_str}\nAnswer: ",
        "inferenceConfig": {
            "maxTokens": 4000,
            "temperature": 0.7
        },
        "hxqlQuery": "SELECT * FROM SysContent",
        "hybridSearch": true,
        "limit": 5,
        "adjacentChunkRange": 1,
        "adjacentChunkMerge": true,
        "guardrails": ["HAIP-Profanity", "HAIP-Insults-High"]
    }
}

Configuration Parameters

Parameter	Description	Required	Example
agentType	Must be "graphRag"	Yes	"graphRag"
knowledgeGraphId	Knowledge Graph ID	Yes	"7a0e6c74-7c62-4636-adbf-857340244e7d"
ontologyIds	Ontology IDs to scope graph document retrieval to (max 50). When set, only documents tagged with any of these ontologies are returned	No	["9f8c1a2e-3b4d-4e5f-8a6b-7c8d9e0f1a2b"]
llmModelId	LLM model identifier	Yes	"anthropic.claude-haiku-4-5-20251001-v1:0"
systemPrompt	Custom answer generation prompt (see below)	No	"Context: {context_str}\nQuery: {query_str}\nAnswer: "
inferenceConfig	LLM inference parameters	No	{"maxTokens": 4000, "temperature": 0.7}
hxqlQuery	HxQL filter for Content Lake retrieval	No	"SELECT * FROM SysContent"
hybridSearch	Enable hybrid search (embeddings + full-text)	No	true
limit	Maximum number of chunks to retrieve	No	5
adjacentChunkRange	Number of adjacent chunks to fetch around each result (0 = disabled)	No	1
adjacentChunkMerge	Merge adjacent chunks into the parent chunk in document order	No	true
guardrails	List of guardrail names or parameterized guardrails (see Guardrails guide)	No	["HAIP-Profanity"]

System Prompt (Synthesis Prompt)

The systemPrompt field controls how the agent generates answers from retrieved context. It uses two template placeholders:

Placeholder	Description
{context_str}	Replaced with the retrieved context (semantic and graph sources)
{query_str}	Replaced with the user's question

When systemPrompt is provided, it entirely replaces the default answer generation prompt. When omitted, the agent uses a built-in prompt optimized for grounded, factual responses.

Example custom prompt:

Context information is below.
---------------------
{context_str}
---------------------
You are a domain expert. Using ONLY the context above, provide a detailed answer.
If the context does not contain enough information, say so clearly.

Query: {query_str}
Answer:

tip

This follows the same pattern as the RAG agent's systemPrompt. If you already have prompts configured for RAG agents, they work identically with Graph RAG.

Retrieval Parameters

These can be passed at invocation time to override agent defaults:

Parameter	Description	Default
hxqlQuery	HxQL query to filter Content Lake documents	Config default
hybridSearch	Enable hybrid search (embeddings + full-text)	Config default
limit	Number of chunks to retrieve	Config default
adjacentChunkRange	Number of adjacent chunks to fetch around each result	Config default
adjacentChunkMerge	Merge adjacent chunks into parent chunk	Config default
rerankerTopN	Number of results to keep after reranking	Config default

Invocation

Non-Streaming

curl -X POST "/v1/agents/{agent_id}/versions/latest/invoke" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
        {
            "role": "user",
            "content": "What entities are related to Project Alpha?"
        }
    ]
}'

Invocation with Retrieval Overrides

curl -X POST "/v1/agents/{agent_id}/versions/latest/invoke" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
        {
            "role": "user",
            "content": "Summarize the HR onboarding process"
        }
    ],
    "hxqlQuery": "SELECT * FROM SysContent WHERE department = '\''HR'\''",
    "hybridSearch": true,
    "limit": 10,
    "adjacentChunkRange": 2
}'

Streaming

curl -N -X POST "/v1/agents/{agent_id}/versions/latest/invoke-stream" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
        {
            "role": "user",
            "content": "What entities are related to Project Alpha?"
        }
    ]
}'

tip

Responses come in chunks: newline-delimited JSON objects, each a valid JSON object on its own (response.output_text.delta chunks carry the delta text). The concatenation of all chunks forms the complete answer text, same wire format as Tool Agent streaming.

Multi-Turn Conversation

Graph RAG agents support multi-turn conversations by passing previous messages in the messages array. The last message must always have role: "user".

Session-Based Memory

Graph RAG agents support optional session-based short-term memory. Add an X-Session-ID header with a consistent UUID to maintain conversation context across multiple invocations. The platform does not auto-generate session IDs — you must generate and manage them yourself (any valid UUID).

curl -X POST "/v1/agents/{agent_id}/versions/latest/invoke" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "messages": [
        {
            "role": "user",
            "content": "What entities are related to Project Alpha?"
        },
        {
            "role": "assistant",
            "content": "Project Alpha is related to..."
        },
        {
            "role": "user",
            "content": "Which of those are in the finance department?"
        }
    ]
}'

Response Format

The response includes both the generated answer and source information from both retrieval sources:

{
    "object": "response",
    "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "createdAt": 1709654321,
    "output": [
        {
            "type": "message",
            "status": "completed",
            "role": "assistant",
            "content": [
                {
                    "type": "output_text",
                    "text": "Based on the retrieved documents and knowledge graph..."
                }
            ]
        }
    ],
    "customOutputs": {
        "sourceNodes": [
            {
                "docId": "doc-123",
                "chunkId": "chunk-456",
                "score": 0.95,
                "text": "Relevant document excerpt..."
            },
            {
                "docId": "entity-789",
                "chunkId": null,
                "score": null,
                "text": "Knowledge graph entity data..."
            }
        ],
        "knowledgeGraphNodes": [
            {
                "nodeType": "Document",
                "id": "0x1",
                "title": "Vendor Agreement - Acme Corp",
                "docType": "contract",
                "summary": "Master services agreement between Acme Corp and...",
                "clDocId": "6e4a7f58-13f1-4d3f-83b9-ec86c5b7df60",
                "documentId": "6e4a7f58-13f1-4d3f-83b9-ec86c5b7df60"
            },
            {
                "nodeType": "GlobalEntity",
                "id": "0x2",
                "canonicalName": "Acme Corp",
                "entityType": "ORG",
                "documentId": "6e4a7f58-13f1-4d3f-83b9-ec86c5b7df60"
            }
        ]
    }
}

The sourceNodes array contains entries from both semantic search and knowledge graph sources. The knowledgeGraphNodes array contains typed entities resolved directly from the Knowledge Graph — see Knowledge Graph Nodes below.

Knowledge Graph Nodes

Each entry in knowledgeGraphNodes is one of six typed node shapes, discriminated by the nodeType field:

nodeType	Fields	Description
Document	id, title, docType, summary, clDocId, documentId	A source document
TextChunk	id, clEmbedId, chunkIndex, text, docId, documentId	A chunk of document text
GlobalEntity	id, canonicalName, entityType, documentId	A resolved, canonical entity (e.g., an organization or person)
LocalEntity	id, mentionText, entityType, sentiment, documentId	A single mention of an entity within a document
BusinessObject	id, name, objectType, description, documentId	A domain-specific business object (e.g., an invoice or contract)
MetadataKV	id, key, value, valueType, documentId	A metadata key-value pair extracted from a document

documentId is present on every node type — it identifies the document a node belongs to (or, for Document nodes, the document itself), so you can correlate nodes across a response without a separate lookup. It may be null for nodes resolved from older Knowledge Graph data that hasn't been reprocessed.

tip

Document nodes also carry a clDocId field, kept for backward compatibility. For new integrations, prefer documentId.

Hallucination Detection

Graph RAG includes automatic hallucination detection:

• The generated answer is validated against the retrieved context
• If the answer contains information not supported by the context, it is flagged as hallucinated
• The agent retries answer generation (default: up to 2 retries)
• If retries are exhausted, the last generated answer is returned

This ensures responses stay grounded in the actual retrieved data rather than relying on the LLM's training knowledge.

Differences from Standard RAG

Feature	RAG	Graph RAG
Semantic search	Yes	Yes
Knowledge graph retrieval	No	Yes
Hallucination detection	Configurable	Built-in
Streaming support	Yes	Yes
Session-based memory	Yes	Yes

Best Practices

1. Data Preparation

   • Ensure your content is ingested into Content Lake with relevant entities and relationships
   • Graph RAG uses ECE to provide structured context that complements unstructured document search

2. System Prompt Design

   • Include both {context_str} and {query_str} placeholders
   • Instruct the LLM to use only the provided context
   • Consider mentioning both semantic and graph sources in your prompt

3. Retrieval Tuning

   • Use hxqlQuery to scope retrieval to relevant document sets
   • Adjust limit based on your use case (more chunks = more context but higher latency)
   • Use rerankerTopN to control how many chunks survive reranking

4. Guardrails

   • For comprehensive information on discovering, configuring, and merging guardrails, see the Guardrails guide.