Skip to main content
Version: 0.0.5 (stable)

Agent loop

The agent loop turns one question into a cited answer through repeated research and evidence review. The planner divides the question, the researcher searches the graph, and the verifier checks whether each part has support. The loop can search again when evidence is missing, but it cannot make unsupported source material true.

Why it exists​

One search can miss part of a multi-part question. "Who worked with Charles Babbage, and where?" needs two facts that may sit in different passages. The planner separates those questions, and the verifier exposes gaps before the answer is written.

The loop splits the question, so each part gets its own search. It reviews the evidence before it answers. A gap sends the agent back to search again instead of guessing.

The answer uses citation keys that point to evidence gathered during the run. Keys make claims traceable; they do not guarantee that the source itself is correct.

How it works​

The verdict decides the next step.

  1. The planner splits the question into two to four sub-questions.
  2. The planner sends each sub-question to the researcher. The researcher searches the graph with its tools and reports findings. Each finding carries a citation key.
  3. The planner sends the question, the sub-questions, and the findings to the verifier.
  4. The verifier checks each sub-question alone. Then it returns one verdict.
  5. The planner reads the verdict and acts on it.

By default, the researcher does not search candidates. Set AGENT_SEARCH_CANDIDATES=true to add search_unreviewed_candidates. The tool searches pending and approved candidates by text, not embeddings. Each result includes its review state and remains untrusted document data, even when approved. Candidate results have no citation keys, so the agent cannot cite them as evidence or follow instructions in their text. A scoped agent never receives the tool because candidate search cannot enforce the scope.

VerdictMeaningNext step
PASSEvery sub-question has supporting evidence. Nothing conflicts.The planner writes the answer.
INSUFFICIENTA sub-question lacks evidence, or a claim does not match its evidence. The verdict lists the gaps.The planner sends the gaps back to the researcher when retries remain.
CONTRADICTORYTwo cited pieces of evidence conflict.The planner does not retry. It states the conflict in the answer.

A worked example​

The question is "Who worked with Charles Babbage, and where?" The graph holds a chunk that says Ada Lovelace worked with Charles Babbage in London.

StepWhat happens
PlanSub-question 1: who worked with Charles Babbage? Sub-question 2: where did they work?
ResearchThe researcher finds the entity Ada Lovelace (E1), the entity London (E2), and the chunk that links them (C1).
VerifyEach sub-question has a key that supports it. The verdict is PASS.
Answer"Ada Lovelace worked with Charles Babbage in London [E1][E2][C1]."

Citation keys​

The agent sees evidence text that starts with a key. The letter of the key names the kind of evidence.

KeyEvidence
E1An entity, or a resolved entity
R1A relation
C1A chunk of source text
G1A community report
V1A value from a graph query

A run hands out keys in order and never changes one. Each call to the agent starts with an empty ledger, so two questions never share keys.

Limits​

By default, the planner can send work back to the researcher three times. The count starts after the first verifier check, so the first research pass is free. When the limit is reached, the planner answers from the evidence it has. It names the sub-questions that it did not answer. A limit of 50 graph steps stops a run that loops for another reason.

The result has two parts. messages ends with the answer. ledger maps each key to its evidence.

note

The full loop needs the agents extra. Without it, build_agent returns a simpler agent. That agent runs one search and writes one answer. It has no planner, researcher, verifier, or step limit.

Design choices

The verdict has three values. More searching cannot fix two sources that disagree. CONTRADICTORY stops the retries and moves the conflict into the answer. INSUFFICIENT is the only verdict that starts another search.

The verifier has no tools. It judges only the evidence in front of it. It cannot search until the researcher's claim looks right. The planner cites keys. The library attaches the evidence text for each key to the verifier's task, so the verifier can decide whether each key supports its claim.

The library can hide a scope from the model. You can limit every search to one document or tenant. Each tool applies the scope and refuses an argument outside it. The library removes the tool that runs generated Cypher, because a generated query cannot stay inside a scope.