Nexus Agent: A Java Agent Platform Where Routing Decisions Precede Model Calls

The Problem Nexus Agent Targets: Routing, Not Model Choice

The README makes an argument rather than a feature claim. Most tutorials, it says, call an embedding endpoint, push vectors into a store, and generate an answer. That is a demo. The gap between a demo and something operable is not code volume but decisions about chunking, recall, fusion ranking and hallucination control. Nexus Agent is positioned as a worked answer to those decisions in Java, aimed at developers who need a knowledge assistant that cites evidence instead of improvising.

The concrete problem it solves is routing. A user types one sentence. The system must decide whether to ask a clarifying question, run a retrieval-backed question-answer flow, or hand the turn to an open-ended agent with web search and tool calls. The README states the order explicitly: ambiguity clarification takes priority, then knowledge Q&A, then the open-ended agent. That ordering is the design thesis. Knowledge Q&A is described as pursuing stability and explainability, and letting an agent explore freely is described as less controllable. Only questions that genuinely need web search or multi-step reasoning get the agent path.

Who is this for? Java teams already inside the Spring ecosystem who want an agent stack they can read as source rather than as a framework abstraction. The README's own framing, that frameworks do not provide these capabilities and this project implements them, tells you the intended reader is someone willing to own the retrieval pipeline. It is not aimed at teams who want to add an agent in an afternoon.

Three-Tier Executors and the Pre-Retrieval Orchestration Chain

The architecture separates orchestration from execution. A pre-retrieval orchestrator runs before any model answer is generated: routing judgement, question rewriting, sub-question decomposition, knowledge domain narrowing, and ambiguity clarification. The README calls this the RAG front orchestration engine, and the point is that the retrieval plan is built before generation starts. Based on the repository description, this is a five-step decision chain.

Execution then lands in one of three tiers. The README does not name the three executors individually in the supplied text, but it does describe their behaviour: a deterministic orchestration path, an ambiguity-clarification path, and a knowledge Q&A path, with the open-ended ReAct agent sitting behind them. The ReAct agent itself is a full implementation with web search, tool calling, multi-step reasoning and Checkpoint persistence.

The guardrails are the part worth reading closely. ModelCallLimitHook caps model calls at 8 per run, with a cumulative cap of 40 per conversation thread. ToolCallLimitHook caps Tavily searches at 6 per run and 30 per thread. ToolRetryInterceptor retries with exponential backoff, at most 2 retries, initial delay 200ms, maximum delay 1200ms, with jitter. ToolErrorInterceptor catches the terminal failure so the exception does not surface to the user. ReactAgent is configured with parallelToolExecution at a maximum of 4 concurrent tools. Those numbers are specific, which is unusual for a README, and they are the clearest signal that this code has been run against something that loops.

Checkpoint persistence uses Spring AI Alibaba's MysqlSaver, writing ReactAgent checkpoints to MySQL so a restart does not discard the conversation.

Dual-Channel Retrieval, RRF Fusion and the Evidence Budget

Retrieval runs two channels in parallel: vector search and keyword search. Results are fused with Reciprocal Rank Fusion, and an external reranker is optional for a final precision pass. The README frames this as balancing recall and precision rather than choosing between them. The keyword channel is backed by an inverted index; the vector channel by a vector database. Both are listed in the infrastructure set.

Chunking is where the design gets more opinionated. The engine is compositional: structural chunking as the trunk, recursive splitting as a fallback, semantic chunking to refine boundaries, and LLM-driven chunking for documents the other three handle badly. Retrieval then uses Child chunks for hit rate and aggregates to Parent chunks at answer time for context completeness. This Parent-Child split is a standard mitigation for the tension between small chunks that match well and large chunks that read well, and the README presents it as such.

Two controls sit on top. Evidence budget control trims evidence when there are multiple sub-questions, so the prompt does not grow unbounded. The no-evidence short circuit is the more interesting one: when retrieval finds nothing relevant, the system tells the user directly instead of letting the model improvise. That is a deliberate product decision, and it means some questions will get a refusal where a general-purpose chatbot would have produced a plausible-sounding answer.

Above retrieval sits a three-level knowledge routing funnel: Scope, then Topic, then Document. Each user question is ranked through that funnel to lock the relevant knowledge range before retrieval begins. Neo4j holds a document structure graph built at index time, with Document to Section to Item levels, supporting section location, adjacency traversal and structured navigation. The README also describes shadow routing: when a user manually selects a document, the system runs knowledge routing silently in the background and compares the system recommendation against the user's actual choice, to evaluate routing quality over time. That is a measurement mechanism, not a feature users see.

Getting It Running: Multi-Module Maven, Java 25 and the Middleware Set

The README's quick-start link points to a prerequisites page rather than inlining setup steps, and the supplied material does not include the actual startup commands, so I cannot give you a verified command sequence. What the repository does establish is the shape of the build: a multi-module Maven project, Java 25 or later, with a Vue 3 front end. The front end covers session execution and an operations console; the interface and streaming layer handles requests, SSE, authentication and interrupt control.

The infrastructure list is the real setup cost. MySQL, PostgreSQL with pgvector, Elasticsearch, Neo4j, Redis, Kafka, MinIO and Tika all appear in the architecture description. Reading that list against the features explains each entry: MySQL for checkpoints and application data, pgvector for the vector channel, Elasticsearch for the inverted index, Neo4j for the document structure graph, Redis and Kafka for the caching and messaging layers, MinIO for object storage, Tika for multi-format document parsing. Each is load-bearing for some capability, which means you cannot trim the list without losing a feature.

Two configuration surfaces are named in the README. The hook limits (8 model calls per run, 40 per thread, 6 Tavily calls per run, 30 per thread) and the retry parameters (2 retries, 200ms initial delay, 1200ms maximum, jitter) are described as values, not as config keys, so I cannot confirm from the supplied text whether they are externalized. The Skills system uses SKILL.md files, declarative, directory-organized, with automatic loading and references to scripts and supporting material. The MCP integration is described as dynamic tool discovery rather than hardcoded function calls. Streaming uses SSE: body fragments pushed in real time, with citations and recommended follow-up questions appended at the end, plus support for actively stopping generation.

If you are evaluating this, the prerequisites page is the first thing to read, not the feature list. The middleware count is the adoption decision.

Where Nexus Agent Is the Wrong Tool

The infrastructure footprint is the first limitation, and it is not incidental. A team that wants one process and an embedded vector store will find this project's dependency set disqualifying. The dual-channel retrieval design requires both a vector engine and an inverted index; the graph navigation requires Neo4j. Removing any of them removes the capability that justified including it.

The three-tier executor design carries a second cost. Because routing happens before execution, every question pays for routing judgement, rewriting, sub-question decomposition and domain narrowing before a single token of answer is generated. For a simple factual question against a small corpus, that is overhead. The README's own justification, that knowledge Q&A needs stability and explainability, is a trade of latency and pipeline complexity for predictability. If your use case is conversational and open-ended, the deterministic path is friction rather than safety.

The no-evidence short circuit is a genuine failure mode as well as a feature. When retrieval returns nothing, the user gets told so. If your corpus is thin, poorly parsed, or full of scanned documents that Tika handles badly, users will hit that path often, and the system will look less capable than a plain chatbot that answers from parametric memory. That is the correct behaviour for a compliance-flavoured assistant and the wrong behaviour for a brainstorming tool.

Finally, the material describes the system at a level of design detail that suggests a substantial codebase. The README lists no releases, so there is no versioned artifact to pin. You are tracking the master branch. For a platform with this many moving parts, that matters.

Compared With Assembling Spring AI Yourself

The honest alternative is not another agent framework. It is Spring AI plus Spring AI Alibaba, which this project already builds on, plus your own retrieval pipeline. Nexus Agent uses MysqlSaver from Spring AI Alibaba for checkpoints, so the underlying framework is doing real work here. Choosing between the two is choosing whether to write the orchestration layer yourself.

The difference in approach is where the decisions live. With raw Spring AI, you wire a chat client, a vector store and a tool-calling loop, and the routing logic is whatever you write. With Nexus Agent, the routing logic is already written and opinionated: ambiguity before knowledge Q&A before agent, three-level knowledge funnel, RRF fusion of two channels, Parent-Child aggregation, evidence budget trimming, no-evidence short circuit. If your product needs a different ordering, say agent-first with retrieval as a tool, you are fighting the design rather than extending it.

A second alternative is a Python agent stack with a hosted retrieval service. That gets you a smaller operational surface at the cost of running two languages if your application tier is Java, and it moves retrieval tuning out of your repository. The README's argument, that the competitive difference is engineering rather than model choice, cuts against outsourcing retrieval. Whether that argument holds for your team depends on whether you intend to tune chunking and fusion at all.

What Nexus Agent offers that neither alternative gives you out of the box is the measurement loop: shadow routing compares system recommendations against user document selections, and the README also mentions an evaluation harness with quality tracing. That is the part most homegrown pipelines never build.

Licence, Maintenance and What to Verify Before Adopting

The project is Apache-2.0, which permits commercial use and modification with the usual notice and patent terms. I am not giving legal advice; read the LICENSE file in the repository and have counsel review it if you are embedding this in a product. The practical implication of Apache-2.0 here is that you can fork and modify the orchestration chain without a copyleft obligation on your own code, which matters because the routing order is exactly the thing a product team is most likely to want to change.

On maintenance, the material supports only a limited read. The repository is not archived, the default branch is master, and the last push is dated 2026-08-19. No releases were retrieved, so there is no tagged version to depend on. That means upgrades are branch pulls, and you should expect to resolve conflicts in the modules you have modified. The README asks for a star, which tells you the maintainer is seeking visibility, but I have no user counts, no contributor data and no release cadence to reason about, and I will not guess at them.

The Skills system is the extension point with the lowest upgrade cost: SKILL.md files are declarative and directory-organized, so custom skills should survive core changes better than patches to the executor chain. If you plan to extend this project, extend it there first.

What to verify before you commit, concretely. First, whether the hook limits are configurable: the README states 8 and 40 for model calls and 6 and 30 for Tavily, but if those are constants in code rather than properties, tuning them means forking. Second, whether the Skills loader reads from a directory you control or a classpath location, since that determines whether skills can be updated without a redeploy. Third, whether the SSE stop-generation control is exposed on the endpoint you will integrate with, because streaming protocols that support interruption in the UI but not in the API force client-side workarounds. Read the prerequisites page and the core architecture page on the docs site against the repository before you provision the middleware, because the middleware list is the commitment.

Editorial conclusion

Adopt Nexus Agent if you are building a Java-side knowledge assistant where answer traceability matters more than open-ended exploration, and you already operate MySQL, PostgreSQL with pgvector, Elasticsearch, Neo4j, Redis, Kafka and MinIO. Do not adopt it if you want a single-binary agent or cannot run that middleware set, because the retrieval path depends on two engines and the graph navigation path depends on Neo4j. Before committing, verify three things against the repository and the docs site: whether the documented ModelCallLimitHook and ToolCallLimitHook values (8 and 40 for models, 6 and 30 for Tavily) are configurable or hardcoded, whether the Skills loader resolves SKILL.md from a directory you control, and whether the SSE endpoint exposes the stop-generation control the README describes. If those three check out, the routing design is the reason to pick this over assembling Spring AI yourself.

Official sources

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