DEV Community: Solon Framework

Rerun and Continue in SolonCode Web — Two Buttons, Two Semantics

Solon Framework — Mon, 24 Aug 2026 07:38:50 +0000

When you're chatting with an AI agent, two things go wrong most often: the model produced an answer you don't want, or the model stopped too early and you'd like it to keep going.

SolonCode's Web UI solves both problems with two small icons — Re-run and Continue — that sit next to every AI response bubble. They look alike (same toolbar, same spot) but do very different things under the hood.

This article walks through what each button does, what the code does when you click it, and when you should use one versus the other.

The two buttons at a glance

Every AI response row in SolonCode Web shows four action icons to its right:

Copy — copies the final answer to the clipboard
Re-run (循环箭头) — replays the last user message from scratch
Continue (快进) — extends the last AI response without deleting anything
Delete — removes the response and everything after it

The Re-run and Continue buttons are the focus here. Both send a command to the engine (/rerun and /continue), but the effect on the conversation is fundamentally different.

Re-run (重新运行): replay the turn, delete the old answer

What you see

You type "Refactor OrderRepository to use Solon Data" and the agent returns a response with code changes. You open the result and decide the approach is wrong — maybe it touched too many files, or used the wrong pattern. You click the Re-run icon on that AI response.

The old AI bubble vanishes. A new one appears in its place, and the agent starts thinking again.

What the code does

The RerunCommand (org.noear.solon.codecli.command.builtin.RerunCommand) implements the command:

Walk backwards through the session message list until it finds a UserMessage.
Strip that user message and everything after it from the session (session.removeLatestMessage(1) in a loop).
Call ctx.runAgentTask(lastUserInput, null) — the same input, a clean slate.

// RerunCommand.java (simplified)
List<ChatMessage> messageList = session.getMessages();
String lastUserInput = null;

while (!messageList.isEmpty()) {
    ChatMessage msg = messageList.get(messageList.size() - 1);
    if (msg instanceof UserMessage) {
        lastUserInput = msg.getContent();
        session.removeLatestMessage(1);
        break;
    }
    session.removeLatestMessage(1);  // strip AI messages too
}

ctx.runAgentTask(lastUserInput, null);

The Web UI mirrors this by removing every DOM element with the same data-run-id — the AI bubble, any tool cards, thinking blocks, everything from that turn — so the new response renders in a clean bubble.

When to use Re-run

The agent's last answer is wrong and you want to try again with the same prompt
The agent took a wrong turn mid-response and you want it to pick a different path
You want to test whether a different model or a different system prompt would give a better result on the same input

Key property: Re-run preserves your conversation history up to the last user message, then replays that message. Everything after the user message is discarded.

Continue (继续运行): extend the response, keep what's there

What you see

The agent responded with a partial refactor — it changed OrderRepository but stopped mid-way through PaymentService. You click Continue and the same bubble stays; new content simply flows into it, like the agent kept typing.

What the code does

ContinueCommand (org.noear.solon.codecli.command.builtin.ContinueCommand) takes a different approach. Instead of discarding the last turn, it manipulates the agent's internal execution trace:

Look up the ReActTrace stored in the session context under "__main".
If the trace's current route is Agent.ID_END (meaning the agent has already reached its final answer node), reset the route back to ReActAgent.ID_REASON — putting the agent back in "thinking" mode.
Clear the final answer from the trace (trace.setFinalAnswer(null, false)).
Remove the last assistant message from working memory and from the session (so it will be regenerated).
Call ctx.runAgentTask(null, null) — the agent picks up from where it left off.

// ContinueCommand.java (simplified)
ReActTrace trace = session.getContext().getAs("__main");
if (trace != null) {
    if (Agent.ID_END.equals(trace.getRoute())) {
        trace.setRoute(ReActAgent.ID_REASON);       // go back to thinking
        trace.setFinalAnswer(null, false);           // clear the old answer

        ChatMessage workMessage = trace.getWorkingMemory().getLastMessage();
        if (workMessage instanceof AssistantMessage) {
            trace.getWorkingMemory().removeLastMessage();
        }

        List<ChatMessage> messageList = session.getMessages();
        if (Assert.isNotEmpty(messageList)
                && messageList.get(messageList.size() - 1) instanceof AssistantMessage) {
            session.removeLatestMessage(1);         // remove the completed reply
        }
    }
}

ctx.runAgentTask(null, null);  // continue from current state

Because the trace is reset to the reasoning step, the agent doesn't start a new conversation — it continues the same reasoning chain, appending to the existing response.

On the Web UI side, the Continue button sends /continue with removeRow=false, so the existing bubble stays visible and new content simply appends to it.

When to use Continue

The agent stopped mid-task (e.g., refactored 3 of 12 files) and you want it to keep going
The agent's last answer was mostly right but incomplete
You want the response to feel like a natural extension, not a re-do

Key property: Continue does not discard anything. It preserves the conversation history and the agent's reasoning state, then asks the agent to pick up where it stopped.

Side-by-side comparison

	Re-run	Continue
Command	`/rerun`	`/continue`
Deletes old response?	Yes — removes the entire run	No — appends to the same bubble
Strips history?	Yes — removes everything after the last user message	No — preserves all history
Resets agent state?	Yes — starts fresh with the same prompt	Partially — resets trace to reasoning step, keeps context
Preserves tools/skills?	Yes — same session, same tools	Yes — same session, same tools
Best for	"That answer was wrong, try again"	"That answer was incomplete, keep going"
Web UI icon	Loop arrow (循环箭头)	Fast-forward (快进)
i18n key	`msg.rerun`	`msg.continue`
Chinese label	重新运行	继续运行

A concrete example

Imagine you ask SolonCode: "Migrate the UserService from Spring Data JPA to Solon Data."

Scenario A — the agent got the migration wrong

The agent produced a response that uses the wrong Solon Data API. You click Re-run. The old response disappears, the agent thinks again, and this time produces a correct migration. Your history now has the corrected response in place of the old one.

Scenario B — the agent stopped halfway

The agent migrated findUserById but stopped before findByEmail. You click Continue. The same bubble stays, and the agent keeps typing — now adding findByEmail to the response. Nothing is deleted.

Scenario C — the agent hallucinated a dependency

The agent's response included a @Component on a class that shouldn't have one. You click Re-run. The agent re-thinks and this time produces a cleaner response. Then you realize the response is still missing deleteById, so you click Continue to add it.

How the commands are exposed

Both /rerun and /continue are registered as built-in commands (since v2026.4.28):

CLI: type /rerun or /continue directly in the terminal
Web UI: click the icon on any AI response bubble
IM channels (飞书/钉钉/微信): send /rerun or /continue in chat — the IM bot forwards the same command to the engine

In the Web UI, RerunCommand and ContinueCommand are not marked cliOnly(), so they appear in the /web/chat/hints endpoint and are available from any channel.

Under the hood: the runId linkage

One detail worth understanding is how the Web UI knows which elements belong to a single "run."

Every message element — the AI bubble, tool cards, thinking blocks — is stamped with data-run-id (the same ID assigned to the current ReActTrace). When you click Re-run, the UI removes all elements with that runId from the DOM before the new response arrives. This is why the entire turn vanishes atomically, not just the text bubble.

Continue doesn't touch the DOM at all — it just sends the command and lets the stream append to the existing bubble.

Summary

Re-run and Continue are two sides of the same coin: Re-run is about correctness (throw away a bad answer and try again), while Continue is about completeness (keep a partial answer and finish it).

Both operate at the session level — they don't create new sessions, they don't change tools or models, and they don't affect other conversations. The only difference is whether the old response gets discarded (rerun) or preserved (continue).

Next time you're chatting with SolonCode and the agent's answer isn't quite right, reach for the icon that matches your intent:

Wrong? → Re-run
Incomplete? → Continue

Both are available in the Web UI, CLI, and IM channels — pick the one that fits your workflow.

SolonCode is an open-source coding agent built on Solon AI and Java. It supports CLI, Web, Desktop, and ACP interaction modes. Open source under Apache 2.0 / MIT.

Spring AI vs Solon AI - Building Agents and Handling Agent Events

Solon Framework — Thu, 20 Aug 2026 16:14:09 +0000

Both Spring AI and Solon AI can build tool-calling, multi-step agents in Java. But once your agent grows beyond a single chat call — you want step-by-step streaming, per-tool tracing, run metrics, or human-in-the-loop suspension — the two frameworks diverge sharply in how you assemble the agent and how you observe its execution.

This article compares the two side by side: agent construction first, then the event/observability models, with runnable examples for each. Everything below is checked against the official docs (Spring AI reference) and the Solon AI v4.0.5 source code.

Part 1: Building Agents

Spring AI: The Agent Is a Pattern, Not a Type

Spring AI has no Agent class. An "agent" is a composition: a ChatClient with advisors, plus tools, plus (optionally) memory. The tool-calling loop is run by the framework through the always-auto-registered ToolCallingAdvisor, which delegates execution to ToolCallingManager and loops until the model stops requesting tools.

ChatClient client = ChatClient.builder(chatModel)
        .defaultSystem("You are a helpful weather assistant.")
        .defaultTools(new WeatherTools())          // @Tool-annotated methods
        .defaultAdvisors(
                MessageChatMemoryAdvisor.builder(chatMemory).build())
        .build();

String answer = client.prompt()
        .user("What's the weather in Hangzhou? Should I bring an umbrella?")
        .call()
        .content();

Spring AI also documents three tool-execution modes:

Framework-controlled — the default above; you never see the loop.
Advisor-controlled — you configure ToolCallingAdvisor explicitly to customize the loop's stop condition.
User-controlled — you disable the auto-registered advisor (AdvisorParams.toolCallingAdvisorAutoRegister(false)) and drive the loop yourself, aggregating streamed chunks with ChatClientMessageAggregator.

For multi-agent orchestration, Spring AI's documented pattern is composition: one ChatClient can be exposed as a ToolCallback for another, so a "planner" agent literally calls a "worker" agent as a tool.

// A worker agent exposed as a tool (documented pattern)
ToolCallback researcherTool = FunctionToolCallback
        .builder("researcher", query -> researcherClient.prompt()
                .user(query)
                .call()
                .content())
        .description("Ask the researcher sub-agent")
        .inputType(String.class)
        .build();

The strength here is familiarity: if you know ChatClient + advisors, you already know how to build agents. The weakness is that there is no first-class object representing "an agent run" — no run ID, no run-scoped trace, no built-in notion of an agent's lifecycle.

Solon AI: Agents Are First-Class Citizens

Solon AI ships an actual agent layer in solon-ai-agent. The root interface Agent declares name(), role(), profile(), and the request builders prompt(...). Out of the box you get three levels:

ReActAgent — a single agent running a think → act → observe loop with tools.
TeamAgent — a coordinator that plans and delegates to multiple member agents.
Ai Flow — YAML-declared workflows where agents are nodes.

Building a ReAct agent is a builder chain over the same portable ChatModel:

public class WeatherTools extends AbsToolProvider {
    @ToolMapping(description = "Get current weather for a city")
    public String getWeather(@Param(description = "City name") String city) {
        return weatherService.lookup(city);
    }
}

ChatModel chatModel = ChatModel.of(apiUrl)
        .apiKey(apiKey).model("gpt-4o")
        .build();

ReActAgent agent = ReActAgent.of(chatModel)
        .name("weather_helper")
        .role("Answers weather questions and gives clothing advice")
        .modelOptions(o -> o.temperature(0.1F))   // low temp for consistent reasoning
        .defaultToolAdd(new WeatherTools())
        .maxTurns(10)                  // hard cap on the reasoning loop
        .outputSchema(WeatherAdvice.class)  // structured final answer
        .build();

AgentSession session = InMemoryAgentSession.of("session-001");
String answer = agent.prompt("What's the weather in Hangzhou?")
        .session(session)
        .call()
        .getContent();

Three things are worth noticing versus Spring AI:

The loop has a budget — maxTurns, retryConfig(maxRetries, retryDelayMs), and autoRethink are builder-level controls on the reasoning loop itself, not something you wire by hand.
The session is the agent's memory — AgentSession carries the working memory and execution snapshot; it can be serialized to JSON (FlowContext.toJson() / fromJson()) and restored, which also powers human-in-the-loop: session.pending(true, "waiting for approval") suspends mid-run, and agent.prompt() (no argument) resumes it later.
Async and streaming are symmetric — every agent request supports .call(), .callAsync() (CompletableFuture), and .stream().

A TeamAgent reuses the same builder shape, and notably can work without its own model — TeamAgent.of(null) builds a deterministic coordinator driven purely by code:

TeamAgent team = TeamAgent.of(chatModel)
        .name("support_team")
        .defaultInterceptorAdd(new AuditInterceptor())
        .build();

Part 2: Events and Observability

This is where the architectural difference is deepest.

Spring AI: Observability via Micrometer, Not an Event Stream

Spring AI's answer to "what happened inside my agent run" is the Micrometer Observation API. ChatClient calls and tool executions automatically record observations (spring.ai.chat.client, spring.ai.tool) with GenAI-convention key-values:

gen_ai.operation.name (execute_tool for tools)
spring.ai.tool.definition.name, spring.ai.tool.call.id
tool call arguments and results are not exported by default (sensitive data); opt in with spring.ai.tools.observations.include-content=true

These feed tracing backends (Zipkin, Tempo, ...) via standard Spring Boot actuator configuration. It is production-grade telemetry — but it is metrics and spans, not events you can program against. There is no RunStarted callback, no per-tool-call hook you can implement to mutate behavior, and no run object carrying token usage you can read in-process after a run.

For streaming, you get Flux<ChatResponse> content chunks; and if you drive the tool loop yourself, ChatClientMessageAggregator lets you tap each iteration's chunk flux — but the lifecycle of "a tool was selected → executed → returned" surfaces only through observation spans.

Solon AI: A Typed Event Stream Plus Lifecycle Interceptors

Solon AI treats the agent run as a stream of typed events. AgentRequest.stream() returns Flux<AgentEvent>, and every event carries getRunId(), getAgentName(), the AgentSession, and a metadata map:

agent.prompt("What's the weather in Hangzhou?")
        .session(session)
        .stream()
        .doOnNext(event -> {
            if (event instanceof RunStartEvent e) {
                log.info("run {} started on agent {}", e.getRunId(), e.getAgentName());
            } else if (event.hasContent()) {
                // incremental token stream for the UI
                uiSink.emit(e.getContent());
            } else if (event instanceof RunEndEvent e) {
                Metrics m = e.getMetrics();
                log.info("run finished: abnormal={}, tokens={}, duration={}ms",
                        e.isAbnormal(), m.getTotalTokens(), m.getTotalDuration());
            }
        })
        .subscribe();

The event vocabulary is small and structural:

Event	Meaning
`RunStartEvent`	an agent run begins (carries `ReActTrace`)
content events (`hasContent()`)	streaming answer chunks
`RunEndEvent`	run finished — carries the final `ReActResponse`, the trace, and `Metrics` (prompt/completion/total tokens, cache tokens, total duration, `isAbnormal()`)
`TeamStartEvent` / `NodeStartEvent` / `NodeChunk` / `NodeEndEvent` / `TeamEndEvent`	team-level granularity: which member agent started, streamed, finished

Because events are typed objects on a Reactor flux, wiring them to SSE, WebSockets, or an audit log is trivial — no observation registry required.

Complementing the event stream is the interceptor chain. ReActInterceptor gives you synchronous hooks into every phase of the loop, registered per agent:

public class AuditInterceptor implements ReActInterceptor {
    @Override
    public void onReasonStart(ReActTrace trace, StringBuilder systemPromptBuf) {
        trace.getRunId(); // correlate with the event stream
    }

    @Override
    public void onToolCallStart(ReActTrace trace, ToolExchanger toolExchanger) {
        log.info("calling tool: {}", toolExchanger.getToolName());
    }

    @Override
    public void onToolCallEnd(ReActTrace trace, ToolExchanger toolExchanger,
                              ChatMessage message, Throwable error, long durationMs) {
        log.info("tool {} done in {}ms, error={}",
                toolExchanger.getToolName(), durationMs, error);
    }

    @Override
    public void onObservation(ReActTrace trace, ToolExchanger toolExchanger,
                              @Nullable ChatMessage observation,
                              @Nullable Throwable error, long durationMs) {
        // the observation that will be fed back to the model
    }
}

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(new WeatherTools())
        .defaultInterceptorAdd(new AuditInterceptor())
        .build();

The full hook surface: onAgentStart, onReasonStart / onReasonEnd, onPlan, onActionStart / onActionEnd, onToolCallStart / onToolCallEnd, onAgentEnd — plus onThought / onAction / onObservation mirroring the classic ReAct vocabulary. Since ReActInterceptor extends both AgentInterceptor and ChatInterceptor, one object can observe agent-level and raw-model-level traffic simultaneously.

And unlike observation spans, these hooks can do things: mutate the system prompt buffer at onReasonStart, redact tool results, enforce budgets, or suspend the run.

The Philosophical Difference in One Table

Aspect	Spring AI	Solon AI
Agent abstraction	none — `ChatClient` + advisors pattern	`Agent` / `ReActAgent` / `TeamAgent` types
Tool loop owner	`ToolCallingAdvisor` (framework, advisor, or user-controlled)	`ReActAgent` loop with `maxTurns` / `retryConfig`
Multi-agent	compose clients-as-tools	built-in `TeamAgent` coordinator
Execution events	not exposed as API	typed `Flux<AgentEvent>` stream
Per-tool hooks	via Micrometer spans	`ReActInterceptor` lifecycle callbacks
Token/cost per run	from observation metrics export	`Metrics` on `RunEndEvent`, in-process
Mid-run suspension	DIY	`session.pending()` + resume
Telemetry backend	Micrometer / OTel, first-class	read events/trace in code; bridge to whatever you like

Which One Fits?

These models are not enemies — they answer different pressures:

If your agents live inside a Spring estate and your observability story is already Micrometer/tracing-based, Spring AI's pattern-based approach slots in with zero new concepts, and spans flow to your existing dashboards.
If you are building agent-centric products — dashboards that render reasoning steps, billing driven by per-run token metrics, HITL approval flows, SSE streams of typed events — Solon AI's first-class run/event/interceptor model gives you that without wrapping observation infrastructure in application code.

A pragmatic hybrid also works well and is worth stating plainly: Spring Boot as the shell (web, security, actuator) with Solon AI's agent kernel inside it — Solon AI is framework-neutral, so ReActAgent runs happily as a plain bean.

Spring AI vs Solon AI - A Practical Comparison for Java Developers

Solon Framework — Thu, 20 Aug 2026 15:29:18 +0000

If you build AI-powered applications on the JVM today, you will meet two frameworks quickly: Spring AI, the official AI layer of the vast Spring ecosystem, and Solon AI, the AI stack of the Solon project that also embeds into any Java framework — including Spring Boot itself.

They solve the same problem — connect your Java code to LLMs, tools, RAG pipelines, and agents without locking yourself to one vendor — but they approach it with very different philosophies. This article compares them feature by feature, with side-by-side code for every major capability. All Solon AI snippets below were verified against the solon-ai source (v4.x), and the Spring AI snippets follow the current Spring AI 1.0.x reference documentation.

What They Share

The overlap is larger than the marketing suggests. Both frameworks offer:

A portable chat model abstraction — one interface, many providers (OpenAI, Anthropic, Google Gemini, Ollama, Azure, DeepSeek, DashScope, ...). Write once, swap the backend by configuration.
Tool calling via annotated Java methods (@Tool in Spring AI, @ToolMapping in Solon AI), with the framework managing the request/execute/return loop.
Structured output — map model responses directly onto Java POJOs.
A full RAG chain — document loaders, splitters, embedding models, vector store adapters (PGVector, Redis, Milvus, Qdrant, Chroma, ...), and metadata filtering.
Chat memory / conversation persistence, with pluggable stores.
MCP (Model Context Protocol) on both sides: consume external MCP servers and expose your own services as MCP servers.
Sync and streaming responses, plus GraalVM native image support.

Both are Apache 2.0 licensed and production-oriented. The interesting part is where they diverge.

Difference #1: The Ecosystem Contract

This is the deepest difference.

Spring AI is an AI abstraction layer for the Spring ecosystem. Its idioms are Spring idioms: Boot starters, auto-configuration, dependency injection, Micrometer observability. It requires Java 17+ (the upcoming 2.0 line targets Java 21+), and in practice it lives inside a Spring Boot application.

Solon AI is framework-neutral. It runs standalone on plain JDK 8 through 26, and it can be embedded into Spring Boot, Quarkus, Vert.x, or jFinal as just another library. If you have a legacy Java 8 service in a bank and want to add LLM features, this distinction decides the question by itself.

Difference #2: API Style — Advisor Chain vs. Builder + Agent

Spring AI's high-level API is ChatClient, a fluent builder in the spirit of WebClient. Cross-cutting behaviors — memory, RAG, tool execution — are composed as an Advisor chain:

ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(
                MessageChatMemoryAdvisor.builder(chatMemory).build(), // memory
                QuestionAnswerAdvisor.builder(vectorStore).build()    // RAG
        )
        .build();

String answer = chatClient.prompt()
        .user("What is our refund policy for enterprise contracts?")
        .call()
        .content();

Advisors are interceptors wrapping the call: they can rewrite the prompt, inject retrieved documents, and post-process the response. It is a clean, extensible pattern — but everything is a ChatClient concern.

Solon AI instead exposes a ladder of abstractions, from low to high:

ChatModel — the raw, provider-neutral model call.
ReActAgent — an agent with role, instructions, session, retries, and reflection loop.
TeamAgent — multi-agent collaboration with routing protocols.

The equivalent of the snippet above in Solon AI:

ChatModel chatModel = ChatModel.of("https://api.openai.com/v1")
        .apiKey(apiKey)
        .model("gpt-4o")
        .build();

ReActAgent supportBot = ReActAgent.of(chatModel)
        .name("SupportBot")
        .instruction("Answer using only the provided knowledge base")
        .build();

String answer = supportBot.prompt("What is our refund policy?")
        .call().getContent();

Difference #3: Tool Calling

The concepts map almost one-to-one; only the annotations and wiring differ.

Spring AI — annotate a method, register the object, and the auto-registered ToolCallingAdvisor runs the tool loop:

class WeatherTools {
    @Tool(description = "Get current weather for a city")
    String getWeather(@ToolParam(description = "City name") String city) {
        return weatherService.lookup(city);
    }
}

String answer = chatClient.prompt()
        .tools(new WeatherTools())
        .user("Weather in Hangzhou?")
        .call().content();

Solon AI — same idea with @ToolMapping and @Param:

public class WeatherTools extends AbsToolProvider {
    @ToolMapping(description = "Get current weather for a city")
    public String getWeather(@Param(description = "City name") String city) {
        return weatherService.lookup(city);
    }
}

ChatModel chatModel = ChatModel.of(apiUrl)
        .apiKey(apiKey).model("gpt-4o")
        .defaultToolAdd(new WeatherTools())
        .build();

String answer = chatModel.prompt("Weather in Hangzhou?")
        .call().getContent();

A Solon AI extra worth noting: the Talent system, where entire tool suites (terminal, mail, memory, browser automation) are mounted as swappable capability groups an agent can discover — closer to "skills" than to plain function calls.

Difference #4: Structured Output

Spring AI converts responses to POJOs at the ChatClient layer:

record ActorFilms(String actor, List<String> movies) {}

ActorFilms films = chatClient.prompt()
        .user("List 3 movies of Tom Hanks")
        .call()
        .entity(ActorFilms.class);

Solon AI puts the constraint in ChatOptions.outputSchema(...). The framework generates a JSON Schema from your POJO and injects it into the instruction in a provider-neutral <output_schema> block — it does not rely on any vendor's native JSON mode, so the same code works on OpenAI, Ollama, DashScope, or Gemini:

ReActAgent extractor = ReActAgent.of(chatModel)
        .name("ResumeExtractor")
        .outputSchema(ResumeInfo.class)   // POJO -> JSON Schema, enforced
        .outputKey("resume")
        .build();

On the response side, AssistantMessage.getJsonContent() strips markdown fences and toBean(Type) deserializes back to the same type.

Difference #5: RAG

Spring AI treats RAG as advisors. QuestionAnswerAdvisor implements naive RAG; RetrievalAugmentationAdvisor composes modular pipelines (query transformers, retrievers, post-processors) inspired by the Modular RAG paper. Filtering uses a portable SQL-like FilterExpression.

Advisor rag = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .vectorStore(vectorStore)
                .similarityThreshold(0.50)
                .build())
        .build();

Solon AI treats RAG as a repository. One abstraction covers embedding, storage, retrieval, filtering, and prompt augmentation:

// Ingest
repository.insert(Document.of(text).metadata(Map.of("department", "support")));

// Retrieve with a filter expression pushed down to the store
QueryCondition cond = QueryCondition.from("refund policy")
        .filterExpression("department == 'support'");

// Let the model drive retrieval itself (agentic RAG)
ChatModel chatModel = ChatModel.of(apiUrl)
        .defaultToolAdd(new RepositoryTool(repository, 5))
        .build();

RepositoryTool turns the repository into a tool, so the model decides when and what to search — agentic RAG out of the box. Spring AI can achieve similar behavior by combining tools with a vector store, but you assemble it yourself.

Difference #6: Memory

Spring AI: ChatMemory stores per-conversation messages (in-memory, JDBC, Cassandra...), surfaced through MessageChatMemoryAdvisor. Each call must supply ChatMemory.CONVERSATION_ID.

Solon AI: ChatSession is the message ledger with windowed retrieval (getLatestMessages(windowSize)), while AgentSession additionally persists workflow state — including pending human-in-the-loop checkpoints — with File and Redis backends. The session abstraction covers both chat history and long-running agent execution state in one object.

Difference #7: Agents and Orchestration

This is where the frameworks diverge most in ambition.

Spring AI's agent story is compositional: advisors + tools + (in recent versions) recursive advisors for self-reflection. Deep agentic workflows in the Spring world often pull in additional projects, e.g. Spring AI Alibaba's graph engine.

Solon AI ships agent primitives natively: ReActAgent with reflection and retries, TeamAgent with built-in collaboration protocols, dynamic skill admission, and Ai Flow — YAML-based flow orchestration for a low-code, Dify-like experience. If your application is an agent system, Solon AI gives you the vocabulary for it without extra dependencies.

Difference #8: MCP

Both fully support MCP:

Spring AI: dedicated Boot starters (spring-ai-starter-mcp-client, etc.), annotation model (@McpTool, @McpResource, @McpPrompt), sync/async client and server, Stdio/SSE/Streamable-HTTP transports.
Solon AI: @McpServerEndpoint + @ToolMapping to expose services; client-side integration folds remote MCP tools into the local tool system; multiple endpoint groups per service.

Implementation detail: Spring AI builds on the official MCP Java SDK; Solon AI implements the protocol within its own runtime, which keeps the dependency tree small.

Difference #9: Runtime Footprint

The Solon project advertises (and its TechEmpower-style results back up) dramatically lower resource usage than comparable Spring Boot stacks: startup in fractions of a second, tens of MB of heap, tiny JARs. For serverless and edge deployments this matters; for a monolith behind an existing observability stack, it matters less. Spring AI compensates with first-class Micrometer integration, Spring Security, and the enormous Spring ecosystem of starters.

Summary Table

Dimension	Spring AI	Solon AI
Ecosystem	Spring Boot native	Framework-neutral, embeddable anywhere
Java requirement	17+ (2.0: 21+)	8 ~ 26
Core API	ChatClient + Advisor chain	ChatModel + Agent ladder
Tools	`@Tool` + ToolCallback	`@ToolMapping` + Talent system
Structured output	`.entity(Class)`	`outputSchema(Class)`, provider-neutral
RAG	Advisors, modular pipeline	Repository abstraction, agentic RAG built in
Memory	ChatMemory advisors	ChatSession + AgentSession (incl. HITL state)
Agents	Compositional (advisors/tools)	Native ReAct/Team agents + Ai Flow YAML
MCP	Starters + MCP Java SDK	Native implementation, multi-endpoint
Footprint	Typical Spring Boot	Very small, fast startup
Observability	Micrometer, Actuator	Solon ecosystem

Which One Should You Pick?

Choose Spring AI when you already live in Spring Boot, your team's skills are Spring-centric, and you value the ecosystem: auto-configuration, starters for everything, Micrometer observability, and long-term commercial backing from the Spring team.

Choose Solon AI when you need AI features in a codebase that is not (or cannot be) a modern Spring Boot app: Java 8 legacy services, Quarkus/Vert.x/jFinal stacks, resource-constrained deployments — or when your application is fundamentally an agent system and you want native ReAct, team collaboration, skills, and YAML flow orchestration rather than assembling them from parts.

And remember the pragmatic option: because Solon AI embeds into Spring Boot, the choice is not always either/or — some teams use Spring Boot for the web tier and Solon AI for the agent core, taking the best of both ecosystems.

Both frameworks move fast, both are genuinely production-capable, and the competition between them is exactly what the Java AI ecosystem needs right now.

References

Spring AI reference docs: https://docs.spring.io/spring-ai/reference/
Spring AI project page: https://spring.io/projects/spring-ai
Solon AI repository: https://github.com/opensolon/solon-ai
Solon AI docs: https://solon.noear.org/article/learn-solon-ai
Model Context Protocol: https://modelcontextprotocol.io

Give Your Java Agents a Memory - Session Management with Solon AI

Solon Framework — Thu, 20 Aug 2026 15:17:07 +0000

Most LLM demos are amnesiacs. The user says "my name is noear and I like blue" in turn one, asks "what's my name?" in turn two, and the model shrugs - because every HTTP call to the chat API is stateless, and nobody fed the history back in. In production this is not a cosmetic issue: a support agent that forgets the ticket the customer opened 30 seconds ago is worse than no agent at all.

Solon AI (v4.0.5) treats conversation state as a first-class, pluggable construct. In this article we build a multi-turn customer support agent whose memory survives process restarts and horizontal scaling, using only the framework's session abstractions - no hand-rolled history tables.

The problem with hand-rolled memory

The naive fix is to append every message to a List<ChatMessage> in your own code and resend it with each request. That works until it doesn't:

Unbounded growth - a 200-turn ticket means 400 messages re-sent (and re-billed as tokens) on every call.
System prompt pollution - if you persist everything, stale system prompts pile up inside the history.
No place for workflow state - agents don't just remember text; they remember where they are in a plan, which steps finished, what a human approved.
Restart amnesia - in-memory lists die with the JVM.

Solon AI answers each of these with a dedicated layer.

ChatSession: the message ledger

At the core sits ChatSession (org.noear.solon.ai.chat, since 3.1) - a deliberately small interface that models the conversation as an append-only message sequence:

public interface ChatSession {
    String getSessionId();

    List<ChatMessage> getMessages();
    List<ChatMessage> getLatestMessages(int windowSize);
    void removeLatestMessage(int windowSize);

    void addMessage(Collection<? extends ChatMessage> messages);
    void addMessage(String userMessage);          // convenience: user role

    boolean isEmpty();
    void clear();

    Map<String, Object> attrs();                  // transient, never persisted
}

Two details are worth calling out:

getLatestMessages(windowSize) is the windowing primitive. The framework itself uses it to inject only the last N turns into the prompt - the unbounded-growth problem is solved at the retrieval side, not by deleting history. The full ledger stays available for audit.
attrs() is explicitly documented as not needing persistence - a place for per-request scratch data that must never leak into your storage layer.

AgentSession: memory plus workflow state

Agents need more than a transcript. AgentSession (since 3.8.1) extends ChatSession with the state of the agent's execution flow:

public interface AgentSession extends ChatSession {
    void updateSnapshot();          // sync execution snapshot
    FlowContext getContext();       // live flow context

    void pending(boolean pending, String reason); // suspend / resume
    boolean isPending();
    String getPendingReason();
}

The pending(...) family is how human-in-the-loop agents park themselves mid-plan: suspend with a reason ("waiting for expense approval"), serialize the whole session, and resume the exact step when the human answers. Because the snapshot lives inside the session object, one storage backend covers both transcript and workflow state.

Attaching a session to an agent

Every agent request carries its session explicitly:

ChatModel chatModel = ...;

SimpleAgent agent = SimpleAgent.of(chatModel)
        .name("SupportAgent")
        .role("A customer support assistant")
        .instruction("Track the customer's issue across the whole conversation.")
        .sessionWindowSize(10)   // inject last 10 messages as history
        .build();

AgentSession session = InMemoryAgentSession.of("customer-8837");

// Turn 1
agent.prompt("My order #5521 arrived broken, I want a replacement.")
     .session(session)
     .call()
     .getMessage();

// Turn 2 - minutes later, same session: the agent already knows the order number
String answer = agent.prompt("It was the blue ceramic mug, by the way.")
     .session(session)
     .call()
     .getContent();

What the framework does per call (from the SimpleAgent source):

Builds the agent prompt, pulling session.getLatestMessages(config.getSessionWindowSize()) as history (default window: 5).
Stamps __sessionId into both the prompt attributes and the tool context - so custom tools you write can correlate database writes with the conversation.
Appends the assistant's reply with session.addMessage(...) and calls updateSnapshot() - your code never mutates history manually.

Pluggable backends

Sessions are an interface, and three backends ship in the box:

Backend	Messages	Snapshot	Use case
`InMemoryAgentSession`	JVM heap	JVM heap	tests, single-node demos
`FileAgentSession`	NDJSON append log	JSON file	single instance, zero infra
`RedisAgentSession`	Redis list (`<id>:messages`)	Redis key (`<id>:snapshot`)	production, multi-instance

The FileAgentSession behaves like a proper write-ahead log. The official test suite demonstrates the property that matters most - restart recovery:

FileAgentSession session = new FileAgentSession(sessionId, tempDir);
session.addMessage(ChatMessage.ofUser("hello"),
                   ChatMessage.ofAssistant("hi, how can I help?"));
session.getContext().put("user_name", "noear");
session.updateSnapshot();

// simulate a process restart: new instance, same directory
FileAgentSession recovered = new FileAgentSession(sessionId, tempDir);

recovered.getMessages().size();                 // 2 - transcript survived
recovered.getContext().get("user_name");        // "noear" - snapshot survived

Note the subtlety verified by the same tests: system messages are filtered out of the NDJSON log. Persisted history contains only the real conversation (user/assistant/tool), so reloading never stacks stale system prompts.

RedisAgentSession adds an in-memory cache layer with per-session locking, so hot conversations don't pay a network round trip per message, while the canonical state lives in Redis - which is what you want when the support team's traffic lands on a load balancer and turn two may hit a different pod than turn one.

One provider to route them all

The last piece is AgentSessionProvider - a one-method factory the framework uses to resolve sessions by business ID:

@Bean
public AgentSessionProvider redisSession(RedisClient redisClient) {
    Map<String, AgentSession> map = new ConcurrentHashMap<>();
    return sessionId -> map.computeIfAbsent(
            sessionId, k -> new RedisAgentSession(k, redisClient));
}

The contract is lazy loading: return the existing session if there is one (keeping context continuous), create one on demand otherwise. Inject it wherever agents are used:

@Inject AgentSessionProvider sessionProvider;
@Inject ReActAgent supportAgent;

public String reply(String customerId, String message) throws Throwable {
    AgentSession session = sessionProvider.getSession("customer-" + customerId);
    return supportAgent.prompt(message)
            .session(session)
            .call()
            .getContent();
}

Because the session ID is your business key ("customer-8837"), memory becomes addressable: the same customer chatting from the app and from email can be routed to the same session, and your data retention tooling can age sessions out by exactly the keys it already knows.

Windows, not truncation

A common misconception is that windowing means deleting history. In Solon AI the two are separate concerns:

getLatestMessages(n) - what the model sees (token cost control)
getMessages() - what your system knows (audit, analytics, compliance)

So a support platform can show the customer their full transcript in the UI, feed the agent only the last 10 messages for cost, and keep everything in NDJSON or Redis for the retention policy - one session object, three views.

Closing thoughts

Statelessness is the LLM's constraint, not yours. Solon AI's session layer turns "agent with memory" from a hand-rolled liability (growing lists, lost state on deploy, no audit trail) into a configuration decision: pick a backend, set a window, inject a provider. The transcript, the workflow snapshot and the human-in-the-loop suspension point all ride in the same persistent object - and swapping the demo InMemoryAgentSession for the production RedisAgentSession is a one-line change.

If you want to dig into the agent framework, chat models, RAG or tool calling, the docs live at solon.noear.org.

From Messy Text to Reliable Java Objects - Structured Output Extraction with Solon AI

Solon Framework — Thu, 20 Aug 2026 03:50:41 +0000

Every enterprise has a pile of documents that machines cannot read yet: supplier invoices arriving as free-text emails, résumés in a dozen formats, support tickets, contract clauses. The downstream systems - ERP, ATS, CRM - all want clean, typed data. Bridging that gap has traditionally meant brittle regex farms or template matchers that break on the first layout change.

Large language models are obviously good at reading this text. The unsolved part is the output contract. If you just ask a model "return JSON", you get JSON decorated with markdown fences, occasional prose preambles, missing fields, or a friendly sentence explaining why it could not comply. That is fine for a demo and fatal for a database insert.

This article shows how Solon AI (v4.0.5) treats structured extraction as a first-class capability: you declare the target as a plain Java type, the framework generates the JSON Schema, injects it into the conversation, extracts the JSON from whatever the model actually returned, and deserializes it back into your bean - with retries, sessions and agents when you need them.

The problem with "please return JSON"

The common workaround is prompt engineering:

Extract the invoice fields and return ONLY valid JSON matching: {invoice_no, total, currency, ...}

Three failure modes in production:

Decoration drift. Models wrap output in ```json fences, add "Here is the JSON:", or both. Your parser dies on character one.
Schema amnesia. Long prompts, many fields - the model forgets tax_rate or invents taxRate. Nothing catches it before the INSERT.
Provider lock-in. Some vendors offer native JSON mode or response_format with strict schemas. Your extraction code then only works with that one vendor, and the migration cost multiplies across every extraction job you own.

Solon AI addresses all three with a type-driven pipeline that runs on any ChatModel.

Step 1: Declare the target type

Extraction targets are ordinary Java beans. Fields can carry @Param annotations to enrich the generated schema with descriptions, required flags and defaults:


java
public class InvoiceInfo {
    @Param(description = "Invoice number, e.g. INV-2025-0311", required = true)
    public String invoiceNo;

    @Param(description = "Vendor legal name", required = true)
    public String vendor;

    @Param(description = "Total amount in minor currency units", required = true)
    public Long totalAmount;

    @Param(description = "ISO-4217 currency code")
    public String currency;

    @Param(description = "Due date in yyyy-MM-dd")
    public String dueDate;

    @Param(description = "Extracted line items")
    public LineItem[] items;

    public static class LineItem {
        @Param(description = "Item description")
        public String description;

        @Param(description = "Quantity", required = true, defaultValue = "1")
        public Integer quantity;

        @Param(description = "Unit price in minor units")
        public Long unitPrice;
    }
}

Why descriptions matter: they end up inside the JSON Schema that the model reads. A field named totalAmount is ambiguous (gross? net? VAT included? major or minor units?). The schema text is the cheapest place to remove that ambiguity - cheaper than debugging wrong numbers in your ledger.

Step 2: Attach the schema and call

With just the core chat API, the schema rides on the request options:


java
ChatModel chatModel = ChatModel.of("http://localhost:11434/api/chat")
        .apiKey(System.getenv("LLM_API_KEY"))
        .model("qwen3:14b")
        .build();

ChatResponse resp = chatModel
        .prompt(invoiceEmailText)
        .options(o -> o.outputSchema(InvoiceInfo.class))
        .call();

InvoiceInfo invoice = resp.getMessage().toBean(InvoiceInfo.class);

System.out.println(invoice.invoiceNo + " -> " + invoice.totalAmount);

That is the whole extraction call. Three things happened under the hood worth understanding, because they are the difference between this and prompt-begging.

How the schema reaches the model

When outputSchema is set, the request pipeline hands the schema string to the active chat dialect, which appends it to the instruction block:


json
<output_schema>
{"type":"object","properties":{"invoiceNo":{"type":"string","description":"Invoice number, e.g. INV-2025-0311"}, ...},"required":["invoiceNo","vendor","totalAmount", ...]}
</output_schema>

The schema itself is generated from the Java type by the framework (snack4's JsonSchema generator walks the TypeEggg metadata of your bean, consuming the @Param annotations along the way). Primitive wrappers, strings, enums and simple types don't even need a schema - only structured objects do, so your prompt stays minimal when a type degenerates to a string.

Because the injection happens through the ChatDialect extension point, every provider benefits - Ollama, OpenAI, DashScope, Gemini, Anthropic - and a vendor with a native strict JSON mode could override the hook. Your extraction code never branches on provider capabilities.

How the answer comes back

Models will still decorate. AssistantMessage.getJsonContent() strips the noise: it locates the first { or [ and the matching last closing brace, so markdown fences, "Here is the JSON:" preambles and trailing commentary are all tolerated. toBean() then deserializes the extracted JSON into the target type. You can also call getResultContent() to get thinking-stripped raw text if you want to run your own validation.

What you do NOT get for free

Honesty section: a schema improves field discipline dramatically, but it cannot make a small model do reliable arithmetic. For invoice totals, compute from line items in Java; use extraction only to read, not to sum. Validation belongs in your code:


java
if (invoice.totalAmount == null || invoice.items == null || invoice.items.length == 0) {
    throw new ExtractionException("invoice fields missing: " + invoice.invoiceNo);
}

Step 3: Promote to an extraction agent

Single calls are fine for one document. A production pipeline processing hundreds of résumés per day wants retries, low temperature, and a place to collect results. This is where SimpleAgent earns its name:


java
SimpleAgent resumeAgent = SimpleAgent.of(chatModel)
        .name("ResumeExtractor")
        .role("HR assistant specialized in résumé parsing")
        .instruction("Extract the key facts from the candidate text provided by the user")
        .outputSchema(ResumeInfo.class)
        .outputKey("extracted_resume")
        .retryConfig(3, 2000L)
        .modelOptions(o -> o.temperature(0.1F))
        .build();

public static class ResumeInfo {
    public String name;
    public Integer age;
    public String email;
    public String[] capabilities;
}

Running it against a batch:


java
AgentSession session = InMemoryAgentSession.of("resume-batch-01");

for (String rawResume : inboundResumes) {
    AssistantMessage message = resumeAgent
            .prompt(Prompt.of(rawResume))
            .session(session)
            .call()
            .getMessage();

    // Path A: typed bean directly
    ResumeInfo info = message.toBean(ResumeInfo.class);

    // Path B: same result, stored in the session context under outputKey
    String extractedJson = (String) session.getContext().get("extracted_resume");

    atsService.upsert(info);
}

The knobs that matter for extraction jobs:

outputSchema(ResumeInfo.class) - same type-driven schema as the raw ChatModel path.
outputKey("extracted_resume") - the agent also writes the extracted JSON into the session context, so downstream steps (an enrichment agent, a human reviewer, an export job) can pick it up without re-parsing the message.
retryConfig(3, 2000L) - up to 3 retries with a 2s delay. Schema violations and unparseable output are exactly the transient failures retries absorb.
modelOptions(o -> o.temperature(0.1F)) - extraction is reading, not writing poetry. Low temperature measurably reduces format drift.

The same builder surface exists on ReActAgent for extraction jobs that need tools first - say, the agent must call a country-code lookup service before it can normalize a phone number, then emit the final structured result.

Where the pieces live

For reference, the moving parts in the Solon AI modules:

Capability	Module	Entry point
Schema generation from Java types	`solon-ai-core`	`ToolSchemaUtil.buildOutputSchema(Type)`
Schema injection per provider	`solon-ai-core` dialects	`ChatDialect.prepareOutputSchemaInstruction(...)`
JSON stripping + deserialization	`solon-ai-core`	`AssistantMessage.getJsonContent()` / `toBean(Type)`
Agent pipeline (retry, outputKey)	`solon-ai-agent`	`SimpleAgent` / `ReActAgent` builders

Dependencies for a minimal extraction service:


xml
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-core</artifactId>
</dependency>
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-dialect-ollama</artifactId>
</dependency>
<!-- or: solon-ai-dialect-openai / dashscope / gemini / anthropic -->
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-agent</artifactId>
</dependency>

Beyond invoices and résumés

The same pattern generalizes to any text-to-record workload:

Support tickets → structured incident records (severity, product area, entitlement) feeding your ticketing API.
Contract clauses → obligation registers with counterparty, deadline, penalty fields for a compliance dashboard.
Sensor log excerpts → fault codes for maintenance planning, where the "text" is semi-structured machine output.
Agent-to-agent handoff - one agent's structured output is the next agent's typed input, with outputKey as the contract slot.

When your extraction job outgrows a single call, the schema composes with the rest of the Solon AI stack: wrap it in a TeamAgent workflow with a human-in-the-loop checkpoint for low-confidence records, or let a Loop-based validator re-prompt with the validation error until the bean passes - the schema gives the loop a concrete failure signal to work with.

Wrapping up

Structured extraction fails in production for boring reasons: fences around the JSON, renamed fields, vendor-specific JSON modes. Solon AI's answer is to make the Java type the single source of truth - generate the schema from it, transport it in a provider-neutral way, strip whatever decoration the model adds, and deserialize back into the same type that generated the contract. Add retries and low temperature at the agent layer, and the gap between "the model can read it" and "the database can accept it" closes to a few lines of code.

The framework is open source, Java 8 to 26, and the docs live at solon.noear.org.

Integrating External Tool Ecosystems with Solon AI's MCP Protocol

Solon Framework — Wed, 19 Aug 2026 11:32:08 +0000

Large Language Models (LLMs) are only as powerful as the tools they can access. While internal tools are easy to wire directly into a Java application, the real challenge begins when you need your AI agents to reach out — to call REST APIs, query databases, invoke third-party services, or even communicate with other AI systems.

Hardcoding every external dependency creates a fragile architecture. Every new tool requires code changes, new dependencies, and new configurations. This is where the Model Context Protocol (MCP) comes in.

In this article, we explore how Solon AI v4.0.5 implements MCP to solve one of the hardest problems in AI engineering: How do we let agents access external tool ecosystems in a standardized, reusable, and secure way?

The Problem: Tool Sprawl in AI Applications

Imagine you're building a financial analysis agent. Initially, it needs access to:

Stock price APIs
Company financial report databases
Real-time news feeds
Regulatory filing systems
Risk scoring models

If you hardcode all of these, every new tool requires:

New Maven dependencies
New service classes
New tool registration code
New configuration properties
New error handling logic

And if you want to share these tools across different applications or with other teams? You'd have to copy-paste entire codebases or rebuild everything from scratch.

This is exactly the problem MCP solves. By adopting an open protocol, tools become composable, shareable, and reusable — just like Linux executables or npm packages.

What is MCP?

Model Context Protocol (MCP) is an open standard for connecting AI applications to external data sources and tools. Think of it as USB-C for AI agents — a universal connector that lets any client talk to any server using a common language.

The protocol defines three core primitives:

Tools: Functions the agent can call (like get_weather(city))
Resources: Data the agent can read (like weather://forecast/{city})
Prompts: Reusable template instructions (like summarize_report)

Originally developed by Anthropic and now maintained by the MCP Open Source Project, the protocol has gained massive adoption. As of 2025, over 1,200 MCP servers exist across 30+ categories — from file systems and databases to email, calendars, and code repositories.

Solon AI's MCP Integration

Solon AI v4.0.5 adds deep MCP support through the solon-ai-mcp module. Let's look at how it works.

Server Side: Exposing Tools via MCP

To expose a Java service as an MCP server, you only need to:

Add the solon-ai-mcp dependency
Annotate your tool class with @McpServerEndpoint
Use @ToolMapping for tools, @ResourceMapping for resources

Here's a complete example:

@McpServerEndpoint(
    channel = McpChannel.STREAMABLE,
    mcpEndpoint = "/mcp/weather"
)
public class WeatherTool {

    @ToolMapping(description = "Get current weather for a city")
    public String getWeather(@Param String city) {
        // Call external weather API
        return fetchWeatherData(city);
    }

    @ResourceMapping(
        uri = "weather://forecast/{city}",
        description = "Get weather forecast"
    )
    public String getForecast(@Param String city) {
        return buildForecastJson(city);
    }
}

That's it. Solon AI automatically:

Registers the tools and resources with the MCP server
Handles JSON-RPC message serialization/deserialization
Manages the transport layer (HTTP, SSE, or Stdio)
Supports the notifications/tools/list_changed event for dynamic updates

Client Side: Using Remote Tools as Local Beans

The real power shines on the client side. Once a tool is exposed via MCP, any Solon AI agent can use it as if it were a local bean:

@Configuration
public class MyAppConfig {

    @Bean
    public McpTalentClient weatherClient(McpClientProvider provider) {
        return new McpTalentClient(provider);
    }

    @Bean
    public ReActAgent agent(McpTalentClient weatherTool) {
        return ReActAgent.builder()
            .system("You are a travel assistant...")
            .defaultToolAdd(weatherTool)  // Inject MCP tool
            .build();
    }
}

The McpTalentClient acts as a bridge between your agent and the remote MCP server. When the agent calls getWeather(), the call is routed over the network to the server, executed, and the result is returned — all transparently.

Transport Options

Solon AI supports four transport channels via McpChannel:

Channel	Use Case
`STDIO`	Local CLI tools, subprocess invocation
`SSE`	Long-running server connections
`STREAMABLE`	Modern HTTP-based (recommended)
`STREAMABLE_STATELESS`	Stateless HTTP, no session management

For production systems, STREAMABLE is recommended because it provides both HTTP/2 multiplexing and session management.

Real-World Use Case: Multi-Source Financial Analysis

Let's build a practical example. Imagine a compliance agent that needs to:

Query a company database for financial records
Call a risk scoring API
Fetch regulatory updates from an external feed
Generate a compliance report

With MCP, each data source becomes a separate MCP server that can be developed, deployed, and updated independently:

# app.yml
solon:
  ai:
    mcp:
      client:
        financial-db:
          channel: streamable
          url: http://localhost:8081/mcp
        risk-api:
          channel: streamable
          url: http://localhost:8082/mcp
        regulatory-feed:
          channel: streamable
          url: http://localhost:8083/mcp

The compliance agent doesn't know (or care) which server provides which tool. It just declares what it needs:

@ToolMapping(description = "Query company financials")
public FinancialData queryFinancials(@Param String ticker);

@ToolMapping(description = "Calculate risk score")
public RiskScore calculateRisk(@Param FinancialData data);

@ToolMapping(description = "Fetch regulatory updates")
public List<String> getRegulatoryUpdates(@Param String category);

When the agent runs, it automatically discovers and calls the appropriate tools. If you need to update the risk API, you only change the server code — the agent remains untouched.

Advanced: Stateful vs Stateless Servers

Solon AI v4.0.5 supports both stateful and stateless MCP servers:

Stateful servers (McpServerHost): Maintain connection state, support streaming, ideal for long-running services
Stateless servers (StatelessMcpServerHost): No connection state, simpler deployment, better for microservice architectures

For most enterprise applications, stateless servers are preferred because they're easier to scale horizontally.

Security Considerations

When exposing tools via MCP, security is paramount:

Authentication: Use HTTP headers or JWT tokens to authenticate clients
Authorization: Implement role-based access control at the tool level
Input Validation: Always validate tool parameters to prevent injection attacks
Rate Limiting: Protect backend services from abuse
Audit Logging: Log all tool calls for compliance

Solon AI's McpPlugin supports custom ServerTransportSecurityValidator implementations for advanced security scenarios.

The Bigger Picture

MCP is not just a technical solution — it's a cultural shift in how we build AI applications. Instead of every developer reinventing the wheel for each new tool, we now have a shared ecosystem where:

Tool creators can build once and deploy everywhere
Agent developers can discover and compose tools without knowing implementation details
Enterprise IT can manage tool access centrally with consistent security policies

As the MCP ecosystem grows, we'll see more specialized servers emerge — from code review tools to database query optimizers to legal document reviewers. The possibilities are limited only by our imagination.

Getting Started

To add MCP support to your Solon AI project:

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-mcp</artifactId>
    <version>4.0.5</version>
</dependency>

Then follow the patterns shown in this article. The full source code examples are available in the Solon AI GitHub repository.

Conclusion

MCP is solving one of the most fundamental challenges in AI engineering: How do we make tools composable and reusable?

By implementing MCP support, Solon AI gives you:

Standardized integration — connect to any MCP server using a common protocol
Tool reuse — build once, deploy everywhere
Security — enterprise-grade authentication and authorization
Flexibility — support for multiple transport channels

The future of AI is not about building bigger models — it's about connecting smarter tools. And MCP is the protocol that makes that possible.

Ready to explore? Check out the Solon AI documentation and join the MCP community.

The Solon AI Talent System: Solving Real Business Problems with Composable Agent Capabilities

Solon Framework — Wed, 19 Aug 2026 10:13:44 +0000

Every LLM agent library gives you tools. Few give you a coherent system for organizing those tools into reusable, context-aware skill clusters that can adapt to the business problem at hand — not the other way around. Solon AI's Talent system is that organization layer.

In this post I'll walk through what a Talent actually is, how it differs from a plain tool, and how Solon ships over thirty built-in Talents covering everything from code search and memory management to enterprise messaging and file operations. Then I'll show how to compose them to solve real business problems: sending a report email with attachments, pushing a deployment notification to your team chat, and running a self-improving agent that learns from past conversations.

What a Talent actually is

In Solon AI, a Talent is a bundle of three things:

Tools — the FunctionTool methods the LLM can call (annotated with @ToolMapping).
Instructions — a dynamic prompt fragment injected into the system message when the Talent is active, telling the model how to use those tools.
Metadata — name, description, and an enable/disable flag.

The key difference from a plain tool is context awareness. A Talent can decide whether it's relevant to the current conversation via isSupported(Prompt), initialize state when attached via onAttach(Prompt), and even swap its tool set dynamically based on what the user is asking.

public class MyTalent extends AbsTalent {

    @Override
    public boolean isSupported(Prompt prompt) {
        String content = prompt.getUserContent().toLowerCase();
        return content.contains("代码") || content.contains("code");
    }

    @Override
    public String getInstruction(Prompt prompt) {
        return "## 代码搜索指南\n你可以通过 codesearch 工具查找 API 文档和示例代码...\n";
    }

    @ToolMapping(name = "my_tool", description = "Do something useful")
    public String myTool(@Param("param") String param) {
        return doSomething(param);
    }
}

AbsTalent (the convenience base class) handles the boilerplate: it reflects over @ToolMapping methods to auto-register tools, manages the enabled/disabled lifecycle, and exposes getToolMap() and getToolAry() for introspection.

The built-in Talent ecosystem

Solon AI ships a rich set of Talents across dedicated Maven modules. Here's a survey of the ones most relevant to business applications:

Talent	Module	What it does
`TerminalTalent`	`solon-ai-talent-cli`	File read/write/ls/grep/glob + bash execution with sandbox support
`MemoryTalent`	`solon-ai-talent-memory`	Long-term memory: extract, recall, search, consolidate, prune
`WebsearchTalent`	`solon-ai-talent-web`	Real-time web search via Exa MCP
`CodeSearchTalent`	`solon-ai-talent-web`	Code repo search via Exa MCP
`MailTalent`	`solon-ai-talent-mail`	Send emails with HTML body and file attachments
`DingTalkTalent`	`solon-ai-talent-social`	Push messages to DingTalk (with HMAC signature)
`FeishuTalent`	`solon-ai-talent-social`	Push Lark/Feishu cards (with signature)
`WeComTalent`	`solon-ai-talent-social`	Push messages to WeCom / Enterprise WeChat
`Text2SqlTalent`	`solon-ai-talent-text2sql`	Natural language to SQL with dialect support
`PdfTalent`	`solon-ai-talent-pdf`	PDF reading and extraction
`RedisTalent`	`solon-ai-talent-data`	Redis read/write operations
`LspTalent`	`solon-ai-talent-lsp`	Language Server Protocol integration

All Talents are opt-in. You挂 them onto a ReActAgent or HarnessEngine explicitly:

ReActAgent agent = ReActAgent.of()
    .model(chatModel)
    .defaultTalentAdd(
        new TerminalTalent(mountManager),
        new MemoryTalent(solutionProvider),
        new MailTalent(workDir, host, port, user, pass),
        new DingTalkTalent(webhookUrl, secret)
    )
    .build();

Each Talent's isSupported() method is evaluated at call time. If the current prompt matches, the Talent activates, its getInstruction() is injected into the system message, and its tools become available to the model.

Business scenario 1: automated report delivery

A common enterprise pattern: generate a report, attach it, and email it to stakeholders. With Solon AI, this is two Talents working together.

MailTalent mail = new MailTalent(
    "/path/to/workdir",
    "smtp.company.com", 465,
    "agent@company.com", "smtp-password"
);

DingTalkTalent dingtalk = new DingTalkTalent(
    "https://oapi.dingtalk.com/robot/send?access_token=xxx",
    "SECxxxxxxxx"
);

ReActAgent agent = ReActAgent.of()
    .model(chatModel)
    .defaultTalentAdd(mail, dingtalk)
    .build();

When the user says "Generate the monthly sales report and send it to the team," the agent:

Uses TerminalTalent to generate the report file in the work directory.
Calls send_email on MailTalent, which auto-detects the attachment path, reads the file bytes, and sends via SMTPS (port 465, TLS). The MailTalent resolves attachment paths relative to the work directory and validates them against the root path to prevent path traversal.
Calls send_dingtalk on DingTalkTalent, which packages the summary as a markdown message, computes the HmacSHA256 signature, and pushes to the webhook.

Both operations are synchronous from the agent's perspective. MailTalent uses a connection pool (coreSize=2) for SMTP sessions, so high-frequency report runs don't open a new TCP connection each time.

Business scenario 2: multi-platform team notification

In a multi-office company, different teams use different platforms — DingTalk in China, Feishu in some subsidiaries, WeCom in others. Rather than writing three separate notification integrations, you挂 all three Talents and let the model pick the right one based on context.

ReActAgent agent = ReActAgent.of()
    .model(chatModel)
    .defaultTalentAdd(
        new DingTalkTalent(dingtalkUrl, dingtalkSecret),
        new FeishuTalent(feishuUrl, feishuSecret),
        new WeComTalent(wecomUrl)
    )
    .build();

Each Talent overrides isSupported() to match keywords in the user's message:

DingTalkTalent: matches "钉钉" or "ding"
FeishuTalent: matches "飞书", "lark", or "feishu"
WeComTalent: matches "企微", "企业微信", or "wecom"

This means the model automatically routes to the correct platform. If the user says "Notify the Shanghai team on DingTalk about the deployment," only DingTalkTalent.isSupported() returns true, so its instruction and tools are injected. The other two Talents stay dormant.

FeishuTalent adds a nice touch: if a title is provided, it sends an interactive card (with a blue header and lark_md body); otherwise it falls back to plain text. DingTalkTalent similarly upgrades to markdown mode when a title is present.

Business scenario 3: self-improving agent with long-term memory

Perhaps the most powerful pattern is combining MemoryTalent with a ReActAgent to build an agent that gets smarter over time.

MemorySolutionProvider solutionProvider = /* ... configure ... */;

MemoryTalent memory = new MemoryTalent(solutionProvider)
    .relevanceCount(5)       // semantic matches from current conversation
    .priorityCount(5)        // high-importance fallback memories
    .relevanceInjection(true); // mix semantics + popularity

ReActAgent agent = ReActAgent.of()
    .model(chatModel)
    .defaultTalentAdd(memory)
    .build();

MemoryTalent exposes five tools:

memory_extract — store a fact with an importance score (1-10). Returns the old value for comparison if the key already exists.
memory_recall — exact lookup by key.
memory_search — semantic search by natural language query, or * to list all keys.
memory_consolidate — merge multiple low-importance fragments into a single high-importance insight (importance automatically set to 10).
memory_prune — delete a stale or incorrect entry.

The getInstruction() method of MemoryTalent does something important: it injects relevant memories into the system prompt at the start of each turn. It fetches up to relevanceCount semantically similar memories and up to priorityCount high-importance memories, deduplicates them, and formats them into the prompt. This means the agent doesn't need to explicitly call memory_search on every turn — the most relevant context is already there.

The agent is also guided by the injected instructions to proactively call memory_extract when it learns something worth remembering, and memory_consolidate when it notices碎片 (fragments) piling up.

The mount system: connecting Talents to the filesystem

TerminalTalent (the file system and bash Talent) works in concert with MountManager, which maps logical paths (@solon-source, @workspace-agents, etc.) to physical directories. When sandbox mode is enabled, TerminalTalent restricts all file operations to the work directory and explicitly listed mounts — no absolute paths, no cross-mount writes unless the mount is marked writeable="true".

The instruction string that TerminalTalent.getInstruction() generates is dynamic: it lists all active mounts with their aliases, types, and write permissions, so the LLM always knows which paths it can safely use.

<mount_list>
  <mount alias="@solon-source" type="FILES" writeable="false" ... />
  <mount alias="@workspace-agents" type="AGENTS" writeable="false" ... />
</mount_list>

This means you can give an agent read-only access to your source code repositories while allowing it to write freely in its work directory — all without hardcoding path restrictions in the prompt.

Why composition matters

The Talent system's real power isn't any single Talent — it's that they compose cleanly. Each Talent is an independent module with no hard dependencies on the others. You can mix and match:

Add Text2SqlTalent to let the agent query your database in natural language.
Add PdfTalent to let it read and summarize PDF attachments.
Add CodeSearchTalent so it can look up API docs before writing code.
Add MemoryTalent so it remembers your preferences across sessions.

And when a Talent isn't needed, you simply don't挂 it. There's no global registry to clean up, no configuration file to edit. The isSupported() gate ensures even unused Talents impose zero overhead.

All Talents share the same small vocabulary: @ToolMapping for tools, getInstruction() for context, isSupported() for gating. That uniformity is what makes the system feel cohesive rather than a collection of disjoint utilities.

If you want to explore the full list of built-in Talents and their APIs, the source lives at solon.noear.org.

Building a Grounded Enterprise Knowledge Base: RAG with Solon AI

Solon Framework — Tue, 18 Aug 2026 11:22:18 +0000

Every team eventually hits the same wall with LLMs: the model is confident, fluent, and completely wrong about your internal policies, your product docs, or last quarter's numbers. It was never trained on your data, so it hallucinates plausible-sounding answers. Retrieval-Augmented Generation (RAG) is the standard fix — you retrieve the relevant facts from your own corpus first, then let the model answer grounded in that context.

The problem is that most RAG stacks feel like a pile of loosely-related libraries stitched together: one thing to parse PDFs, another to chunk text, a vector database SDK, an embedding client, and a prompt-assembly layer you write by hand. Solon AI (v4.0.5) collapses that whole pipeline into a small, coherent set of interfaces. This post walks through building a real enterprise knowledge base — ingesting company docs, storing them in pgvector, and answering questions grounded in the retrieved content — using only the built-in APIs.

The pipeline in one picture

A production RAG system has two distinct phases:

Ingestion (offline): load raw documents → split into chunks → embed → store in a vector repository.
Query (online): embed the question → search for relevant chunks → augment the prompt → let the model answer.

Solon AI models each stage with a dedicated abstraction, and they compose cleanly. Let's build both phases.

Phase 1: Ingesting documents

Enterprise knowledge lives in messy formats — Markdown wikis, HTML pages, PDFs, Word docs, spreadsheets. Solon AI ships a DocumentLoader per format as separate Maven modules (solon-ai-load-markdown, solon-ai-load-html, solon-ai-load-pdf, solon-ai-load-word, solon-ai-load-excel, solon-ai-load-ppt). Each loader turns raw bytes into a List<Document>.

A Document is a simple, fluent value object:

Document doc = new Document("The refund window is 30 days from purchase.")
        .title("Refund Policy")
        .url("https://wiki.acme.com/policies/refund")
        .metadata("department", "support")
        .metadata("version", 3);

The metadata map is the workhorse for enterprise scenarios — you'll use it later to filter by department, product line, or access level.

Loading and splitting

Raw documents are usually too large to embed as a single vector, so they must be chunked. Solon AI provides a SplitterPipeline that chains multiple DocumentSplitter stages. A common, robust combination is: split on structural boundaries first (RegexTextSplitter), then enforce a hard token ceiling (TokenSizeTextSplitter) so no chunk exceeds the embedding model's context window.

import org.noear.solon.ai.rag.Document;
import org.noear.solon.ai.rag.DocumentLoader;
import org.noear.solon.ai.rag.loader.MarkdownLoader;
import org.noear.solon.ai.rag.loader.HtmlSimpleLoader;
import org.noear.solon.ai.rag.splitter.SplitterPipeline;
import org.noear.solon.ai.rag.splitter.RegexTextSplitter;
import org.noear.solon.ai.rag.splitter.TokenSizeTextSplitter;

public List<Document> loadAndSplit(String url) throws IOException {
    String text = HttpUtils.http(url).get();

    DocumentLoader loader;
    if (text.contains("</html>")) {
        loader = new HtmlSimpleLoader(text.getBytes(StandardCharsets.UTF_8));
    } else {
        loader = new MarkdownLoader(text.getBytes(StandardCharsets.UTF_8));
    }

    // Split structurally, then cap each chunk at 500 tokens.
    return new SplitterPipeline()
            .next(new RegexTextSplitter())
            .next(new TokenSizeTextSplitter(500))
            .split(loader.load());
}

TokenSizeTextSplitter is not a naive character-count chopper. Internally it tokenizes with jtokkit (the CL100K_BASE encoding), and when it reaches the chunk boundary it backs up to the last sentence-ending punctuation (., ?, !, or newline) so chunks don't get cut mid-sentence. The default constructor targets 500 tokens per chunk, which is a sensible starting point for most embedding models.

Phase 2: Storing in pgvector

For the vector store, this example uses PostgreSQL with the pgvector extension — a pragmatic choice for teams that already run Postgres and don't want to operate a separate vector database. Solon AI supports many backends (Redis, Elasticsearch, Milvus, Qdrant, Chroma, Weaviate, MariaDB, MySQL, and more), and they all implement the same RepositoryStorable interface, so swapping backends later is a one-line change.

You build a PgVectorRepository from two things: an EmbeddingModel and a JDBC DataSource.

import org.noear.solon.ai.embedding.EmbeddingModel;
import org.noear.solon.ai.rag.repository.PgVectorRepository;
import org.noear.solon.ai.rag.repository.pgvector.MetadataField;

EmbeddingModel embeddingModel = EmbeddingModel.of("http://127.0.0.1:11434/api/embed")
        .provider("ollama")
        .model("bge-m3")
        .build();

// Promote hot metadata keys to real indexed columns.
List<MetadataField> metadataFields = new ArrayList<>();
metadataFields.add(MetadataField.text("department"));
metadataFields.add(MetadataField.text("title"));
metadataFields.add(MetadataField.numeric("version"));

PgVectorRepository repository = PgVectorRepository.builder(embeddingModel, dataSource)
        .tableName("acme_knowledge")
        .metadataFields(metadataFields)
        .build();

The build() call does the DDL heavy-lifting for you. On first initialization it runs CREATE EXTENSION IF NOT EXISTS vector, creates the table with an embedding VECTOR(n) column sized to your embedding model's dimensions(), stores the full metadata map as JSONB, and creates an ivfflat cosine-distance index. The metadataFields you declare get promoted to dedicated typed columns (TEXT / NUMERIC / JSONB) so you can filter on them efficiently instead of digging through JSON on every query.

Saving is then trivial — the repository handles batching, embedding, and upserts internally:

List<Document> docs = loadAndSplit("https://wiki.acme.com/policies/refund.md");
repository.save(docs);

Under the hood save partitions the documents according to the embedding model's batchSize(), calls the embedding model per batch, and inserts with ON CONFLICT (id) DO UPDATE — so re-ingesting an updated document overwrites the old vector rather than duplicating it. For large corpora, there's an overload that reports progress:

repository.save(docs, (done, total) ->
        System.out.printf("Embedded batch %d / %d%n", done, total));

And an async variant, asyncSave(docs, progressCallback), that returns a CompletableFuture<Void> if you want to kick ingestion off the request thread.

Phase 3: Querying with grounding

Now the online path. The simplest retrieval is a bare query string, which uses sensible defaults (top 4 results, similarity threshold 0.4):

List<Document> hits = repository.search("How long is the refund window?");

For real applications you'll want control, and that's what QueryCondition gives you. This is where enterprise metadata filtering pays off — you can restrict retrieval to a specific department while still ranking by semantic similarity:

import org.noear.solon.ai.rag.util.QueryCondition;

QueryCondition condition = new QueryCondition("How long is the refund window?")
        .limit(5)
        .similarityThreshold(0.5)
        .filterExpression("department == 'support' AND version >= 2");

List<Document> hits = repository.search(condition);

The filterExpression is parsed by Solon's built-in expression engine (SnEL) and pushed down to the store — for pgvector it becomes a SQL WHERE clause against those promoted metadata columns, so the filter runs in the database, not in your JVM after the fact. Each returned Document carries a getScore() reflecting its similarity to the query, so you can inspect or threshold results yourself.

Assembling the grounded prompt

Retrieval only gets you the facts; you still have to feed them to the model. Repository has a convenience method, promptAugment, that does the search and packs the results into a user message:

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.message.ChatMessage;

ChatModel chatModel = ChatModel.of("http://127.0.0.1:11434/api/chat")
        .provider("ollama")
        .model("qwen2.5")
        .build();

ChatMessage grounded = repository.promptAugment("How long is the refund window?");

String answer = chatModel.prompt(grounded).call().getMessage().getContent();

promptAugment builds on ChatMessage.ofUserAugment, which formats the original question together with the current timestamp and the retrieved references into a single user message. The model now answers from the supplied context instead of its training-time guesses.

Going further: Agentic RAG

The pattern above is passive retrieval — you decide what to search for, once, before the model runs. But some questions need the model to decide what to look up, and to look up several things. Solon AI supports this with RepositoryTool, which wraps a repository as a callable tool the model can invoke on its own:

import org.noear.solon.ai.rag.RepositoryTool;

ChatModel agent = ChatModel.of("http://127.0.0.1:11434/api/chat")
        .provider("ollama")
        .model("qwen2.5")
        .defaultToolAdd(new RepositoryTool(repository))
        .build();

// The model can now call `repository_query` itself, with multiple search
// terms, whenever it decides it needs background knowledge.
String answer = agent.prompt("Compare our refund and exchange policies, and note any version differences.")
        .call().getMessage().getContent();

RepositoryTool exposes a repository_query tool that accepts a list of search terms (up to five) plus a topK, runs each search, and formats the merged results back to the model. This shifts the system from "passive retrieval" to "active knowledge-seeking" — the model can break a complex question into several targeted lookups. If you have a reranking model, you can pass it as a second constructor argument (new RepositoryTool(repository, rerankingModel)) to reorder hits by relevance before they reach the model.

Why this composes well

The thing worth noticing is that every stage is an interface, and swapping an implementation never touches the rest of your code:

Switch from pgvector to Redis or Milvus? Change the Repository construction line. save, search, and promptAugment are identical because they're defined on RepositoryStorable / Repository.
Add PDF ingestion? Add the solon-ai-load-pdf dependency and swap the loader. The splitter and repository don't care where the Document came from.
Move from passive to agentic retrieval? Wrap the same repository in a RepositoryTool.

That uniformity is the real payoff. RAG stops being a bespoke integration project and becomes a matter of picking implementations off a shelf, all speaking the same small vocabulary of Document, Repository, and QueryCondition.

If you want to explore the full set of loaders, splitters, and vector-store backends, the source and docs live at solon.noear.org.

Self-Healing Software Development: Automating Code Generation, Testing, and Fixing with Solon AI Loop Engine

Solon Framework — Mon, 17 Aug 2026 22:44:39 +0000

Software agents are transitioning from stateless assistants to autonomous, loop-driven operators. While generating boilerplate code is easy, the real challenge in software engineering is maintaining correctness: resolving compilation errors, fixing failing unit tests, and adhering to strict quality gates.

In traditional architectures, developers act as the loop execution engine: reviewing errors, editing code, and rebuilding until the tests pass.

With Solon AI (v4.0.5), the newly introduced solon-ai-loop plugin codifies this cyclic corrective behavior directly into your backend architecture. By leveraging the Loop Engine, custom Loop Strategies, and automated Quality Gates, we can construct self-healing software development agents that iterate autonomously on source code until all gates are met.

In this article, we will explore the core design of the Solon AI Loop Engine and build a complete, production-grade Self-Healing Coding & Verification Pipeline using Java 8+ and GraalVM-compatible components.

Understanding the Solon AI Loop Engine

The solon-ai-loop package provides a structured framework for stateful, iterative execution of tasks. Rather than letting an LLM run indefinitely or writing custom spaghetti loops, Solon AI models loops around three main components:

LoopEngine: The core runtime that starts, pauses, resumes, and monitors loop sessions.
LoopStrategy: Encapsulates the state machine defining how iterations progress, when to check constraints, and what dictates failure or success.
Validator & QualityGate: Decoupled verification components that assert whether an output meets quality thresholds (e.g., compilation, style rules, or test suites).

Three strategies are pre-built to match common software workflows:

RalphLoopStrategy: A PRD-driven, story-by-story implementation loop that tracks progress, learnings, and file modifications.
TeamPipelineStrategy: A multi-phase transition pipeline (PLAN $\rightarrow$ PRD $\rightarrow$ EXEC $\rightarrow$ VERIFY $\rightarrow$ FIX).
UltraQAStrategy: A testing-focused gatekeeper that runs code checks, tracks failures, and prevents runaway token usage using Same-Failure Detection.

Designing a Self-Healing Development Pipeline

Let's design a pipeline where an autonomous agent compiles, runs test suites, and refactors its own code when bugs occur.

+-------------------------------------------------------------+
|                       Solon AI Loop                         |
|                                                             |
|   +----------+        +------------+        +-----------+   |
|   |  Agent   |------->| Build Gate |------->| Test Gate |   |
|   |  (EXEC)  |        | (VERIFY)   |        | (VERIFY)  |   |
|   +----------+        +------------+        +-----------+   |
|        ^                     |                    |         |
|        |                     v (Fail)             v (Fail)  |
|        |              +------------+        +-----------+   |
|        +--------------|  Analyze   |<-------| Normalize |   |
|          (Fix Loop)   |  & Fix     |        | Failure   |   |
|                       +------------+        +-----------+   |
+-------------------------------------------------------------+

To prevent the agent from getting stuck in an infinite loop trying the exact same fix on a hard-to-resolve bug, our pipeline uses the UltraQAStrategy's built-in Same-Failure Detection. If the normalized error output remains identical across 3 consecutive attempts, the engine aborts the run with a SAME_FAILURE status, saving token usage and requesting human intervention.

Step-by-Step Implementation

1. Adding Dependencies

Include the core Solon AI dependencies alongside the new loop engine plugin in your pom.xml:

<dependencies>
    <!-- Solon AI Core -->
    <dependency>
        <groupId>org.noear</groupId>
        <artifactId>solon-ai-core</artifactId>
        <version>4.0.5</version>
    </dependency>

    <!-- Solon AI Loop Engine Plugin -->
    <dependency>
        <groupId>org.noear</groupId>
        <artifactId>solon-ai-loop</artifactId>
        <version>4.0.5</version>
    </dependency>

    <!-- Chat Model Dialect for model integration -->
    <dependency>
        <groupId>org.noear</groupId>
        <artifactId>solon-ai-dialect-openai</artifactId>
        <version>4.0.5</version>
    </dependency>
</dependencies>

2. Defining the Self-Healing Code Validator

First, we define a Validator that represents our physical quality gate checks. In a real-world scenario, this validator runs local shell commands (such as mvn compile or mvn test) or parses project compilation structures.

Here is the implementation of a mock compiler and test validator that simulates a compilation success on the 3rd attempt:

import org.noear.solon.ai.loop.validator.*;

public class SelfHealingCodeValidator implements Validator {
    private int compileAttempts = 0;

    @Override
    public ValidationResult validate(Object result, ValidationCriteria criteria) {
        return validateIteration(result, null);
    }

    @Override
    public ValidationResult validateQualityGate(QualityGate gate, Object result) {
        // Evaluate based on the gate type ("build" or "test")
        if ("build".equals(gate.getName())) {
            compileAttempts++;
            if (compileAttempts < 3) {
                return ValidationResult.failed(
                    "Compilation Error", 
                    "error: cannot find symbol\n  symbol: class OrderProcessor\n  location: package com.demo"
                );
            }
            return ValidationResult.passed("Build success!");
        } else if ("test".equals(gate.getName())) {
            return ValidationResult.passed("All unit tests passed!");
        }
        return ValidationResult.passed("Quality check skipped.");
    }

    @Override
    public ValidationResult validateIteration(Object iterationResult, ValidationContext context) {
        if (iterationResult == null) {
            return ValidationResult.failed("Execution Result Null", "No artifacts were produced.");
        }
        return ValidationResult.passed("Iteration valid.");
    }
}

3. Configuring the Loop Session with UltraQA Strategy

Now, we set up the LoopEngine and use UltraQAStrategy to drive our self-healing loop. We'll target the TESTS goal type and configure a maximum of 5 overall iterations:

import org.noear.solon.ai.loop.config.LoopConfig;
import org.noear.solon.ai.loop.config.LoopEngineConfig;
import org.noear.solon.ai.loop.engine.*;
import org.noear.solon.ai.loop.strategy.UltraQAStrategy;
import org.noear.solon.ai.loop.strategy.UltraQAStrategy.UltraQAGoalType;
import org.noear.solon.ai.loop.strategy.UltraQAStrategy.UltraQAExitReason;
import org.noear.solon.ai.loop.validator.QualityGate;

import java.time.Duration;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class SelfHealingPipelineDemo {

    public static void main(String[] args) throws InterruptedException {
        // 1. Initialize the Loop Engine
        LoopEngineConfig engineConfig = LoopEngineConfig.builder()
                .monitoringEnabled(true)
                .debuggingEnabled(true)
                .build();
        LoopEngine engine = new SimpleLoopEngine(engineConfig);

        // 2. Configure the Quality Gates (Build Gate followed by Test Gate)
        QualityGate buildGate = QualityGate.build(); // Runs compilation & dependency validation
        QualityGate testGate = QualityGate.test();   // Runs unit & integration tests

        // 3. Configure the QA Loop Strategy
        UltraQAStrategy qaStrategy = UltraQAStrategy.builder()
                .gates(Arrays.asList(buildGate, testGate))
                .goalType(UltraQAGoalType.TESTS)
                .parallelTesting(false)
                .maxTestAttempts(5) // Max cycles
                .strictMode(true)
                .build();

        // 4. Bind configuration
        Map<String, Object> params = new HashMap<>();
        params.put("workDir", "./demo-project");

        LoopConfig loopConfig = LoopConfig.builder()
                .taskDescription("Fix missing OrderProcessor class implementation in com.demo")
                .strategy(qaStrategy)
                .validator(new SelfHealingCodeValidator())
                .maxIterations(10)
                .verificationRequired(true)
                .statePersistenceEnabled(true)
                .parameters(params)
                .build();

        // 5. Start the Loop Session
        System.out.println("Starting Self-Healing pipeline...");
        LoopSession session = engine.start(loopConfig);

        // 6. Listen to live iteration state updates
        session.onIterationComplete(iterResult -> {
            System.out.printf("[Iteration %d] Status: %s | Message: %s | Duration: %d ms\n",
                    iterResult.getNumber(),
                    iterResult.getState(),
                    iterResult.getMessage(),
                    iterResult.getDuration().toMillis()
            );

            // Check metadata parameters
            Map<String, Object> meta = iterResult.getMetadata();
            if (meta != null && meta.containsKey("failures")) {
                System.out.printf("  -> Cumulative Failures Recorded: %s\n", meta.get("failures"));
            }
        });

        session.onStateChange(state -> {
            System.out.printf("[State Event] Loop transitioned to: %s\n", state);
        });

        // 7. Await termination (max 10 seconds)
        session.waitForCompletion(Duration.ofSeconds(10));

        // 8. Print out final analysis
        LoopResult result = session.getResult();
        if (result != null) {
            System.out.println("\n====================================");
            System.out.println("Pipeline Final Summary:");
            System.out.printf("  Session ID: %s\n", result.getSessionId());
            System.out.printf("  Successful: %s\n", result.isSuccess());
            System.out.printf("  Final State: %s\n", result.getFinalState());
            System.out.printf("  Total Iterations Run: %d\n", result.getTotalIterations());
            System.out.printf("  Total Execution Time: %d ms\n", result.getTotalDuration().toMillis());

            UltraQAExitReason exitReason = qaStrategy.getFinalExitReason(session.getContext());
            System.out.printf("  Execution Termination Reason: %s (%s)\n", 
                    exitReason.name(), 
                    exitReason.getDescription()
            );
            System.out.println("====================================");
        }
    }
}

Exploring the Run Traces

When running the pipeline, the console outputs how the state machine dynamically handles failures, fixes, and gates:

Starting Self-Healing pipeline...
[State Event] Loop transitioned to: EXECUTING
[Iteration 1] Status: FIXING | Message: Gate failed: build | Duration: 4 ms
  -> Cumulative Failures Recorded: 1
[State Event] Loop transitioned to: FIXING
[Iteration 2] Status: FIXING | Message: Gate failed: build | Duration: 2 ms
  -> Cumulative Failures Recorded: 2
[State Event] Loop transitioned to: FIXING
[Iteration 3] Status: VERIFYING | Message: Gate failed: test | Duration: 1 ms
  -> Cumulative Failures Recorded: 2
[Iteration 4] Status: COMPLETED | Message: All quality gates passed | Duration: 2 ms
  -> Cumulative Failures Recorded: 2
[State Event] Loop transitioned to: COMPLETED

====================================
Pipeline Final Summary:
  Session ID: 4c3ab871-6c2e-4b20-80de-cd13ad91cf76
  Successful: true
  Final State: COMPLETED
  Total Iterations Run: 4
  Total Execution Time: 9 ms
  Execution Termination Reason: GOAL_MET (目标达成)
====================================

How it resolved:

Iteration 1 & 2: The compile validator returned Compilation Error. Because the gate failed, the loop state changed to FIXING, indicating to the agent that corrective steps were needed.
Iteration 3: On the 3rd attempt, the compile check passed. The runner moved on to check the test gate, which failed because the test suite had not yet run under the verified state. The loop transitioned to VERIFYING.
Iteration 4: Both gates were fully verified, culminating in All quality gates passed and terminating with GOAL_MET.

Under the Hood: Same-Failure Guard & Message Normalization

If we simulate a recurring bug where the agent repeats the exact same error, the pipeline guards against runaway execution.

The UltraQAStrategy class implements normalization rules to sanitize error logs before registering them. Dynamic parameters like timestamps, random file lines, execution times, and version numbers are removed:

private String normalizeFailure(String failure) {
    if (failure == null) return "";
    return failure
            .replaceAll("\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}", "")  // Remove ISO timestamps
            .replaceAll(":\\d+:\\d+", "")                        // Remove line:column numbers
            .replaceAll("\\d+ms", "")                              // Remove durations
            .replaceAll("line \\d+", "line N")                  // Generalize line numbers
            .replaceAll("\\s+", " ")                            // Collapse white spaces
            .trim()
            .toLowerCase();
}

If failures.get(i).equals(lastFailure) matches the same pattern 3 times consecutively, the engine breaks:

[Iteration 1] Status: FIXING | Message: Gate failed: build | Error: compilation error at line 42
[Iteration 2] Status: FIXING | Message: Gate failed: build | Error: compilation error at line 42
[Iteration 3] Status: FIXING | Message: Gate failed: build | Error: compilation error at line 42

Execution Termination Reason: SAME_FAILURE (相同的失败重复出现)

By adding this check, you keep your LLM agent from entering a repeating loop when encountering system errors or environmental problems, preventing unnecessary API costs.

Conclusion

The Loop Engine in Solon AI (v4.0.5) shifts agent design from stateless, unidirectional workflows to robust, self-verifying systems. By pairing structural LLM generation with local compiling/testing tools via UltraQAStrategy or TeamPipelineStrategy, you can construct enterprise-grade pipelines capable of autonomous bug resolution.

Integrate the solon-ai-loop plugin into your current codebase and begin building self-healing, agentic workflows today!

For more documentation and code examples, visit the official repository:

GitHub Repository: opensolon/solon-ai
Official Website: solon.noear.org

Securing Financial Agents: Implementing Human-in-the-Loop (HITL) Workflows in Solon AI

Solon Framework — Mon, 17 Aug 2026 17:07:53 +0000

In the era of autonomous AI Agents, letting a Large Language Model (LLM) invoke backend tools directly presents a significant risk. If an Agent receives a command to "transfer $10,000 to user X" or "permanently purge the user database," executing it without human verification could result in financial or data disaster.

To bridge the gap between AI autonomy and enterprise safety, Solon AI (v4.0.5) introduces a robust, native Human-in-the-Loop (HITL) framework. By utilizing session-aware interceptors, it intercepts high-risk tool calls, suspends execution, and exposes an API for administrators to approve, reject, skip, or modify arguments before resuming.

This guide explores the design, API structure, and practical implementation of HITL workflows in Solon AI.

The HITL Architecture in Solon AI

The HITL architecture is designed around the ReAct (Reasoning and Acting) loop. Instead of letting the Agent execute tools immediately after reasoning, an interceptor chain checks the arguments against predefined safety rules.

[User Request] 
      │
      ▼
 [ReActAgent] (Reasoning)
      │
      ▼
  [ToolCall] ────► [HITLInterceptor] (Evaluate Args)
                          │
                ┌─────────┴─────────┐
         [Allowed / Safe]    [High-Risk / Suspend]
                │                   │
                ▼                   ├─► Push HITLPendingEvent
          [Execute Tool]            ├─► Set Session to PENDING
                │                   ▼
                │           [Wait for Human Decision]
                │                   │
                │                   ▼  (via API Controller)
                │           [HITL.submit(...) / approve / reject]
                │                   │
                │                   ├─► Push HITLDecidedEvent
                │                   ├─► Apply modifiedArgs / skip / reject
                │                   ▼
                └───────────────► [Resume Execution]

At its core, Solon AI provides three main components:

HITLInterceptor: ReAct interceptor that registers target tools and runs strategies to decide if a request should be suspended.
HITL: A static helper class offering convenient APIs for your controller to inspect pending tasks and submit human decisions.
HITLDecision: An object containing the decision type (Approve, Reject, Skip), comments, and optional parameter modifications.

Step 1: Defining a High-Risk Tool

Let's assume we have a Java tool mapped to execute database transfers. In Solon AI, this is defined as a standard tool provider:

import org.noear.solon.ai.chat.tool.AbsToolProvider;
import org.noear.solon.ai.chat.tool.annotation.ToolMapping;

public class FinancialTools extends AbsToolProvider {

    @ToolMapping(name = "transfer", description = "Transfer money to another account")
    public String transfer(String targetAccount, double amount) {
        // Execute the transfer transaction
        System.out.printf("Successfully transferred $%.2f to %s\n", amount, targetAccount);
        return "SUCCESS";
    }
}

Step 2: Configuring the HITL Interceptor

An interceptor is attached to the ReActAgent during construction. We register our safety evaluation rules using the HITLStrategy interface:

import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.react.intercept.HITLInterceptor;
import org.noear.solon.ai.agent.react.intercept.HITLStrategy;

// Setup ReActAgent with HITL Interceptor
ReActAgent agent = ReActAgent.of(llmModel)
    .defaultToolAdd(new FinancialTools())
    .defaultInterceptorAdd(new HITLInterceptor()
        // Define a strategy for the "transfer" tool
        .onTool("transfer", (trace, args) -> {
            double amount = Double.parseDouble(args.get("amount").toString());
            // If the amount exceeds $5,000, trigger HITL interception
            if (amount > 5000) {
                return "The transfer amount exceeds the single-transaction limit of $5000.";
            }
            return null; // Safe to proceed without intervention
        })
    )
    .build();

When the LLM outputs a tool call to transfer with an amount greater than 5000, the HITLInterceptor intercepts it, blocks execution, and tags the AgentSession as Pending.

Step 3: Handling Suspension in the Controller

When exposing the Agent through an HTTP endpoint, your controller must handle the PENDING state. Under the hood, Solon AI stores the task snapshots in the session context, which can be fetched using the HITL helper class.

import org.noear.solon.annotation.*;
import org.noear.solon.ai.agent.AgentSession;
import org.noear.solon.ai.agent.react.ReActResponse;
import org.noear.solon.ai.agent.react.intercept.HITL;
import org.noear.solon.ai.agent.react.intercept.HITLTask;
import org.noear.solon.core.handle.Result;

@Controller
@Mapping("/api/agent")
public class AgentController {

    private final ReActAgent agent; // Injected or constructed

    @Post
    @Mapping("/ask")
    public Result ask(String sessionId, String prompt) throws Throwable {
        AgentSession session = getOrCreateSession(sessionId);

        // Run the agent loop
        ReActResponse resp = agent.prompt(prompt)
                                  .session(session)
                                  .call();

        // If the execution was intercepted by HITL, return the pending task details
        if (session.isPending()) {
            HITLTask pendingTask = HITL.getPendingTask(session);
            return Result.failure(403, "REQUIRED_HUMAN_APPROVAL", pendingTask);
        }

        return Result.succeed(resp.getContent());
    }
}

If the agent decides to transfer $12,000, the REST API returns a status showing that approval is required, along with the HITLTask metadata (including the unique callUuid, the tool name, and the arguments).

Step 4: Submitting Human Decisions

Administrators need an endpoint to approve, reject, or bypass the transaction. With Solon AI v4.0.5, decisions are bound to a specific callUuid to handle parallel or batch tool calls.

Here is how you handle approval, rejection, skipping, and parameter modification:

import org.noear.solon.ai.agent.react.intercept.HITLDecision;
import java.util.Map;

@Post
@Mapping("/approve")
public Result approve(String sessionId, String callUuid, String action, @Body Map<String, Object> modifiedArgs) {
    AgentSession session = getSession(sessionId);

    // 1. Locate the precise task using callUuid
    HITLTask task = HITL.getPendingTaskByCallUuid(session, callUuid);
    if (task == null) {
        return Result.failure("No pending task found for UUID: " + callUuid);
    }

    HITLDecision decision;
    if ("approve".equalsIgnoreCase(action)) {
        decision = HITLDecision.approve().comment("Approved by operations manager.");

        // Human Override: If the manager adjusted the transfer amount down, apply it!
        if (modifiedArgs != null && !modifiedArgs.isEmpty()) {
            decision.modifiedArgs(modifiedArgs);
        }
    } else if ("reject".equalsIgnoreCase(action)) {
        decision = HITLDecision.reject("Rejected: Suspected fraudulent activity.");
    } else {
        // Skip: Bypass this tool call, returning a custom mock message to the LLM
        decision = HITLDecision.skip("Skipped: Submitter bypassed this step.");
    }

    // 2. Submit the decision back to the session
    HITL.submit(session, task, decision);

    // 3. Resume execution: Trigger agent call with a blank prompt
    try {
        ReActResponse resp = agent.prompt()
                                  .session(session)
                                  .call();
        return Result.succeed(resp.getContent());
    } catch (Throwable e) {
        return Result.failure(e.getMessage());
    }
}

Inside the Decision Lifecycle

When HITL.submit(...) is called, the decision is stored in the AgentSession context under _hitl_decision_<callUuid>. When the Agent resumes:

onAgentStart(trace): The interceptor intercepts the resume event. It scans all pending tasks in the session. If all have decisions, it sets the routing directly to the ACTION phase, skipping another LLM reasoning step.
ActionTask: When executing the tool task:
- On Approve: The tool is invoked. If modifiedArgs are provided, the interceptor clones the original arguments to preserve history, applies the modified parameters, and invokes the tool.
- On Reject: The tool is blocked. A rejection message is injected into the exchange context as if the tool failed, steering the LLM to handle the denial gracefully.
- On Skip: The tool is not run. The comment from the decision is directly returned to the LLM as the mock result of the tool.

Batch Tool Call & AlwaysAllow Settings

Solon AI's HITL framework also supports advanced features:

Batch Approvals: If the model decides to invoke three tools simultaneously, HITL.getPendingTasks(session) returns a list of tasks. You can submit individual decisions using HITL.submitAll(session, Map<callUuid, HITLDecision>) or approve them all with HITL.approveAll(session).
alwaysAllow: In some cases, a manager wants to say "Approve this transfer, and trust this specific action for the rest of the session." By submitting HITLDecision.approve(true) (or .alwaysAllow(true)), the framework automatically registers a session-level rule to bypass subsequent checks for this specific tool.

Summary

The Human-in-the-Loop mechanism in Solon AI (v4.0.5) transforms risky AI operations into secure, auditable, and human-guided workflows. By placing interceptors right at the boundary of tool execution and enabling real-time argument overrides, Solon AI ensures that autonomous agents remain safely within corporate compliance guardrails.

Orchestrating Complex Enterprise Workflows with Nested Agents in Solon AI

Solon Framework — Mon, 17 Aug 2026 16:59:41 +0000

Standard monolithic Large Language Model (LLM) prompts fall short when faced with complex, multi-stage enterprise procedures. For workflows such as financial credit approvals or audit pipelines, tasks must be routed based on strict compliance rules, pass through hierarchical review loops, and sometimes return to previous steps for corrections.

In this article, we demonstrate how to build and orchestrate a multi-stage Financial Loan Approval Pipeline using Solon AI (v4.0.5). We will leverage its native integration with the lightweight state machine engine Solon Flow, utilizing nested agents, conditional routing (Exclusive Junctions), and state verification.

The Architecture: Nested Agents and Flow Orchestration

Our credit approval system simulates a real-world enterprise workflow:

Entry Officer (KYC): Performs preliminary verification and data formatting.
Loan Architect: Automatically designs loan products, interest rates, and loan terms, rating risk levels (high, mid, low).
Risk Control Center (Nested Team): A specialized, nested sub-agent committee that acts as a unified black box. Inside, a Credit Department sub-team, a Quota Calculator, and a Legal Compliance Officer collaborate.
Stress Tester: Run simulations to assess risk and default probabilities. If tests fail, the workflow loops back to the Risk Control Center for term rectification.
Security Auditor: Conducts final checks to ensure GDPR compliance.
Final Approver: Signs off on the final decision, determining the disbursement route (canary or full).

Here is a simplified flowchart of the process:

[Start] -> (Entry Officer) -> (Loan Architect) -> [Junction: Risk Level?]
                                                        |
                            +---------------------------+ (high risk)
                            |                           |
                            v                           v (low/mid risk)
                   ((Risk Control Center)) ----> (Stress Tester)
                            ^                           |
                            |                           v
                            +----------------- [Junction: Passed?] (no)
                                                        | (yes)
                                                        v
                                                (Security Auditor)
                                                        |
                                                        v
                                                (Final Approver) -> [Disbursement Route] -> [End]

Implementing the Workflow in Solon AI

Let us implement this pipeline in Java using Solon AI.

Step 1: Initialize Chat Model and Define ReAct Agents

First, we set up our LLM backend and instantiate the individual professional agents using ReActAgent:

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.agent.react.ReActAgent;

// Initialize the ChatModel
ChatModel chatModel = ChatModel.of("https://api.your-provider.com/v1/chat/completions")
        .apiKey("your-api-key")
        .model("your-model-name")
        .build();

// Entry Officer (KYC Analyst)
ReActAgent entryOfficer = ReActAgent.of(chatModel)
        .name("entry_officer")
        .role("Loan Intake Officer")
        .instruction("Verify customer identity. Structure the application details cleanly. Ask for missing details.")
        .build();

// Loan Architect
ReActAgent loanArchitect = ReActAgent.of(chatModel)
        .name("loan_architect")
        .role("Credit Product Architect")
        .instruction("Calculate DTI (Debt-to-Income). Assign preliminary risk label: [high, mid, low].")
        .build();

Step 2: Build a Nested Risk Control Committee

In Solon AI, a TeamAgent acts as a multi-agent container. Since a team is itself an instance of Agent, it can be nested inside another TeamAgent seamlessly:

import org.noear.solon.ai.agent.team.TeamAgent;

// Risk Control Center containing multiple internal experts and a nested Credit Dept sub-team
TeamAgent riskControlCenter = TeamAgent.of(chatModel)
        .name("risk_control_center")
        .role("Deep Risk and Compliance Assessment Group")
        .agentAdd(
                // Nested sub-team (Credit Department)
                TeamAgent.of(chatModel)
                        .name("credit_dept")
                        .agentAdd(
                                ReActAgent.of(chatModel)
                                        .name("big_data_analyst")
                                        .role("Big Data Risk Modeler")
                                        .instruction("Analyze social behavior patterns and alternative credit scores.")
                                        .build()
                        ).build(),

                // Quota Calculator
                ReActAgent.of(chatModel)
                        .name("quota_calculator")
                        .role("Credit Actuary")
                        .instruction("Evaluate collateral and financial records to determine the final credit line.")
                        .build(),

                // Legal Compliance Officer
                ReActAgent.of(chatModel)
                        .name("legal_reviewer")
                        .role("AML Auditor")
                        .instruction("Cross-check PEP lists and perform Anti-Money Laundering verification.")
                        .build()
        ).build();

Step 3: Define Post-Assessment and Audit Agents

Next, define the validation, stress-testing, and sign-off actors:

ReActAgent riskStressTester = ReActAgent.of(chatModel)
        .name("risk_stress_tester")
        .role("Stress Test Engineer")
        .instruction("Simulate default probability under a +200BP interest rate shock. Set 'passed' to true/false.")
        .build();

ReActAgent securityAuditor = ReActAgent.of(chatModel)
        .name("security_auditor")
        .role("Data Privacy Auditor")
        .instruction("Verify that user data handling adheres to GDPR and national data security laws.")
        .build();

ReActAgent finalApprover = ReActAgent.of(chatModel)
        .name("final_approver")
        .role("General Manager of Credit Division")
        .instruction("Synthesize the stress test and security audit to output a final strategy: [canary, full, reject].")
        .build();

Step 4: Programmatic Flow Orchestration (`graphAdjuster`)

Now, orchestrate the interaction flow. By default, TeamAgent uses collaborative protocols (e.g., Sequential, Swarm), but for strict corporate governance, we override the topology using .graphAdjuster to build a directed workflow graph:

TeamAgent creditApprovalSystem = TeamAgent.of(chatModel)
        .name("credit_approval_system")
        .graphAdjuster(spec -> {
            // Start node routes directly to the KYC officer
            spec.addStart("start").linkAdd("entry_officer");
            spec.addActivity(entryOfficer).linkAdd("loan_architect");

            // Define conditional branching: high-risk applications route to the Wind Control Center
            spec.addExclusive("exc_risk_level")
                    .linkAdd("risk_control_center", l -> l.when("risk == 'high'"))
                    .linkAdd("risk_stress_tester");

            // Wind Control Center transitions to the Stress Tester
            spec.addActivity(riskControlCenter).linkAdd("risk_stress_tester");

            // Stress Tester branches depending on outcome. If failed (passed == false), return to Risk Center
            spec.addActivity(riskStressTester).linkAdd("exc_test_result");
            spec.addExclusive("exc_test_result")
                    .linkAdd("risk_control_center", l -> l.when("passed == false"))
                    .linkAdd("security_auditor");

            spec.addActivity(securityAuditor).linkAdd("final_approver");
            spec.addActivity(finalApprover).linkAdd("exc_release");

            // Branch to final disbursement channels
            spec.addExclusive("exc_release")
                    .linkAdd("canary_disburser", l -> l.when("route == 'canary'"))
                    .linkAdd("full_disburser", l -> l.when("route == 'full'"))
                    .linkAdd("end");

            spec.addActivity("canary_disburser").title("Canary Disbursement Channel").linkAdd("end");
            spec.addActivity("full_disburser").title("Full-Scale Disbursement Channel").linkAdd("end");
            spec.addEnd("end");
        }).build();

Running the Workflow with State Tracking

To execute our orchestrated agent network, we maintain a persistent state using AgentSession. This keeps a record of variables like risk, passed, and route, ensuring they flow correctly between nodes:

import org.noear.solon.ai.agent.AgentSession;
import org.noear.solon.ai.agent.session.InMemoryAgentSession;
import org.noear.solon.ai.chat.prompt.Prompt;
import org.noear.solon.ai.agent.team.TeamTrace;

public class App {
    public static void main(String[] args) throws Throwable {
        // Create an in-memory session for a loan application
        AgentSession session = InMemoryAgentSession.of("LOAN_ID_2026_999");

        String query = "【Urgent Loan Application】\n" +
                "Applicant: Wang Wu (Business Owner)\n" +
                "Purpose: 8 Million RMB for raw materials purchasing.\n" +
                "Note: Since this involves cross-border trade and a high limit, " +
                "please tag this as high risk. Verify disbursement via the Canary channel.";

        // Run the workflow
        String report = creditApprovalSystem.prompt(Prompt.of(query))
                .session(session)
                .call()
                .getContent();

        System.out.println("=== Final Execution Report ===\n" + report);

        // Inspect and trace the execution path
        TeamTrace trace = creditApprovalSystem.getTrace(session);
        System.out.println("\n=== Execution Path Trace ===");
        trace.getRecords().forEach(step -> 
            System.out.println("Executed Node: [" + step.getSource() + "]")
        );
    }
}

Sample Traced Path Output:

=== Execution Path Trace ===
Executed Node: [entry_officer]
Executed Node: [loan_architect]
Executed Node: [risk_control_center]
Executed Node: [risk_stress_tester]
Executed Node: [security_auditor]
Executed Node: [final_approver]
Executed Node: [canary_disburser]

Due to the applicant's status and the high transaction limit, the system dynamically rerouted the execution thread through the risk_control_center before performing stress tests and releasing funds through the canary gateway.

Architectural Advantages

Deterministic Controls for Nondeterministic LLMs: By defining structured states (using addExclusive and SpEL conditions), the workflow enforces rigid banking boundaries while allowing LLMs to handle unstructured text processing within individual nodes.
Specialized Division of Labor: High-risk calculations are isolated inside the risk_control_center micro-agent block. General tasks skip this step, optimizing latency and saving LLM token costs.
Dynamic Loop Corrections: If the stress test flags default vulnerability (passed == false), the agent automatically returns to the risk center to renegotiate security collaterals without crashing the session.
Complete Trace Audits: Since every single execution step is tracked inside TeamTrace, banking compliance officers can easily audit the trace record log, mapping out exactly which agent made which decision.

How Solon Bypasses Heavy Classpath Scanning in GraalVM Native Image using IndexFiles

Solon Framework — Mon, 17 Aug 2026 16:44:10 +0000

Classpath scanning is a ubiquitous practice in modern Java frameworks. When your application starts, the framework scans JARs, reads directories, and looks for classes annotated with @Component, @Controller, or XML mapper files.

While this dynamic approach works wonderfully on standard JVMs, it poses a severe bottleneck for GraalVM Native Images. The closed-world assumption of GraalVM mandates that all classes, reflections, and resources must be known at compile time. Furthermore, traditional classpath scanning (ClassLoader.getResources(...)) is either highly restricted or incredibly slow in a compiled native binary.

In this article, we'll dive deep into Solon's AOT (Ahead-of-Time) compilation engine and see how it solves classpath scanning under GraalVM Native Image using a lightweight, elegant mechanism called IndexFiles.

The GraalVM Native Image Dilemma

To compile a Java application into a standalone executable, GraalVM needs to build a static dependency graph starting from the main entry point. Any class accessed via reflection, any dynamic proxy, and any resource file must be registered beforehand in JSON configuration files:

reflect-config.json
resource-config.json
serialization-config.json
proxy-config.json

If your framework relies on scanning directory trees inside JAR files at runtime to discover components, it will fail under Native Image—there are no JAR files at runtime!

While some frameworks solve this by generating massive amounts of source code or bytecode during compilation, Solon takes a cleaner, more runtime-friendly approach: IndexFiles.

Introducing Solon's IndexFiles

Solon introduces org.noear.solon.core.runtime.IndexFiles, a internal helper class designed to record scans during build time and substitute them with static indexes at runtime.

The core idea is simple:

At AOT Compilation Time: Run the Solon container in a special AOT-processing mode to intercept and record all classpath scans.
Write Flat Index Files: Save these scan results into META-INF/solon-index/ as simple .index text files.
At Runtime: Bypass expensive scanning. Read the .index files directly and load the recorded classes or resources instantly.

This mechanism applies to both class scanning (discovering beans) and resource scanning (finding templates, config files, or RPC descriptors).

How It Works: Step-by-Step

Let's look at the underlying implementation details.

1. The AOT Flag Interceptor

During Solon's AOT phase, the maven/gradle plugin triggers the main execution via org.noear.solon.aot.SolonAotProcessor. The processor sets a crucial system property:

System.setProperty(NativeDetector.AOT_PROCESSING, "true");

This tells the container that it is running in build-time AOT pre-processing mode.

2. Intercepting Class Scanning

When Solon scans for beans, it uses ClassUtil.scanClasses(clzExpr). Let's look at how it behaves under the hood:

public static void scanClasses(ClassLoader classLoader, String clzExpr, Consumer<Class<?>> clzConsumer) {
    if (NativeDetector.isAotRuntime()) {
        // Build-time AOT Processing
        List<String> clzNames = new ArrayList<>();
        doScanClasses0(classLoader, clzExpr, filter, (name, clz) -> {
            clzNames.add(name);
            clzConsumer.accept(clz);
        });
        // Write the recorded scan results to an index file
        IndexFiles.writeIndexFile(clzExpr, "scan_clz", clzNames);
    } else {
        // Standard JVM or Native Image Runtime
        Collection<String> clzNames = IndexFiles.loadIndexFile(clzExpr, "scan_clz");
        if (clzNames != null) {
            // Index exists! Directly load classes from the pre-recorded index
            for (String clzName : clzNames) {
                Class<?> clz = ClassUtil.loadClass(classLoader, clzName);
                if (clz != null) {
                    clzConsumer.accept(clz);
                }
            }
            return;
        }
        // Fallback to slow scan if no index exists
        doScanClasses0(classLoader, clzExpr, filter, (name, clz) -> clzConsumer.accept(clz));
    }
}

By substituting raw scanning with a pre-built index, Solon bypasses JAR scanning entirely!

3. Intercepting Resource Scanning

The exact same logic applies to resource scanning via ResourceUtil.scanResources:

public static Collection<String> scanResources(ClassLoader classLoader, String resExpr) {
    if (NativeDetector.isAotRuntime()) {
        List<String> resList = new ArrayList<>();
        scanResources(classLoader, resExpr, resList::add);
        // Write to an index file, e.g., mapping to a "scan_res" tag
        IndexFiles.writeIndexFile(resExpr, "scan_res", resList);
        return resList;
    } else {
        List<String> resList = IndexFiles.loadIndexFile(resExpr, "scan_res");
        if (resList == null) {
            resList = new ArrayList<>();
            scanResources(classLoader, resExpr, resList::add);
        }
        return resList;
    }
}

Anatomy of an Index File

How does Solon serialize these expressions into filenames? Filesystem paths have strict character limitations, whereas package patterns or scan expressions contain wildcard asterisks (*) and colons (:).

IndexFiles.getIndexFileName safely sanitizes expressions:

Dots (.), slashes (/), and backslashes (\) are replaced with hyphens (-).
Asterisks (*) are replaced with at-signs (@).
Colons (:) are replaced with exclamation marks (!).
The filename is post-fixed with _{tag}.index.

For example, a scan expression like classpath:demo/**/*.json (mapped to tag scan_res) will generate an index file located at:
META-INF/solon-index/classpath!demo--@@-@.json_scan_res.index

Inside the file is a simple list of matching resources:

demo/config/db.json
demo/static/data.json

When running in GraalVM Native Image, ResourceUtil simply opens this text file, reads the lines, and returns the resources instantly.

Seamless GraalVM Integration

Of course, recording these files isn't enough; GraalVM needs to build these resources and reflected classes into the binary. solon-aot coordinates this.

During AOT compilation:

SolonAotProcessor invokes addResourceConfig(metadata). It automatically registers standard directories (static/.*, templates/.*, META-INF/.*) and saves the pre-scanned resource paths to solon-resource.json.
It generates resource-config.json listing the generated .index files.
It generates reflect-config.json registering the default constructors of all components recorded in scan_clz.index so GraalVM doesn't strip them away.

Solon Native Customization: `RuntimeNativeRegistrar`

Sometimes, third-party libraries perform dynamic reflections or resources scans that Solon's automated AOT processor cannot intercept.

For these cases, Solon provides the RuntimeNativeRegistrar interface. You can declare a custom component to manually register resources or reflections:

@Component
public class MyNativeRegistrar implements RuntimeNativeRegistrar {
    @Override
    public void register(AppContext context, RuntimeNativeMetadata metadata) {
        // Manually register some resources
        metadata.registerResourceInclude("my-custom-config.xml");

        // Manually register classes for serialization
        metadata.registerSerialization(MyDataTransferObject.class);

        // Register class for reflection (constructors + methods)
        metadata.registerReflection(MyLegacyService.class, 
            MemberCategory.INVOKE_DECLARED_CONSTRUCTORS, 
            MemberCategory.INVOKE_DECLARED_METHODS
        );
    }
}

This bean is automatically collected during AOT compilation and injected into the GraalVM metadata compilation suite.

Summary: Performance Benefits

By substituting runtime Classpath/JAR scanning with compile-time index generation, Solon achieves:

Near-Zero Scanning Overhead: No CPU cycles are wasted traversing JAR directories during startup.
GraalVM native compatibility: Seamlessly translates classpath wildcard scans (classpath:com/demo/**/*.class) into predictable, static lookups that satisfy GraalVM's closed-world restrictions.
Incredibly Fast Startup: Solon applications typically boot in 0.1 to 0.2 seconds on standard JVMs, and under 2 to 5 milliseconds as compiled GraalVM native binaries.

Solon's AOT compiler demonstrates that achieving GraalVM native support doesn't require rewriting your code or producing messy generated classes—sometimes, a simple index is all you need to keep things clean, simple, and blazing fast.

DEV Community: Solon Framework

Rerun and Continue in SolonCode Web — Two Buttons, Two Semantics

The two buttons at a glance

Re-run (重新运行): replay the turn, delete the old answer

What you see

What the code does

When to use Re-run

Continue (继续运行): extend the response, keep what's there

What you see

What the code does

When to use Continue

Side-by-side comparison

A concrete example

How the commands are exposed

Under the hood: the runId linkage

Summary

Spring AI vs Solon AI - Building Agents and Handling Agent Events

Part 1: Building Agents

Spring AI: The Agent Is a Pattern, Not a Type

Solon AI: Agents Are First-Class Citizens

Part 2: Events and Observability

Spring AI: Observability via Micrometer, Not an Event Stream

Solon AI: A Typed Event Stream Plus Lifecycle Interceptors

The Philosophical Difference in One Table

Which One Fits?

Further Reading

Spring AI vs Solon AI - A Practical Comparison for Java Developers

What They Share

Difference #1: The Ecosystem Contract

Difference #2: API Style — Advisor Chain vs. Builder + Agent

Difference #3: Tool Calling

Difference #4: Structured Output

Difference #5: RAG

Difference #6: Memory

Difference #7: Agents and Orchestration

Difference #8: MCP

Difference #9: Runtime Footprint

Summary Table

Which One Should You Pick?

References

Give Your Java Agents a Memory - Session Management with Solon AI

The problem with hand-rolled memory

ChatSession: the message ledger

AgentSession: memory plus workflow state

Attaching a session to an agent

Pluggable backends

One provider to route them all

Windows, not truncation

Closing thoughts

From Messy Text to Reliable Java Objects - Structured Output Extraction with Solon AI

The problem with "please return JSON"

Step 1: Declare the target type

Step 2: Attach the schema and call

How the schema reaches the model

How the answer comes back

What you do NOT get for free

Step 3: Promote to an extraction agent

Where the pieces live

Beyond invoices and résumés

Wrapping up

Integrating External Tool Ecosystems with Solon AI's MCP Protocol

The Problem: Tool Sprawl in AI Applications

What is MCP?

Solon AI's MCP Integration

Server Side: Exposing Tools via MCP

Client Side: Using Remote Tools as Local Beans

Transport Options

Real-World Use Case: Multi-Source Financial Analysis

Advanced: Stateful vs Stateless Servers

Security Considerations

The Bigger Picture

Getting Started

Conclusion

The Solon AI Talent System: Solving Real Business Problems with Composable Agent Capabilities

What a Talent actually is

The built-in Talent ecosystem

Business scenario 1: automated report delivery

Business scenario 2: multi-platform team notification

Business scenario 3: self-improving agent with long-term memory

The mount system: connecting Talents to the filesystem

Step 4: Programmatic Flow Orchestration (`graphAdjuster`)

Solon Native Customization: `RuntimeNativeRegistrar`