1How do I answer questions about a whole collection, not just one document in it?
Search returns the passages most like the question, but "what are the main complaints across all our tickets?" has no such passage. GraphRAG reads the whole corpus once, maps entities and their relations, groups related ones into topics and summarises each. Broad questions are answered from those summaries.
You may need it if
- People ask for themes, trends or overviews: across interviews, tickets, reviews or reports.
- Your search-based assistant answers broad questions from three random documents and misses the big picture.
- Questions follow connections, such as which customers use the integrations that keep failing.
2When is building a graph of my documents not worth it?
Use it when
- Users ask about patterns across many documents, not facts inside one.
- The corpus changes slowly, so an index built once a week or once a month stays useful.
- The relationships matter: people, products, customers and how they connect.
Avoid it when
- Questions are about specific facts, such as a clause or a price, that one search can find.
Use Agentic RAG instead - The documents change every hour. Rebuilding the graph that often costs more than it returns.
Use Corrective RAG instead - What you need to keep is facts learned about users during conversations, not a map of a document collection.
Use Graph Memory instead
What it costs
- Model calls
- Index once: 1 per chunk + 1 per topic. Question: 2 to 3, or 1 per topic + 1 if broad
- Latency
- high
- Complexity
- high
3How does the corpus become a map, and how does a question use it?
Two separate runs. Indexing reads the corpus once, extracts entities and relations, groups them into topics and stores a summary of each. At question time, broad questions go to readers that each use one topic summary; specific ones go straight to the writer, which reads the graph around the named entities.
- Step 1 of 5
Read everything once
Ahead of any question, the graph builder reads the corpus in chunks. From each one it extracts entities, such as customers, products and issues, and how they relate, such as "customer X reported issue Y with product Z".
- Step 2 of 5
Group and summarise
Entities that are densely linked form topics, for example "billing errors after plan upgrades". Each topic gets a written summary. Everything is stored with links back to the source passages.
- Step 3 of 5
Broad or specific?
A question arrives. "What are the main reasons for churn?" is broad. "What issues has Acme reported?" names an entity. The route decides which part of the map to use.
- Step 4 of 5
Broad questions, one reader per topic
Each topic reader sees one summary and writes what it contributes to the question, with a helpfulness score. Readers whose topic is irrelevant return nothing.
- Step 5 of 5
Combine, or follow the links
For broad questions the writer merges the highest-scoring partial answers. For specific ones it reads the named entities, their neighbours and source passages straight from the graph. Both answers cite where they came from.
What each part does
- Corpus
- The document collection to index, such as tickets, interviews or reports.
- Graph builder
- Extracts entities and relations from each chunk, groups related entities into topics and summarises each topic.
- Index built
- The report of an indexing run: entities, relations and topics created.
- Graph and summaries
- Entities, relations, topic groups and their summaries, each linked to its source passages.
- Question
- A question about the indexed corpus, broad or specific.
- Broad or specific?
- Decides whether the question is about the whole corpus or about named entities in it.
- Topic readers
- Each reads one topic summary and writes a partial answer, with a score for how much it helps.
- Writer
- Combines the best partial answers, or answers from the entities around the ones named.
- Answer
- The answer, with the topics or entities and source passages it relies on.
- Graph builder → Graph and summaries: entities, relations, topics
- Broad or specific? → Topic readers: about the whole corpus
- Broad or specific? → Writer: about named entities
- Graph and summaries → Topic readers: topic summaries
- Graph and summaries → Writer: entity neighbourhood
- Topic readers → Writer: scored partial answers
Where it connects
A question about a corpus that has already been indexed.
The documents to index, each with an identifier, a date and its text. Runs separately from questions.
When: The writer has combined the partial answers or read the entities around the named ones.
The answer, the topics or entities it draws on, and the source passages behind them.
When: An indexing run over the corpus has finished.
The entities, relations and topics created or updated, with their counts and the documents covered.
Entities, relations, topic groups and topic summaries, each linked to source passages. Built by indexing runs, only read by question runs.
4What do I ask my assistant to set up?
The agents to launch
Graph builder, One call per chunk, then one call per topic
For each chunk, list the entities it mentions (people, companies, products, issues) and the relations between them, each with a one-line description and the chunk identifier. After all chunks, for each group of linked entities, write a summary of what the group is about. Use only what the chunks say.
Sees: One chunk at a time when extracting, and one topic's entities and relations when summarising. Never the questions users will ask.
Topic reader, One per topic summary, run in parallel
Read the question and one topic summary. Write what this topic contributes to the answer, in at most five sentences, and score its helpfulness from 0 to 10. If the topic is unrelated, score 0 and write nothing.
Sees: The question and a single topic summary. Not the other summaries or partial answers.
Writer
Answer the question from the material provided: either the scored partial answers or the named entities with their neighbours and source passages. Merge overlapping points, keep the most supported ones first and cite topics or sources.
Sees: The question and the material for its route. Not the readers that scored 0.
A prompt you can paste
Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.
You are the orchestrator of a multi-agent workflow that follows the "GraphRAG" architecture. Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it. # Task [Describe your task here] # GraphRAG Map the whole corpus ahead of time, then answer from the map. Input: the task above. It must provide: A question about a corpus that has already been indexed. If something essential is missing, ask for it before starting. Agents to launch: - Graph builder (One call per chunk, then one call per topic): For each chunk, list the entities it mentions (people, companies, products, issues) and the relations between them, each with a one-line description and the chunk identifier. After all chunks, for each group of linked entities, write a summary of what the group is about. Use only what the chunks say. Context for this agent: One chunk at a time when extracting, and one topic's entities and relations when summarising. Never the questions users will ask. - Topic reader (One per topic summary, run in parallel): Read the question and one topic summary. Write what this topic contributes to the answer, in at most five sentences, and score its helpfulness from 0 to 10. If the topic is unrelated, score 0 and write nothing. Context for this agent: The question and a single topic summary. Not the other summaries or partial answers. - Writer: Answer the question from the material provided: either the scored partial answers or the named entities with their neighbours and source passages. Merge overlapping points, keep the most supported ones first and cite topics or sources. Context for this agent: The question and the material for its route. Not the readers that scored 0. Procedure: 1. Indexing run: split the corpus into chunks of about a page. Launch the graph builder on each chunk and store entities and relations with their chunk identifiers. 2. Group densely linked entities into topics with a standard clustering method, then launch the graph builder once per topic to write its summary. Store everything. 3. Question run: decide whether the question is broad, about the corpus as a whole, or names specific entities. 4. If broad, launch one topic reader per summary in parallel, keep the partial answers scoring 5 or more, and pass them to the writer. 5. If specific, find the named entities in the graph and pass them, their direct neighbours and their source passages to the writer. 6. Launch the writer and return its answer with the sources used. Stop rule: Indexing stops when every chunk and every topic has been processed once. A question run makes one pass through its route with no retries, and stops after the writer. Exit: - `answer`, when: The writer has combined the partial answers or read the entities around the named ones. Deliver: The answer, the topics or entities it draws on, and the source passages behind them. # Final deliverable For a question, the answer with the topics or entities and source passages behind it. For an indexing run, the counts of entities, relations and topics, and the documents covered.
The same thing in code
import asyncio
import operator
from typing import Annotated, Literal, TypedDict
from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from langgraph.types import Send
from pydantic import BaseModel
llm = init_chat_model("anthropic:claude-sonnet-5-5")
class Entity(BaseModel):
name: str
kind: str
description: str
class Relation(BaseModel):
source: str
target: str
description: str
class Extraction(BaseModel):
entities: list[Entity]
relations: list[Relation]
class Partial(BaseModel):
score: int
text: str
class Route(BaseModel):
scope: Literal["broad", "specific"]
entities: list[str]
# the graph store: entities, relations and topic summaries, each linked to chunk ids
entities: dict[str, tuple[Entity, set[str]]] = {}
relations: list[tuple[Relation, str]] = []
topics: list[tuple[list[str], str]] = []
def cluster(rels: list[tuple[Relation, str]]) -> list[list[str]]:
return [] # plug in community detection (Leiden, Louvain) over the entity graph
async def ask[T: BaseModel](schema: type[T], prompt: str) -> T:
out = await llm.with_structured_output(schema).ainvoke(prompt)
assert isinstance(out, schema)
return out
async def index(chunks: dict[str, str]) -> dict[str, int]:
# indexing run: the graph builder sees one chunk at a time, never user questions
async def extract(cid: str, text: str) -> None:
x = await ask(Extraction, "List the entities (people, companies, products, issues) and relations "
f"in this chunk, each with a one-line description. Use only what it says.\n\n{text}")
for e in x.entities:
entities.setdefault(e.name, (e, set()))[1].add(cid)
relations.extend((r, cid) for r in x.relations)
await asyncio.gather(*(extract(c, t) for c, t in chunks.items()))
for group in cluster(relations):
facts = [r.description for r, _ in relations if r.source in group or r.target in group]
msg = await llm.ainvoke(f"Summarise what this group of entities is about.\nEntities: {group}\nRelations: {facts}")
topics.append((group, msg.text))
return {"entities": len(entities), "relations": len(relations), "topics": len(topics)}
class State(TypedDict):
question: str
named: list[str]
partials: Annotated[list[Partial], operator.add]
material: str
answer: str
class ReaderIn(TypedDict):
question: str
summary: str
async def route(state: State) -> dict:
r = await ask(Route, "Is this question about the corpus as a whole (broad) or about named entities "
f"(specific)? List any entities it names.\n\n{state['question']}")
return {"named": r.entities if r.scope == "specific" else []}
def fan_out(state: State) -> list[Send] | Literal["neighbourhood"]:
if state["named"]:
return "neighbourhood"
return [Send("reader", {"question": state["question"], "summary": s}) for _, s in topics]
async def reader(state: ReaderIn) -> dict:
# one reader per topic: the question and a single summary
p = await ask(Partial, "Write what this topic contributes to the answer, in at most five sentences, and "
"score its helpfulness 0 to 10. Unrelated: score 0, no text.\n\n"
f"Question: {state['question']}\nTopic summary: {state['summary']}")
return {"partials": [p] if p.score > 0 else []}
def neighbourhood(state: State) -> dict:
near = [(r, c) for r, c in relations if r.source in state["named"] or r.target in state["named"]]
lines = [f"{r.source} -> {r.target}: {r.description} [chunk {c}]" for r, c in near]
return {"material": "\n".join(lines)}
async def writer(state: State) -> dict:
kept = sorted((p for p in state["partials"] if p.score >= 5), key=lambda p: -p.score)
material = state["material"] or "\n\n".join(p.text for p in kept)
msg = await llm.ainvoke("Answer from the material below. Merge overlapping points, put the best "
f"supported first and cite topics or chunks.\n\nQuestion: {state['question']}\n\n{material}")
return {"answer": msg.text}
g = StateGraph(State)
g.add_node("route", route)
g.add_node("reader", reader)
g.add_node("neighbourhood", neighbourhood)
g.add_node("writer", writer)
g.add_edge(START, "route")
g.add_conditional_edges("route", fan_out, ["reader", "neighbourhood"])
g.add_edge("reader", "writer")
g.add_edge("neighbourhood", "writer")
g.add_edge("writer", END)
app = g.compile()
async def run(task: str):
# question run: one pass through its route, no retries
state = await app.ainvoke({"question": task, "named": [], "partials": [], "material": "", "answer": ""})
return {"answer": state["answer"], "entities": state["named"], "material": state["material"]}
Replace cluster with a real community-detection step, merge entity aliases before grouping, and persist the store instead of module-level dicts.
import asyncio
import json
from typing import Any
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
# the graph store, in memory: entity -> chunk ids, relations with their chunk, topic summaries
entities: dict[str, set[str]] = {}
relations: list[dict[str, str]] = []
topics: list[dict[str, Any]] = []
def cluster(rels: list[dict[str, str]]) -> list[list[str]]:
return [] # plug in community detection (Leiden, Louvain) over the entity graph
AGENTS = {
"graph-builder": AgentDefinition(
description="Extracts entities and relations from one chunk, or summarises one topic.",
prompt="Given a chunk, list the entities it mentions (people, companies, products, issues) and the "
"relations between them, each with a one-line description. Given a topic's entities and "
"relations, summarise what the group is about. Use only what you are given.", tools=[]),
"topic-reader": AgentDefinition(
description="Scores how much one topic summary helps answer a question.",
prompt="Read the question and one topic summary. Write what this topic contributes, in at most five "
"sentences, and score its helpfulness 0 to 10. If unrelated, score 0 and write nothing.",
tools=[]),
"writer": AgentDefinition(
description="Writes the final cited answer from the material provided.",
prompt="Answer from the material provided: scored partial answers or entities with their neighbours "
"and sources. Merge overlapping points, put the best supported first, cite topics or sources.",
tools=[]),
}
EXTRACTION = {"type": "object", "required": ["relations"], "properties": {"relations": {
"type": "array", "items": {"type": "object", "required": ["source", "target", "description"],
"properties": {k: {"type": "string"} for k in ["source", "target", "description"]}}}}}
ROUTE = {"type": "object", "required": ["scope", "entities"], "properties": {
"scope": {"enum": ["broad", "specific"]}, "entities": {"type": "array", "items": {"type": "string"}}}}
async def ask(prompt: str, schema: dict[str, Any] | None = None) -> Any:
options = ClaudeAgentOptions(agents=AGENTS, allowed_tools=["Agent"],
output_format={"type": "json_schema", "schema": schema} if schema else None)
async for msg in query(prompt=prompt, options=options):
if isinstance(msg, ResultMessage):
return msg.structured_output if schema else msg.result
async def index(chunks: dict[str, str]) -> dict[str, int]:
# indexing run: one sub-agent call per chunk, then one per topic
async def extract(cid: str, text: str) -> None:
x = await ask(f"Use the graph-builder agent on this chunk and return its relations.\n\n{text}", EXTRACTION)
for r in x["relations"]:
relations.append({**r, "chunk": cid})
for name in (r["source"], r["target"]):
entities.setdefault(name, set()).add(cid)
await asyncio.gather(*(extract(c, t) for c, t in chunks.items()))
for group in cluster(relations):
rels = [r for r in relations if r["source"] in group or r["target"] in group]
summary = await ask("Use the graph-builder agent to summarise this topic and return its summary.\n\n"
+ json.dumps({"entities": group, "relations": rels}))
topics.append({"entities": group, "summary": summary})
return {"entities": len(entities), "relations": len(relations), "topics": len(topics)}
async def run(task: str):
r = await ask(f"Is this question about the corpus as a whole (broad) or about named entities "
f"(specific)? List the entities it names. Do not answer it.\n\n{task}", ROUTE)
if r["scope"] == "broad":
# fan-out: the prompt launches one isolated topic reader per summary
listing = "\n".join(f"[topic {i}] {t['summary']}" for i, t in enumerate(topics))
answer = await ask(
"Launch one topic-reader agent per topic below, in parallel. Give each only the question and its "
"own summary. Keep partial answers scoring 5 or more, then pass only those to the writer agent "
f"with the question, and return the writer's answer.\n\nQuestion: {task}\n\n{listing}")
return {"answer": answer, "route": "broad"}
near = [x for x in relations if x["source"] in r["entities"] or x["target"] in r["entities"]]
answer = await ask("Use the writer agent with this question and the entity neighbourhood below; return "
f"its answer unchanged.\n\nQuestion: {task}\n\n{json.dumps(near)}")
return {"answer": answer, "route": "specific", "sources": sorted({x["chunk"] for x in near})}
Replace cluster with a real community-detection step and persist the graph; the broad route trusts the orchestrator prompt to keep each reader isolated.
import asyncio
from typing import Literal
from agents import Agent, Runner
from pydantic import BaseModel
class Relation(BaseModel):
source: str
target: str
description: str
class Extraction(BaseModel):
relations: list[Relation]
class Partial(BaseModel):
score: int
text: str
class Route(BaseModel):
scope: Literal["broad", "specific"]
entities: list[str]
# the graph store, in memory: relations with their chunk id, and topic summaries
relations: list[tuple[Relation, str]] = []
topics: list[str] = []
def cluster(rels: list[tuple[Relation, str]]) -> list[list[str]]:
return [] # plug in community detection (Leiden, Louvain) over the entity graph
builder = Agent(name="Graph builder", output_type=Extraction,
instructions="List the entities in this chunk (people, companies, products, issues) as "
"relations between them, each with a one-line description. Use only the chunk.")
summariser = Agent(name="Graph builder (topics)",
instructions="Summarise what this group of linked entities is about, from its relations only.")
router = Agent(name="Router", output_type=Route,
instructions="Is the question about the corpus as a whole (broad) or about named entities "
"(specific)? List the entities it names.")
reader = Agent(name="Topic reader", output_type=Partial,
instructions="Write what this topic contributes to the answer, in at most five sentences, and "
"score its helpfulness 0 to 10. If unrelated, score 0 and write nothing.")
writer = Agent(name="Writer",
instructions="Answer from the material provided. Merge overlapping points, put the best "
"supported first, and cite topics or chunks.")
async def index(chunks: dict[str, str]) -> dict[str, int]:
# indexing run: the builder sees one chunk at a time, never the questions
results = await asyncio.gather(*(Runner.run(builder, t) for t in chunks.values()))
for cid, res in zip(chunks, results):
relations.extend((r, cid) for r in res.final_output_as(Extraction).relations)
for group in cluster(relations):
facts = "\n".join(r.description for r, _ in relations if r.source in group or r.target in group)
topics.append((await Runner.run(summariser, f"Entities: {group}\nRelations:\n{facts}")).final_output)
return {"relations": len(relations), "topics": len(topics)}
async def run(task: str):
route = (await Runner.run(router, task)).final_output_as(Route)
if route.scope == "broad":
# one reader per topic summary, in parallel, each sees a single summary
runs = await asyncio.gather(*(Runner.run(reader, f"Question: {task}\nTopic summary: {s}") for s in topics))
partials = sorted((r.final_output_as(Partial) for r in runs), key=lambda p: -p.score)
material = "\n\n".join(p.text for p in partials if p.score >= 5)
sources: list[str] = []
else:
near = [(r, c) for r, c in relations if r.source in route.entities or r.target in route.entities]
material = "\n".join(f"{r.source} -> {r.target}: {r.description} [chunk {c}]" for r, c in near)
sources = sorted({c for _, c in near})
# one pass through the route, no retries
out = await Runner.run(writer, f"Question: {task}\n\n{material}")
return {"answer": out.final_output, "route": route.scope, "sources": sources}
Replace cluster with a real community-detection step, merge entity aliases before grouping, and persist the store with a build date.
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, Output } from 'ai';
import { z } from 'zod';
const model = anthropic('claude-sonnet-5-5');
const Relation = z.object({ source: z.string(), target: z.string(), description: z.string() });
type Relation = z.infer<typeof Relation> & { chunk: string };
// the graph store, in memory: relations with their chunk id, and topic summaries
const relations: Relation[] = [];
const topics: { entities: string[]; summary: string }[] = [];
function cluster(rels: Relation[]): string[][] {
return []; // plug in community detection (Leiden, Louvain) over the entity graph
}
export async function index(chunks: Record<string, string>) {
// indexing run: the graph builder sees one chunk at a time, never the questions
await Promise.all(
Object.entries(chunks).map(async ([chunk, text]) => {
const { output } = await generateText({
model,
output: Output.object({ schema: z.object({ relations: z.array(Relation) }) }),
instructions:
'List the entities in this chunk (people, companies, products, issues) as relations between ' +
'them, each with a one-line description. Use only what the chunk says.',
prompt: text,
});
relations.push(...output.relations.map((r) => ({ ...r, chunk })));
}),
);
for (const group of cluster(relations)) {
const facts = relations.filter((r) => group.includes(r.source) || group.includes(r.target));
const { text } = await generateText({
model,
instructions: 'Summarise what this group of linked entities is about, from its relations only.',
prompt: JSON.stringify({ entities: group, relations: facts }),
});
topics.push({ entities: group, summary: text });
}
return { relations: relations.length, topics: topics.length };
}
export async function run(task: string) {
const { output: route } = await generateText({
model,
output: Output.object({
schema: z.object({ scope: z.enum(['broad', 'specific']), entities: z.array(z.string()) }),
}),
instructions:
'Is the question about the corpus as a whole (broad) or about named entities (specific)? ' +
'List the entities it names.',
prompt: task,
});
let material: string;
let sources: string[] = [];
if (route.scope === 'broad') {
// one reader per topic, in parallel, each sees the question and a single summary
const partials = await Promise.all(
topics.map(async (t) => {
const { output } = await generateText({
model,
output: Output.object({ schema: z.object({ score: z.number().int(), text: z.string() }) }),
instructions:
'Write what this topic contributes to the answer, in at most five sentences, and score its ' +
'helpfulness 0 to 10. If unrelated, score 0 and write nothing.',
prompt: `Question: ${task}\nTopic summary: ${t.summary}`,
});
return output;
}),
);
material = partials.filter((p) => p.score >= 5).sort((a, b) => b.score - a.score).map((p) => p.text).join('\n\n');
} else {
const near = relations.filter((r) => route.entities.includes(r.source) || route.entities.includes(r.target));
material = near.map((r) => `${r.source} -> ${r.target}: ${r.description} [chunk ${r.chunk}]`).join('\n');
sources = [...new Set(near.map((r) => r.chunk))];
}
// one pass through the route, no retries
const { text } = await generateText({
model,
instructions:
'Answer from the material provided. Merge overlapping points, put the best supported first, and cite topics or chunks.',
prompt: `Question: ${task}\n\n${material}`,
});
return { answer: text, route: route.scope, sources };
}
Replace cluster with a real community-detection step, merge entity aliases before grouping, and persist the store with a build date.
Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.
What goes wrong
- The same customer named three ways becomes three entities. Merge names that refer to the same thing before grouping.
- Topic summaries go stale as documents arrive. Date every index and rebuild it on a schedule that matches how fast the corpus changes.
- Summaries can drift from their sources. Keep the links to source passages so any claim in an answer can be traced.
Chain it
Its result can feed
- Reflection conditional
Condition: Only the answer part of A's payload fits B's entry, so the link holds when the synthesised answer is passed as the result to improve and the evidence comes along only as reference.
- Chain of Verification conditional
Condition: Only the answer part of A's payload fits B's entry, so the link holds when the answer is passed as the existing answer whose factual claims are to be checked, with the evidence kept as reference.
- Debate conditional
Condition: Only the answer part of A's payload fits B's entry, so the link holds when the answer is passed as an existing answer to challenge, with the evidence kept as background.
- Constitutional Critique conditional
Condition: Only the answer part of A's payload fits B's entry, so the link holds when the answer is passed as the text to check against the constitution, with the evidence kept as reference.
- Textual Backpropagation conditional
Condition: The link holds for the answer part of A's payload; the topics, entities and source passages are evidence, which B's entry does not accept as a work item.