Agentic Runtime

RagLogic AI does not use a single monolithic “AI agent”. The online path uses a small set of narrow, typed agents with structured outputs, validation, and fallbacks. The goal is not autonomy for its own sake. The goal is to make the retrieval path adaptive while keeping the runtime auditable.

What is actually agentic

The current hot path uses four agentic building blocks:

• an optional intent parser embedded in query routing,

• a planner that decides retrieval strategy,

• a CRAG evaluator that checks retrieval sufficiency,

• a refinement agent that rewrites the query when retrieval is not sufficient.

Important

These are constrained runtime agents, not open-ended tool-using copilots. They return typed objects validated by PydanticAI and the runtime keeps heuristic fallbacks when an agent call fails.

Figure 1: Agentic control loop

        flowchart TD
    Q[User question] --> ROUTE[Routing step]
    ROUTE --> INTENT[Optional intent parser<br/>normalize query and select profile]
    ROUTE --> PLAN[Planner agent<br/>runs in parallel with routing]
    INTENT --> RETCFG[Retrieval profile, granularity,<br/>top_k, graph usage]
    PLAN --> DECIDE{Skip retrieval?}
    RETCFG --> RET[Primary retrieval]
    DECIDE -- yes --> EARLY[Clarify, hard block,<br/>or llm_only path]
    DECIDE -- no --> RET
    RET --> CRAG[CRAG evaluator]
    CRAG -- SUFFICIENT --> ENRICH[Context and graph enrichment]
    CRAG -- PARTIAL / INSUFFICIENT --> REFINE[Refinement agent]
    REFINE --> RET2[Refined retrieval]
    RET2 --> ENRICH
    ENRICH --> COMP{Compression needed?}
    COMP -- yes --> CMP[Context compression]
    COMP -- no --> GEN[Generation + citation validation]
    CMP --> GEN
    

Figure 2: Runtime agent inventory

        flowchart LR
    subgraph Routing
        IP[Intent parser]
        QR[Heuristic router]
    end

    subgraph Planning
        PL[Planner]
        EV[CRAG evaluator]
        RF[Refinement]
    end

    subgraph Guardrails
        SO[Structured outputs]
        OV[Output validators]
        FB[Heuristic fallback]
        TM[Trace metadata]
    end

    IP --> SO
    PL --> SO
    EV --> SO
    RF --> SO
    SO --> OV
    OV --> FB
    OV --> TM
    

Agent inventory

Agent or component	Current role	Returned data	Fallback behavior
Intent parser	Optional LLM-assisted routing before heuristic fallback	retrieval profile, normalized query, graph hint, granularity, confidence	if unavailable, routing stays heuristic and deterministic
Planner	Decide whether retrieval should run and how deep it should go	primary_query, intent_class, clarification, complementary queries, compression flag	passthrough plan with original question
CRAG evaluator	Score whether retrieved evidence is sufficient	SUFFICIENT, PARTIAL, or INSUFFICIENT plus gap hint	defaults to sufficient instead of breaking the request
Refinement agent	Generate a better retrieval query after a gap was detected	refined_query and rationale	simple concatenated fallback query
Decomposition agent	Available helper for multi-facet questions	sub-questions and synthesis hint	not currently on the main planning hot path

What the planner changes concretely

The planner does not answer the user. It only changes how retrieval behaves. The most important decisions are:

• whether the request is conversational or documentary,

• whether retrieval should be skipped,

• what the primary search query should be,

• whether follow-up retrieval queries are needed,

• whether the final context is likely to require compression,

• whether strict grounding should be enforced.

That makes the runtime more adaptive without letting the LLM directly control application side effects.

Why this design is safer than a generic agent loop

• Every active agent returns a typed schema, not free-form instructions.

• Output validators reject malformed structured outputs.

• The runtime records planner_path, tool_trace, and output-validation retries.

• Heuristic routing and conservative fallbacks remain available when an agent call fails.

• The final user answer is still governed by source and citation constraints.

Operational traceability

The agentic layer is visible in runtime metadata and streaming traces. The most useful fields are:

• planner_runtime

• planner_run_id

• planner_path

• tool_trace

• output_validation_retries

• agentic.crag

• agentic.complementary

• agentic.compression

These fields matter because they let the UI and observability stack explain why the runtime retrieved more, retrieved less, clarified, or refined a query.

Code anchors

• Structured agent bridge: packages/lalandre_core/lalandre_core/llm/structured.py

• Agent definitions: packages/lalandre_rag/lalandre_rag/agentic/tools.py

• Agent runtime helpers: packages/lalandre_rag/lalandre_rag/agentic/runtime.py

• Planning graph orchestration: packages/lalandre_rag/lalandre_rag/agentic/graph.py

• Hot-path entry point: packages/lalandre_rag/lalandre_rag/modes/hybrid_mode.py

Scope note

The decomposition helper exists in the codebase but is not currently wired as a material step in the main planning graph. The pages above therefore focus on the agents that influence the production online path today.