Nexus Agent: An Enterprise AI Agent Platform Built on a Three-Tier Executor Architecture

The Problem Nexus Agent Addresses

Most engineers learn AI application development by following a tutorial: call an embedding API, insert some text into a vector database, ask a language model to answer from the retrieved results, and declare RAG complete. The README states plainly that this approach produces a demo, not a production system, and identifies the gap: question rewriting, sub-question splitting, knowledge-domain narrowing, mixed retrieval, parent-child chunk aggregation, hallucination control via evidence short-circuiting, and session memory are all missing from tutorial-grade RAG.

Nexus Agent is designed as a reference for engineers who want to understand and implement each of those missing pieces. The README frames it as covering "the complete closed loop from document ingestion, knowledge routing, hybrid retrieval, to evidence generation, tool calls, and observable governance." The stated goal is a system whose complexity matches a real enterprise deployment, not a simplified example.

Three-Tier Executor: Routing Before Acting

The central design decision in Nexus Agent is that not all questions should go to a ReAct agent. The system routes each user message to one of three executors based on a deterministic priority order:

| Executor | Trigger condition | Method | |---|---|---| | Ambiguity clarification | Insufficient information to determine intent | Generates a clarifying question for the user | | RAG knowledge Q&A | Question answerable from the knowledge base | Evidence-driven generation with traceable citations | | ReAct Agent | Open-ended question requiring live search or multi-step reasoning | Autonomous decision + tool calls + reasoning loop |

The priority order is: ambiguity clarification first, then knowledge Q&A, then open-ended agent. This means the system prefers stable, explainable answers over agentic exploration unless forced by the question type. Within knowledge Q&A, if the question is structural ("what is in section 3.2"), the system routes to a Neo4j graph query rather than the vector + keyword retrieval path.

Pre-Orchestrator: Five Steps Before Any Retrieval

Before retrieval begins, a pre-orchestrator processes the user message through five steps. The first is routing judgment: classifying whether the question belongs to knowledge Q&A, open-ended agent, or ambiguity clarification.

The second is question rewriting. A follow-up question like "how does it handle that?" carries an implicit reference that retrieval cannot resolve. The pre-orchestrator reconstructs the full question using recent conversation history.

The third is sub-question splitting. A compound question such as "what is the refund policy and how does the approval flow work?" gets split into independent sub-questions, each processed through its own retrieval path. The README states a maximum of 4 sub-questions per turn to prevent over-fragmentation.

The fourth step is intent analysis and domain narrowing, which maps each sub-question to a knowledge domain and shrinks the retrieval scope from the full corpus to the relevant domain. The fifth step is ambiguity detection: if the question lacks enough information, the system generates a clarification prompt rather than proceeding to retrieval.

Dual-Channel Hybrid Retrieval and Evidence Budget Control

Retrieval in Nexus Agent runs two channels in parallel: vector search and keyword search. The README explains the reason directly: keyword search handles exact matches (order numbers, configuration key names) that semantic similarity cannot reliably surface, while vector search handles paraphrase and terminology variation.

The two channels produce scores on incompatible scales. Nexus Agent uses RRF (Reciprocal Rank Fusion) to merge results by rank rather than by raw score, avoiding the scale mismatch. Both channels apply minimum thresholds; results below the threshold are filtered before fusion. An optional external reranker can further refine the merged candidate set.

Retrieval granularity uses a parent-child block design. Small child blocks are retrieved for precision; at generation time, each matched child block is expanded to its parent block for context completeness.

Evidence budget control enforces per-sub-question character limits and a total character budget across all evidence. If no evidence passes the threshold, the system short-circuits to a fixed response telling the user that no relevant evidence was found. The README identifies this as the most direct way to prevent model hallucination: when there is nothing to cite, say so rather than generating from nothing.

ReAct Agent Execution and Loop Guards

Open-ended questions that need live information or multi-step reasoning go to the ReAct agent executor, which implements a reasoning loop with Tavily search integration. The README documents the specific guards on this loop: a ModelCallLimitHook limits model invocations to 8 per run, with a per-session ceiling of 40. A ToolCallLimitHook limits Tavily search calls to 6 per run, with a per-session ceiling of 30.

Tool call failures use exponential backoff via a ToolRetryInterceptor: maximum 2 retries, initial delay 200ms, maximum delay 1200ms, with random jitter. If retries are exhausted, a ToolErrorInterceptor catches the failure and provides a fallback response rather than surfacing an exception to the user.

The agent state is persisted using MysqlSaver, which stores ReAct agent checkpoints in MySQL. This means an application restart can resume a prior conversation rather than losing the agent state. The README also notes that parallel tool execution is configured with a maximum of 4 concurrent tool calls.

Document Pipeline: From Upload to Indexed

Documents enter the system through a pipeline that covers multi-format parsing (using Apache Tika), chunking, embedding, and dual-engine index construction. The chunking engine is composite: structural chunking handles document hierarchy, recursive chunking serves as fallback, semantic chunking optimizes boundaries, and LLM-based chunking handles difficult documents.

The document structure is also represented as a Neo4j graph with a Document, Section, and Item hierarchy. This graph enables structural navigation queries that are separate from the vector and keyword retrieval paths.

Knowledge routing uses a three-level funnel: Scope, then Topic, then Document. User questions are mapped through these levels to narrow the search space before retrieval begins. A shadow routing feature runs the system's routing recommendation silently in the background when a user manually selects a document, comparing the system's suggestion against the user's choice to accumulate quality data for routing improvements.

Infrastructure Requirements and Licensing

Nexus Agent is released under the Apache-2.0 license. This permits commercial use, modification, and distribution without requiring derivative works to be open-sourced, provided the license and copyright notice are retained.

The infrastructure layer requires MySQL, PGVector, Elasticsearch, Neo4j, Redis, Kafka, MinIO, and Apache Tika. This is a substantial dependency set. The README does not include a Docker Compose file or a minimal-deployment path; the prerequisites guide at javaup.chat/super-agent/getting-started/prerequisites is described as the starting point for local setup.

The project is written in Java and follows a monorepo layout: nexus-agent-business, nexus-agent-common, nexus-agent-id-generator-framework, nexus-agent-redis-tool-framework, nexus-agent-redisson-framework, and a vue directory for the frontend. There are also SQL scripts for schema initialization. The last push was on 2026-09-16, and the repository has no GitHub releases, meaning there is no versioned artifact to download from the releases page.

Editorial conclusion

Nexus Agent targets Java teams building production AI applications who want a reference implementation that goes well beyond a tutorial demo. The architecture is intentionally opinionated: a three-tier executor, a five-step pre-orchestrator, hybrid dual-channel retrieval, and an evidence budget system. Engineers who want to understand the design before running it should read the official documentation at javaup.chat, which the README points to as the primary resource. Teams whose stack is Python-first, or who need a lightweight prototype, will find the infrastructure requirements (MySQL, PGVector, Elasticsearch, Neo4j, Redis, Kafka, MinIO) heavier than they want. Check the prerequisites guide at javaup.chat/super-agent/getting-started/prerequisites before starting a local deployment.

Frequently asked questions

Official sources

1. Issues
2. java-up-up/nexus-agent on GitHub
3. License: Apache-2.0
4. Project website
5. README