Skip to main content

agrag.agents.build.build_agent

build_agent(*, engine:SearchEngine, llm_settings:AgentLLMSettings, agent_settings:AgentSettings | None = None, filters:SearchFilters | None = None, graph_schema:GraphSchema | None = None, tracer:Tracer | None = None) -> Any

Build the planner/researcher/verifier agent graph.

Constructs a LangGraph-based agent with three roles: planner (decomposes the question), researcher (has tools), and verifier (judges evidence sufficiency and returns a structured verdict).

Each call to ainvoke creates a fresh Ledger so citation numbering, identity mappings, and retrieved evidence do not leak across runs, and a fresh ResearchAttemptLimiter so one question's retry budget does not spend another's.

Parameters:

  • engine (SearchEngine) – Retrieval to expose to the researcher subagent's tools.
  • llm_settings (AgentLLMSettings) – The model every subagent role calls, via build_chat_model. With several clients, the remaining ones compose per strategy through agent middleware.
  • agent_settings (AgentSettings | None) – Loop-level configuration; defaults from environment. The recursion limit is enforced as the LangGraph recursion_limit in the invoke config, and max_research_attempts bounds how many times the planner may re-research after an INSUFFICIENT verdict.
  • filters (SearchFilters | None) – Retrieval scope applied to every tool search, e.g. document or tenant constraints. None searches unfiltered. A non-empty scope also removes the query_graph_directly tool, since a generated query cannot be confined to a scope.
  • graph_schema (GraphSchema | None) – The schema the researcher prompt and the query_graph_directly tool describe. None uses the engine's own resolved schema; a value that differs from the engine's raises, so the prompt cannot describe a graph the engine does not search.
  • tracer (Tracer | None) – Receives OpenInference spans for every ainvoke, including the researcher and verifier subagents' tool and model calls. None emits no spans. Spans carry the question, tool inputs, and evidence text.

Returns:

  • Any – An agent whose ainvoke returns an AgentRunResult: the
  • Any – run's messages plus its ledger, which maps each
  • Any – citation key in the answer back to its evidence. When
  • Any – deepagents is not installed, a single-search-plus-synthesis
  • Any – fallback with the same result shape.

Raises:

  • AgentMissingExtraError – tracer is set but the observability extra is not installed.
  • ValueError – graph_schema differs from the engine's schema.