Skip to main content
Version: latest

Agent loop

The agent loop turns one question into a cited answer. A single agent works on a named task. It discovers evidence in the graph, fetches the exact text it needs, and writes an answer that cites only the evidence it fetched. A citation check runs after the answer, and one repair pass removes or replaces citations that do not check out.

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 agent runs several evidence calls for one task, and it keeps the task state between calls.

The agent can also resume a task. Each task has a name. A run with the same task name reloads the evidence fetched earlier and the events recorded for that task.

Citations make claims traceable. They do not make the source correct.

How it works​

  1. The run creates or resumes the task and builds its task view. The view is data, and the agent reads it before it acts.
  2. The agent calls evidence tools. discover_evidence returns evidence ids for passages in scope. find_entities and explore search the graph. navigate moves from one passage to related text.
  3. The agent calls fetch_evidence on the ids it wants to cite. Only a fetch that returns complete text makes an id citable.
  4. The agent writes the answer and cites ids in square brackets.
  5. The run checks every cited id against the ids that were fetched in scope. If some are invalid and the tool budget has room, one repair pass asks the agent to remove or fetch them.
  6. The run returns the answer, a status, the valid citations, and any invalid ids.

The agent can also record progress with set_step and record decisions with record_decision. It reads earlier decisions with search_decisions. A decision counts only when its write tool confirms that the record was saved.

Result status​

StatusMeaning
answeredThe answer has no invalid citations and no limit was hit.
insufficient_evidenceThe answer says that the evidence is insufficient.
partialSome cited ids failed the citation check after the repair pass.
partial_retrievalA retrieval call failed during the run.
budget_exhaustedThe run hit the step limit or the tool-call limit.
recording_failedA task event or decision could not be recorded.

Citation ids​

Evidence ids start with ev1:. A span id names a range of a chunk, and a chunk id names a whole chunk. The agent copies these ids from discovery results. It does not make them up.

Limits​

These settings bound one run. Set them with AGENT_ variables or AgentSettings.

SettingDefaultEffect
recursion_limit50The maximum LangGraph steps. A run that reaches it returns budget_exhausted.
max_tool_calls20The maximum tool calls in one task run.
max_result_characters12000The maximum text that one evidence fetch returns.

The result has two parts that matter most. answer holds the final text. citations lists the fetched evidence that the answer cites.

note

The agent needs the agents extra. build_agent raises AgentMissingExtraError when the extra is not installed.

Design choices

The agent has no subagents. The general-purpose subagent is disabled in the harness profile, so every evidence call runs in the one agent.

The agent judges only the evidence it fetched. The citation check, not the model, decides whether a cited id is valid. A fetch outside the trusted scope fails, so the agent cannot cite text the caller did not allow.

Source passages, task events, and tool results are data. The system prompt tells the agent not to follow instructions found in them.