DEV Community: Solon Framework

Agent RAG in Solon: Make Retrieval a Tool, Not a One-Shot Pre-Step

Solon Framework — Thu, 16 Jul 2026 13:52:55 +0000

Most RAG demos stop at one search. You embed a question, pull top-k chunks, paste them into a prompt, and hope the first hit was enough. That works for FAQ pages. It fails when the first query is vague, the right facts are split across documents, or the model needs a second, more precise lookup.

Solon AI calls the upgrade Agent RAG: retrieval is no longer a fixed pre-step. It becomes a tool the model can call zero or more times inside a ReAct loop.

This article sticks to official Solon v4.0.3 APIs from the RAG and Agent docs.

Passive RAG vs Agent RAG

Mode	Flow	Who decides to search?	Retry if context is weak?
Passive RAG	search → augment → generate	Your code, always once	No
Agent RAG	Thought → tool search → Observation → …	The model	Yes, multi-round

Passive RAG is still useful. Agent RAG is what you want when answers need iterative retrieval.

1. Build a small knowledge base

Same building blocks as classic Solon RAG: embedding model, storable repository, load + split + save.

import org.noear.solon.ai.embedding.EmbeddingModel;
import org.noear.solon.ai.rag.Document;
import org.noear.solon.ai.rag.loader.TextLoader;
import org.noear.solon.ai.rag.repository.InMemoryRepository;
import org.noear.solon.ai.rag.splitter.RegexTextSplitter;
import org.noear.solon.ai.rag.splitter.SplitterPipeline;
import org.noear.solon.ai.rag.splitter.TokenSizeTextSplitter;

import java.net.URI;
import java.util.List;

EmbeddingModel embeddingModel = EmbeddingModel.of(embeddingApiUrl)
        .apiKey(embeddingApiKey)
        .model(embeddingModelName)
        .build();

InMemoryRepository repository = new InMemoryRepository(embeddingModel);

// Load → split → save
List<Document> documents = new SplitterPipeline()
        .next(new RegexTextSplitter("\n\n"))
        .next(new TokenSizeTextSplitter(500))
        .split(new TextLoader(URI.create("https://example.com/policy.txt")).load());

repository.save(documents);

InMemoryRepository is fine for demos. Production can swap in Milvus, Redis, Elasticsearch, Qdrant, and other repository plugins without changing the Agent wiring below.

2. Passive RAG still has a clean path

When one search is enough, keep the pipeline explicit:

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

List<Document> context = repository.search(question);
ChatMessage prompt = ChatMessage.ofUserAugment(question, context);

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

Or let the repository do the one-shot augment:

ChatMessage prompt = repository.promptAugment(question);

This is the classic “retrieve then generate” path. No agent required.

3. Turn the repository into a tool

Agent RAG starts when search becomes a callable tool. Official docs introduce RepositoryTool for that (available since Solon AI 3.10.1):

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

RepositoryTool repositoryTool = new RepositoryTool(repository);

Stage A — ChatModel with tools

The model decides whether to search at all:

ChatModel chatModel = ChatModel.of(chatApiUrl)
        .apiKey(chatApiKey)
        .model(chatModelName)
        .defaultToolAdd(repositoryTool)
        .build();

chatModel.prompt("What is the refund window for lost packages?").call();

Stage B — ReActAgent for multi-hop retrieval

For harder questions, upgrade to ReAct so the model can search, rethink, and search again:

import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.session.InMemoryAgentSession;

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(repositoryTool)
        .sessionWindowSize(8)
        .maxTurns(10)
        .build();

String answer = agent.prompt(
                "Customer paid 158 yuan. Package marked lost at Shanghai hub. "
                        + "What policy applies and what should support do next?"
        )
        .session(InMemoryAgentSession.of("support_user_42"))
        .call()
        .getContent();

That is the heart of Agent RAG in Solon:

Knowledge lives in a Repository
RepositoryTool exposes it as a tool
ReActAgent runs Thought → Action → Observation until it has enough evidence

4. Mix knowledge search with business tools

Real support agents need more than docs. They also need order APIs, logistics APIs, and compensation actions. Solon tools are just ToolProviders — knowledge tools and domain tools hang on the same agent.

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

public class OrderTools extends AbsToolProvider {
    @ToolMapping(description = "Look up order amount and tracking number by order id")
    public String get_order(@Param(description = "order id") String orderId) {
        // call your order service
        return "{\"orderId\":\"" + orderId + "\",\"amount\":158.0,\"trackNo\":\"track_123\"}";
    }
}

public class LogisticTools extends AbsToolProvider {
    @ToolMapping(description = "Get logistics status by tracking number")
    public String get_logistic_status(@Param(description = "tracking number") String trackNo) {
        return "{\"status\":\"lost\",\"info\":\"lost at Shanghai hub\"}";
    }
}

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(repositoryTool)   // policy / FAQ knowledge
        .defaultToolAdd(new OrderTools())
        .defaultToolAdd(new LogisticTools())
        .modelOptions(o -> o.temperature(0.0))
        .maxTurns(10)
        .build();

Typical loop the model may invent:

Search policy for “lost package refund”
Call get_order
Call get_logistic_status
Answer with both policy text and operational next step

No custom orchestrator graph required for this pattern.

5. Keep multi-turn memory under control

Agent RAG often spans several user turns. Solon separates session storage from window size:

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(repositoryTool)
        .sessionWindowSize(5) // only recent messages go to the LLM
        .build();

// Isolate users by session id
agent.prompt("Continue from the last ticket.")
        .session(InMemoryAgentSession.of("user_123"))
        .call();

Built-in session backends (official comparison):

Class	Storage	When to use
`InMemoryAgentSession`	Local map	Dev / tests
`FileAgentSession`	Local files	CLI / single-node tools
`RedisAgentSession`	Redis	Multi-node production

sessionWindowSize is short-term history for the model. Long knowledge still lives in the repository, not in the chat transcript.

6. Optional hybrid senses

When internal docs are not enough, official Agent RAG samples also attach web/code tools from the skill ecosystem:

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(repositoryTool)
        .defaultToolAdd(new CodeSearchTool())
        .defaultToolAdd(new WebsearchTool())
        .defaultToolAdd(new WebfetchTool())
        .build();

Use this carefully in production: each extra tool increases tool-selection noise. Start with repository + domain APIs; add web tools only when the product needs live external facts.

A practical decision guide

Situation	Prefer
Fixed FAQ, one clear query	Passive RAG (`search` + `ofUserAugment`)
Vague question, multi-hop facts	Agent RAG (`RepositoryTool` + `ReActAgent`)
Docs + order/logistics actions	Agent RAG + `AbsToolProvider` tools
Long chat with same user	`AgentSession` + `sessionWindowSize`
Clustered app servers	`RedisAgentSession`

What not to invent

Do not fake a custom implements Tool protocol for knowledge search when RepositoryTool already wraps the repository.
Do not put entire policy PDFs into the system prompt “for simplicity” — load, split, and store them.
Do not confuse Harness memory (coding-agent long-term facts) with business RAG. For product Q&A, start from Repository + Agent tools.

Official references (Solon v4.0.3)

Takeaway

In Solon, Agent RAG is not a second product. It is a composition rule:

Repository (facts) + RepositoryTool (search action) + ReActAgent (decision loop).

Start passive when one search is enough. Flip the repository into a tool when the model must decide if, when, and how to retrieve — and keep domain tools on the same agent when answers must become actions.

Wire Remote MCP Tools into Solon ReActAgent with McpClientProvider

Solon Framework — Thu, 16 Jul 2026 13:33:46 +0000

Most teams start with local tools wired into a ReAct agent. That works until the weather API, CRM connector, or warehouse service lives in another process — or another team’s service.

Solon AI treats MCP clients as first-class tool providers. A remote MCP server can be plugged into ReActAgent the same way a local AbsToolProvider is: one defaultToolAdd(...), no custom RPC glue.

This walkthrough uses only official Solon v4.0.3 APIs.

The idea in one sentence

McpClientProvider implements ToolProvider.

ReActAgent accepts any ToolProvider.

Therefore: remote MCP tools join the Reason → Act loop without a special agent type.

MCP Server (tools over streamable/sse/stdio)
        │
        ▼
McpClientProvider  ──implements──►  ToolProvider
        │
        ▼
ReActAgent.defaultToolAdd(mcpClient)
        │
        ▼
Thought → Action(tool call) → Observation → ...

1. Publish a small MCP tool server

Same pattern as the official weather sample: annotate a class with @McpServerEndpoint, expose methods with @ToolMapping.

import org.noear.solon.Solon;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;
import org.noear.solon.annotation.Param;

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

    // Prefer compile with -parameters so arg names are preserved
    @ToolMapping(description = "Query weather forecast for a city")
    public String getWeather(@Param(description = "City location") String location) {
        return "Sunny, 14°C in " + location;
    }
}

public class WeatherMcpApp {
    public static void main(String[] args) {
        Solon.start(WeatherMcpApp.class, args);
    }
}

Maven dependency:

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

STREAMABLE is the preferred HTTP channel today (single endpoint, long-lived session). SSE still works but is marked deprecated in the docs. Use STREAMABLE_STATELESS when you need short-lived, cluster-friendly HTTP without sticky sessions.

2. Build the MCP client (singleton)

Official guidance: McpClientProvider holds long-lived connections — use a singleton, or call close() when you are done.

import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.client.McpClientProvider;

McpClientProvider weatherMcp = McpClientProvider.builder()
        .channel(McpChannel.STREAMABLE)
        .url("http://localhost:8080/mcp")
        .cacheSeconds(30)          // tool metadata cache
        // .heartbeatInterval(null) // default is 15s; null disables heartbeat
        .build();

You can also smoke-test tools without an agent:

String raw = weatherMcp
        .callTool("getWeather", Map.of("location", "Hangzhou"))
        .getContent();

McpClientProvider exposes three content types through standard interfaces:

Interface	What you get
`ToolProvider`	Remote tools for models / agents
`ResourceProvider`	Remote resources
`PromptProvider`	Remote prompts
`Closeable`	Release connection; stops auto-reconnect

3. Plug MCP into ReActAgent

Local domain tools stay AbsToolProvider + @ToolMapping. Remote tools are just another provider.

import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.session.InMemoryAgentSession;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.tool.AbsToolProvider;
import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.client.McpClientProvider;
import org.noear.solon.annotation.Param;

public class LocalOrderTools extends AbsToolProvider {

    @ToolMapping(description = "Look up order city by order id")
    public String get_order_city(@Param(description = "Order id") String orderId) {
        if ("ORD_20251229".equals(orderId)) {
            return "Hangzhou";
        }
        return "unknown";
    }
}

// remote weather service
McpClientProvider weatherMcp = McpClientProvider.builder()
        .channel(McpChannel.STREAMABLE)
        .url("http://localhost:8080/mcp")
        .build();

ChatModel chatModel = /* your model */;

ReActAgent agent = ReActAgent.of(chatModel)
        .name("ops_assistant")
        .role("Operations assistant that checks orders and live weather")
        .defaultToolAdd(new LocalOrderTools()) // local tools
        .defaultToolAdd(weatherMcp)            // remote MCP tools
        .maxTurns(8)
        .autoRethink(true)
        .modelOptions(o -> o.temperature(0.1))
        .build();

var session = InMemoryAgentSession.of("demo_mcp_react_001");

String answer = agent.prompt(
                "Order ORD_20251229 is delayed. Check the destination city weather " +
                "and suggest whether outdoor delivery is still safe today.")
        .session(session)
        .call()
        .getContent();

System.out.println(answer);

What happens at runtime:

The model sees both local and remote tool descriptions.
It may call get_order_city (local), then getWeather (MCP).
Observations come back into the ReAct loop as normal tool messages.
The agent finishes with a natural-language recommendation.

No adapter layer. No “MCP-only agent”. Same defaultToolAdd surface as the official e-commerce after-sales sample.

4. Same provider also works on ChatModel

If you do not need multi-step ReAct yet, bind MCP tools directly to the chat model:

ChatModel chatModel = ChatModel.of(chatConfig)
        .defaultToolAdd(weatherMcp) // McpClientProvider is a ToolProvider
        .build();

String reply = chatModel.prompt("How is the weather in Hangzhou today?")
        .call()
        .getMessage()
        .getContent();

Per-call attachment is also valid:

chatModel.prompt("How is the weather in Hangzhou today?")
        .options(o -> o.toolAdd(weatherMcp))
        .call();

5. Config-driven clients (production style)

Hard-coding URLs is fine for demos. In apps, inject clients from config:

solon.ai:
  chat:
    demo:
      apiUrl: "http://127.0.0.1:11434/api/chat"
      model: "qwen2.5:1.5b"
  mcp:
    client:
      weather:
        channel: "streamable"
        url: "http://localhost:8080/mcp"
      crm:
        channel: "streamable"
        url: "http://crm-internal.example/mcp"

import org.noear.solon.annotation.Bean;
import org.noear.solon.annotation.Configuration;
import org.noear.solon.annotation.Inject;
import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.chat.ChatConfig;
import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.mcp.client.McpClientProvider;

@Configuration
public class AgentConfig {

    @Bean
    public McpClientProvider weatherMcp(
            @Inject("${solon.ai.mcp.client.weather}") McpClientProvider client) {
        return client; // singleton bean
    }

    @Bean
    public ChatModel chatModel(@Inject("${solon.ai.chat.demo}") ChatConfig cfg) {
        return ChatModel.of(cfg).build();
    }

    @Bean
    public ReActAgent opsAgent(ChatModel chatModel,
                               McpClientProvider weatherMcp,
                               McpClientProvider crmMcp) {
        return ReActAgent.of(chatModel)
                .name("ops_assistant")
                .role("Operations assistant")
                .defaultToolAdd(weatherMcp)
                .defaultToolAdd(crmMcp)
                .maxTurns(10)
                .autoRethink(true)
                .build();
    }
}

Adding a third-party MCP service becomes a config change, not a rewrite of agent code.

6. Heartbeat, reconnect, and lifecycle

MCP sessions are long-lived (the server may call back for notifications or sampling). Solon MCP clients therefore:

Send heartbeat pings (default interval 15s)
On network error or failed heartbeat, retry reconnect on the next request
Stop reconnecting after close()

// disable heartbeat when an external client cannot tolerate ping frames
McpClientProvider client = McpClientProvider.builder()
        .channel(McpChannel.STREAMABLE)
        .url("http://localhost:8080/mcp")
        .heartbeatInterval(null)
        .build();

// later, when the process shuts down
client.close();
// or reopen after intentional close
// client.reopen();

Practical rules:

Prefer one client instance per remote server.
Close clients on app shutdown hooks.
Keep cacheSeconds modest so tool list updates are visible without hammering the server.
Treat remote tools as untrusted I/O: still gate high-risk actions with HITL if needed (separate interceptor topic).

7. Channel cheat sheet

Channel	Session	Link style	Notes
`stdio`	yes	process pipes	One stdio endpoint per process; no console log noise on server
`sse`	yes	long-lived HTTP (2 endpoints)	Works; docs mark it deprecated
`streamable`	yes	long-lived HTTP (1 endpoint)	Default choice for remote services
`streamable_stateless`	yes (client) / short HTTP	short-lived	Cluster-friendly, no sticky routing required

Developer experience is the same; only the channel (and endpoint path) changes.

8. Why this composition matters

Approach	Cost
Wrap every third-party API as local `@ToolMapping`	Own every connector forever
Hand-roll HTTP clients inside tools	Duplicate auth, retry, schema work
MCP server + `McpClientProvider`	Publish once, consume from ChatModel / ReActAgent / multiple apps

ReAct still owns the decision loop. MCP only supplies arms and legs that can live outside the JVM.

Minimal checklist

[ ] Server: @McpServerEndpoint + @ToolMapping
[ ] Client: McpClientProvider.builder().channel(...).url(...).build()
[ ] Agent: ReActAgent.of(model).defaultToolAdd(mcpClient)...build()
[ ] Lifecycle: singleton client + close() on shutdown
[ ] Optional: YAML solon.ai.mcp.client.* injection for multi-server fleets

References (official)

Framework version referenced: Solon v4.0.3.

Plan-ReAct for Solon Agents: Draft the Map Before the Tool Loop

Solon Framework — Mon, 13 Jul 2026 06:15:28 +0000

If a ReAct agent jumps straight into tool calls on a multi-step job, it often thrashs: repeats searches, forgets earlier observations, or finishes with a half-done answer.

Solon AI’s answer is Plan-ReAct (also called Plan-and-Solve / Plan-Execute in the docs). Before the Reason → Act loop starts, the agent first drafts a global plan, then executes against that plan with progress awareness.

This post is a practical walkthrough using only official Solon APIs (docs checked against Solon v4.0.3).

Why plan first?

Plain ReAct is local decision-making: each turn picks the next tool from the latest thought. That works for short chains (“check order → check logistics”), but large goals (“research a topic and write a structured brief”) benefit from a map:

Without planning	With Plan-ReAct
Local next-step only	Global plan before action
Easy to drift after a noisy tool result	Plan acts like a navigator
Hard to show progress in UI	`getPlans()` / `getPlanProgress()` expose checklist state
Fuzzy goals stay fuzzy	Large goal is broken into ordered sub-tasks

Official docs emphasize three gains: anti-noise, progress awareness (Step N/M), and logical decomposition.

Minimal enablement

Planning is a single switch on ReActAgent:

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

ReActAgent agent = ReActAgent.of(chatModel)
        .name("researcher")
        .role("Senior research assistant")
        // 1) turn on planning before Reason/Act
        .planningMode(true)
        // 2) optional: custom planning instruction (defaults are usually enough)
        .planningInstruction(trace ->
                "Break the task into ordered steps and execute them in sequence.")
        .defaultToolAdd(new ResearchTools())
        .maxTurns(12)
        .autoRethink(true)
        .modelOptions(o -> o.temperature(0.2))
        .build();

// Agent emits [Plans] first, then reasons and acts
var resp = agent.prompt(
        "Investigate recent Solon AI Agent capabilities and write a short brief " +
        "covering ReActAgent, TeamAgent, and HITL."
).call();

System.out.println(resp.getContent());

You can also enable planning per call without baking it into the builder:

var resp = agent.prompt("Investigate Solon AI Agent capabilities and write a short brief")
        .options(o -> o.planningMode(true)
                       .maxTurns(12)
                       .temperature(0.2))
        .call();

That per-call form is useful when simple queries stay on plain ReAct, and only heavy tasks pay for an extra planning LLM turn.

Domain tools stay boring (on purpose)

Plan-ReAct does not invent a special tool type. Domain tools remain AbsToolProvider + @ToolMapping, the same pattern as the official e-commerce after-sales sample:

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

public class ResearchTools extends AbsToolProvider {

    @ToolMapping(description = "Search documentation notes by keyword")
    public String search_docs(@Param(description = "Search keyword") String keyword) {
        if (keyword.toLowerCase().contains("react")) {
            return "ReActAgent: Thought -> Action -> Observation loop; supports planningMode, HITL, maxTurns.";
        }
        if (keyword.toLowerCase().contains("team")) {
            return "TeamAgent: multi-agent container with protocols such as SEQUENTIAL and HIERARCHICAL.";
        }
        if (keyword.toLowerCase().contains("hitl")) {
            return "HITLInterceptor can pause sensitive tools before execution for human review.";
        }
        return "No matching notes for: " + keyword;
    }

    @ToolMapping(description = "Save a research note for later synthesis")
    public String save_note(
            @Param(description = "Note title") String title,
            @Param(description = "Note body") String body) {
        return "Saved note: " + title + " (" + body.length() + " chars)";
    }
}

Wire them with defaultToolAdd(new ResearchTools()). No custom implements Tool, no fictional harness wrapper.

Observability: plans are first-class on the trace

After planning is enabled, ReActTrace keeps a plan stack. Official methods:

Method	Use
`getPlans()`	Raw plan list for UI checklists
`getFormattedPlans()`	Markdown-style list injected back into prompts
`getPlanProgress()`	“You are on step 2 of 5” style progress text

Example after a call:

var trace = resp.getTrace();

// Show checklist in an ops console / chat UI
System.out.println("Plans:\n" + trace.getFormattedPlans());
System.out.println("Progress: " + trace.getPlanProgress());

// Or iterate structured plan items if you build a richer UI
trace.getPlans().forEach(step -> System.out.println("- " + step));

This is the production win: users stop staring at a blank spinner and can see what the agent thinks it still needs to do.

Interceptor hook for planning events

If you already use ReActInterceptor for thoughts and tool calls, planning has its own callback:

import org.noear.solon.ai.agent.react.ReActInterceptor;
import org.noear.solon.ai.agent.react.ReActTrace;
import org.noear.solon.ai.chat.message.AssistantMessage;

ReActAgent agent = ReActAgent.of(chatModel)
        .planningMode(true)
        .defaultToolAdd(new ResearchTools())
        .defaultInterceptorAdd(new ReActInterceptor() {
            @Override
            public void onPlan(ReActTrace trace, AssistantMessage message) {
                System.out.println("Plan draft:\n" + message.getContent());
            }

            @Override
            public void onThought(ReActTrace trace, String thoughtContent, AssistantMessage assistantMessage) {
                System.out.println("Thought: " + thoughtContent);
                System.out.println("Progress: " + trace.getPlanProgress());
            }
        })
        .build();

Use onPlan to audit plan quality, push the checklist to a frontend channel, or reject obviously bad plans before heavy tool spend.

Structured output on top of planning

When the final brief must feed another service, combine planning with outputSchema (supported on SimpleAgent / ReActAgent):

public class ResearchBrief {
    public String title;
    public String summary;
    public java.util.List<String> key_points;
    public java.util.List<String> open_questions;
}

ReActAgent agent = ReActAgent.of(chatModel)
        .name("brief_writer")
        .role("High-precision research synthesizer")
        .instruction("Use tools to gather facts, then emit only schema-compliant JSON.")
        .planningMode(true)
        .outputSchema(ResearchBrief.class)
        .defaultToolAdd(new ResearchTools())
        .maxTurns(10)
        .build();

ResearchBrief brief = agent.prompt(
                "Produce a research brief on Solon AI agent collaboration patterns.")
        .call()
        .toBean(ResearchBrief.class);

System.out.println(brief.title);
System.out.println(brief.summary);

Planning keeps the multi-step work coherent; outputSchema keeps the hand-off machine-readable.

When not to enable planning

Official guidance is clear: planning costs an extra LLM call. Skip it for trivial prompts (“what time is it?”, single-tool lookups). A practical rule:

1–2 tool hops, clear goal → plain ReAct
Multi-source research / multi-phase write-up → planningMode(true)
Money / irreversible side effects → planning plus HITL on sensitive tools

boolean needsPlan = taskType == TaskType.RESEARCH || taskType == TaskType.MULTI_PHASE;

var call = agent.prompt(userText);
if (needsPlan) {
    call = call.options(o -> o.planningMode(true).maxTurns(12));
}
var resp = call.call();

Production checklist

Prefer stronger reasoning models for planning (docs call out heavy-logic models).
Cap loops with maxTurns and keep autoRethink(true) as a safety net.
Surface getPlans() / getPlanProgress() in the UI early—it reduces “is it stuck?” tickets.
Keep tools as AbsToolProvider + @ToolMapping; planning is orchestration, not a new tool SPI.
Combine with HITL when a planned step reaches a sensitive tool.
Use per-call .options(o -> o.planningMode(true)) so cheap chats stay cheap.

References (official)

Plan-ReAct: https://solon.noear.org/article/1342
ReActAgent options: https://solon.noear.org/article/1347
ReActAgent config & build: https://solon.noear.org/article/1293
Identity / outputSchema: https://solon.noear.org/article/1315
Domain tools sample (after-sales): https://solon.noear.org/article/1285
Project: https://github.com/opensolon/solon

Plan-ReAct will not fix a bad tool surface, but it stops multi-step agents from improvising themselves into a corner. Turn it on when the job needs a map—not when the job is a single street.

Human-in-the-Loop for Solon ReActAgent: Pause Risky Tools Before They Run

Solon Framework — Sun, 12 Jul 2026 03:56:45 +0000

Most teams can get an AI agent to call tools. The hard part starts when the tool can move money, delete data, or send irreversible messages.

That is where Human-in-the-Loop (HITL) stops being a slide-deck concept and becomes a product requirement. Solon AI ships this as a first-class interceptor on ReActAgent: the agent reasons and acts as usual, but sensitive tool calls can be paused, reviewed, corrected, and resumed without rebuilding the whole conversation.

This post walks through a production-shaped pattern using only official Solon APIs (current docs against Solon v4.0.3).

Why HITL belongs in the agent loop

A naive design puts approval outside the agent:

agent finishes
your service notices a risky side effect
you try to roll it back

That is usually too late. Solon places HITL on the ReAct lifecycle itself:

on Action: before a tool runs, decide whether to interrupt
on Observation: after a tool runs, inject human comments back into the agent’s next thought

So the break point is exact: the model has already chosen transfer(amount=2000), but the tool has not executed yet.

The four building blocks

From the official HITL docs, the model is intentionally small:

Piece	Role
`HITLInterceptor`	Declares which tools need review
`HITLTask`	Snapshot of tool name + args for the approver UI
`HITLDecision`	Approve / reject / skip + optional arg fixes
`HITL`	Business-layer helpers: `getPendingTask`, `submit`, `approve`, `reject`

You do not invent a custom implements Tool interface or wrap business agents in a fictional harness. Domain tools stay as AbsToolProvider + @ToolMapping.

Step 1: Domain tools the agent can actually use

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

public class FinanceTools extends AbsToolProvider {

    @ToolMapping(description = "Query account balance by user id")
    public String get_balance(@Param(description = "User id") String userId) {
        return "{\"userId\":\"" + userId + "\",\"balance\":5200.00,\"currency\":\"CNY\"}";
    }

    @ToolMapping(description = "Transfer money to another account")
    public String transfer(
            @Param(description = "Source user id") String fromUserId,
            @Param(description = "Target account") String toAccount,
            @Param(description = "Amount") double amount) {
        return "Transfer accepted: " + amount + " -> " + toAccount;
    }
}

This matches the official domain-tool style used in the e-commerce after-sales sample: provider class + annotated methods, then defaultToolAdd(...).

Step 2: Register sensitive tools with HITLInterceptor

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

ChatModel chatModel = LlmUtil.getChatModel();

HITLInterceptor hitl = new HITLInterceptor()
        // always pause these tools
        .onSensitiveTool("transfer")
        // or pause only when the amount crosses a threshold
        .onTool("transfer", (trace, args) -> {
            double amount = Double.parseDouble(args.get("amount").toString());
            return amount > 1000 ? "Large transfer needs human approval" : null;
        });

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(new FinanceTools())
        .defaultInterceptorAdd(hitl)
        .maxTurns(10)
        .build();

Two useful patterns from the docs:

onSensitiveTool(...) — any call is pending
onTool(name, strategy) — return a reason string to interrupt, or null to let it pass

That keeps low-risk automation fast while still fencing the dangerous path.

Step 3: Expose ask / task / approve over HTTP

import org.noear.solon.annotation.*;
import org.noear.solon.ai.agent.AgentSession;
import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.react.ReActResponse;
import org.noear.solon.ai.agent.react.intercept.*;
import org.noear.solon.ai.agent.session.InMemoryAgentSession;
import org.noear.solon.core.handle.Result;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

@Controller
@Mapping("/ai/hitl")
public class HitlWebController {

    private final Map<String, AgentSession> sessions = new ConcurrentHashMap<>();

    private final ReActAgent agent = ReActAgent.of(LlmUtil.getChatModel())
            .defaultToolAdd(new FinanceTools())
            .defaultInterceptorAdd(new HITLInterceptor()
                    .onTool("transfer", (trace, args) -> {
                        double amount = Double.parseDouble(args.get("amount").toString());
                        return amount > 1000 ? "Large transfer approval" : null;
                    }))
            .build();

    private AgentSession sessionOf(String sid) {
        return sessions.computeIfAbsent(sid, InMemoryAgentSession::of);
    }

    @Post
    @Mapping("ask")
    public Result ask(String sid, String prompt) throws Throwable {
        AgentSession session = sessionOf(sid);
        ReActResponse resp = agent.prompt(prompt).session(session).call();

        if (resp.getTrace().isPending()) {
            return Result.failure("REQUIRED_APPROVAL", HITL.getPendingTask(session));
        }
        return Result.succeed(resp.getContent());
    }

    @Get
    @Mapping("task")
    public HITLTask task(String sid) {
        return HITL.getPendingTask(sessionOf(sid));
    }

    @Post
    @Mapping("approve")
    public Result approve(String sid, String action, @Body Map<String, Object> modifiedArgs)
            throws Throwable {
        AgentSession session = sessionOf(sid);
        HITLTask task = HITL.getPendingTask(session);
        if (task == null) {
            return Result.failure("No pending task");
        }

        HITLDecision decision;
        if ("approve".equals(action)) {
            decision = HITLDecision.approve().comment("Verified by operator");
            if (modifiedArgs != null && !modifiedArgs.isEmpty()) {
                decision.modifiedArgs(modifiedArgs);
            }
        } else {
            decision = HITLDecision.reject("Rejected by operator");
        }

        HITL.submit(session, task.getToolName(), decision);

        // resume from the breakpoint; no need to resend the original prompt
        ReActResponse resp = agent.prompt().session(session).call();
        return Result.succeed(resp.getContent());
    }
}

This is the production shape:

ask runs the agent
if resp.getTrace().isPending(), return the HITLTask to your admin UI
approve writes a HITLDecision
call agent.prompt().session(session).call() again to continue

The closed loop in plain language

Imagine the user says: “Transfer 2000 to account A10086.”

Trigger — ReAct plans, then tries transfer(...). The interceptor stores a HITLTask and interrupts.
Review — an operator opens the pending task, sees tool name + args.
Decide
- approve as-is: HITL.approve(session, "transfer")
- reject: HITL.reject(session, "transfer", "account anomaly")
- fix args, then approve:

HITL.submit(session, "transfer",
        HITLDecision.approve()
                .modifiedArgs(Map.of("toAccount", "correct_888")));

Resume — the next call() consumes the decision, runs (or skips) the tool, and the agent produces the final answer from a real observation.

Design notes that matter in production

1) Put HITL on the worker, not the narrator

If you later compose agents with TeamAgent, keep the interceptor on the ReActAgent that actually owns the sensitive tool. Team collaboration can suspend through the same pending mechanism, but the tool fence still lives at the acting agent.

2) Session storage is part of the product

InMemoryAgentSession is perfect for demos. For multi-instance deployments, swap in a shared AgentSession implementation so pending tasks survive restarts and stick to the same conversation id.

3) Prefer threshold policies over “approve everything”

onSensitiveTool is blunt and safe. onTool with a predicate keeps small automated refunds / transfers flowing while still catching the expensive mistakes.

4) Don’t fake business ROI numbers

HITL’s value is operational: fewer irreversible mistakes, auditable breakpoints, human correction of bad tool args. Keep claims qualitative unless you have your own measured baseline.

Minimal checklist before you ship

[ ] Tools are AbsToolProvider + @ToolMapping
[ ] Risky tools registered via HITLInterceptor
[ ] API returns pending tasks when trace.isPending()
[ ] Approvals go through HITL.submit / approve / reject
[ ] Resume uses the same AgentSession without replaying the user prompt
[ ] Session backend matches your deployment topology

Where to read next

Official docs used for this article:

ReActAgent overview: solon.noear.org/article/1282
E-commerce after-sales tool style: solon.noear.org/article/1285
HITL guide: solon.noear.org/article/1329
HITL web sample: solon.noear.org/article/1286
Agent selection (Simple / ReAct / Team): solon.noear.org/article/1320

If you are building agents that only chat, you may not need HITL. The moment your agent can spend money or change production state, you do.

Building Your First MCP Server with Solon: A 5-Minute Hello World

Solon Framework — Thu, 09 Jul 2026 11:59:38 +0000

Building Your First MCP Server with Solon: A 5-Minute Hello World

If you've been following the AI tooling space, you've probably heard about MCP (Model Context Protocol) — the open standard that lets AI models interact with external tools and data sources. It's been called "the USB-C for AI" and for good reason.

But here's the thing: setting up an MCP server from scratch can be surprisingly verbose. The official SDK requires you to wire up transports, capability negotiation, and tool specifications by hand.

Solon's approach is different. With @McpServerEndpoint, the whole thing collapses into a single annotated class. Let me show you.

What We're Building

A simple MCP server that exposes a hello tool. The server will:

Start on port 8080
Expose a MCP endpoint at /mcp
Use the STREAMABLE transport (the modern MCP protocol)
Provide a hello tool that takes a name and returns a greeting

Step 1: Add the Dependency

Add the MCP module to your pom.xml:

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

That's it. One dependency gives you server, client, and all transport types. No extra SDKs to wire up.

Step 2: Create the Server

Create a class and annotate it with @McpServerEndpoint:

import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;
import org.noear.solon.annotation.Param;

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

    @ToolMapping(description = "Say hello to someone")
    public String hello(@Param(name = "name", description = "The person's name") String name) {
        return "Hello, " + name + "!";
    }
}

That's the entire server. Let me break down what's happening:

@McpServerEndpoint — Tells Solon this class is an MCP server endpoint. The channel parameter specifies the transport protocol (STREAMABLE is the modern MCP 2025-03-26+ standard). The mcpEndpoint is the URL path.
@ToolMapping — Declares this method as an MCP tool. The description is passed to the AI model so it knows when to use this tool.
@Param — Describes each parameter. The model uses this to generate the correct arguments.
McpChannel.STREAMABLE — The current MCP standard transport. It supports streaming responses and is the recommended channel for new projects.

Step 3: Start the Application

import org.noear.solon.Solon;

public class McpServerApp {
    public static void main(String[] args) {
        Solon.start(McpServerApp.class, args);
    }
}

Solon's component scanner will automatically discover the @McpServerEndpoint class and register it as a real MCP service. No XML, no config classes, no @Bean declarations.

Step 4: Connect with a Client

Once the server is running on port 8080, you can connect with the MCP client:

import org.noear.solon.ai.mcp.client.McpClientProvider;
import java.util.Map;

public class McpClientDemo {
    public static void main(String[] args) {
        McpClientProvider client = McpClientProvider.builder()
                .channel(McpChannel.STREAMABLE)
                .url("http://localhost:8080/mcp")
                .build();

        String result = client.callTool("hello", Map.of("name", "Solon"))
                .getContent();

        System.out.println(result); // Output: "Hello, Solon!"
    }
}

Connecting to an AI Model

The real power of MCP is connecting your tools to an LLM. Here's how:

ChatModel chatModel = ChatModel.of(apiUrl)
        .provider("openai")
        .model("gpt-4")
        .defaultToolsAdd(mcpClient) // Bind MCP tools to the model
        .build();

ChatResponse resp = chatModel
        .prompt("Say hello to Alice")
        .call();

System.out.println(resp.getMessage());
// The model will call the MCP tool automatically

Transport Options

Solon MCP supports four transport types:

Transport	When to Use
`STREAMABLE`	Default for new projects. Modern MCP protocol with streaming support.
`STREAMABLE_STATELESS`	For clustered deployments. No sticky sessions needed.
`SSE`	Legacy MCP protocol. Server-Sent Events based.
`STDIO`	For local subprocess communication (e.g., CLI tools).

Important: Server and client must use matching transport types. STREAMABLE and SSE are not interchangeable.

What's Next

This is the simplest possible MCP server. From here you can:

Add more tools with @ToolMapping methods
Return async results with CompletableFuture<String>
Use STREAMABLE_STATELESS for cluster-friendly deployments
Add authentication with ServerTransportSecurityValidator
Build a full RAG pipeline with MCP resources

The full Solon MCP documentation covers all of these. I found these particularly helpful:

MCP Hello World — The starting point
MCP Tool Services — Publishing and consuming tools
MCP Transport Types — Deep dive on transport options
MCP Async Support — For non-blocking server operations
MCP McpTalent — Combining MCP with Solon's Talent system

If you've been avoiding MCP because the setup looked complex, give Solon's approach a try. One annotation, one dependency, and you're in business.

Solon AI Talents: Building Modular, Context-Aware AI Agents Beyond Simple Tools

Solon Framework — Thu, 09 Jul 2026 11:54:37 +0000

Solon AI Talents: Building Modular, Context-Aware AI Agents Beyond Simple Tools

If you've built AI agents before, you've probably hit this wall: your tool list grows too long, the model gets confused about when to use what, and your code turns into a tangled mess of if-else branching just to decide which tools to expose.

I've been there. And after spending some time with Solon's AI framework, I found something that changed how I think about agent architecture: Talents.

The Problem with Plain Tool Orchestration

Let's say you're building an internal support agent. It needs to:

Search the knowledge base
Check order status
Reset user passwords
Escalate to admin (for admins only)
Access billing info (for finance team only)

With plain tools, you'd typically do:

model.prompt("I need to reset my password")
    .options(o -> {
        o.toolAdd(new KbSearchTool());
        o.toolAdd(new OrderStatusTool());
        o.toolAdd(new PasswordResetTool());
        if ("admin".equals(role)) {
            o.toolAdd(new AdminEscalationTool());
        }
        if ("finance".equals(role)) {
            o.toolAdd(new BillingTool());
        }
    })
    .call();

This works, but it's fragile. The business logic is scattered across call sites. The model sees 5+ tools even when the user just wants to reset a password. And when you have 20+ tools, the model's reasoning quality drops noticeably.

What Are Talents?

Solon Talents are self-contained capability modules — think of them as mini-agents within your agent. Each Talent bundles three things:

Awareness (isSupported) — Can I handle this request?
Instruction (getInstruction) — What SOP should the model follow when using me?
Execution (getTools) — What tools do I expose?

When you register Talents, the framework automatically:

Filters inactive Talents based on user intent (saves tokens)
Injects only relevant instructions into the System Message
"Colors" each tool with its Talent's metadata — so the model knows exactly which SOP applies to which tool

Defining a Talent

There are two ways to build a Talent. I'll show both.

Way 1: Declarative with TalentDesc (Quick & Dynamic)

When you need something fast and don't want to create a new class:

TalentDesc orderExpert = new TalentDesc("order_expert")
    .description("Order management assistant")
    // Only activate when user mentions orders
    .isSupported(prompt -> 
        prompt.getUserContent().contains("order"))
    // Dynamic instruction based on user level
    .instruction(prompt -> {
        if ("VIP".equals(prompt.attr("user_level"))) {
            return "This is a VIP customer. Prioritize fast-track processing.";
        }
        return "Process orders using standard procedures.";
    })
    .toolAdd(new OrderQueryTool())
    .toolAdd(new OrderCancelTool());

Then register it:

ChatModel model = ChatModel.of(config)
    .defaultTalentAdd(orderExpert)
    .build();

Way 2: OOP with AbsTalent (For Complex Logic)

When you need dependency injection, state management, or complex business logic:

@Component
public class TechSupportTalent extends AbsTalent {

    @Inject
    private KbService kbService;

    @Override
    public String name() {
        return "tech_support";
    }

    @Override
    public String description() {
        return "Technical support specialist — handles troubleshooting and config resets";
    }

    @Override
    public boolean isSupported(Prompt prompt) {
        String content = prompt.getUserContent();
        return content != null && (
            content.contains("error") ||
            content.contains("bug") ||
            content.contains("故障")
        );
    }

    @Override
    public String getInstruction(Prompt prompt) {
        return """
            You are a technical support specialist. Follow these SOPs:
            1. First search the knowledge base for known solutions
            2. Verify the user's Solon version before suggesting fixes
            3. If modifying production config, clearly state the risks
            """;
    }

    @ToolMapping(name = "search_kb", 
                 description = "Search the knowledge base for solutions")
    public String searchKb(@Param("query") String query) {
        return kbService.search(query);
    }

    @ToolMapping(
        name = "reset_config",
        description = "Reset system configuration (high-risk operation)",
        meta = "{'danger': true, 'confirm_msg': 'Service will restart. Proceed?'}"
    )
    public String resetConfig(@Param("serviceName") String serviceName) {
        return "Service [" + serviceName + "] config reset, restarting...";
    }
}

Dynamic Context Injection with Prompt Attrs

This is where Talents really shine. The Prompt object carries runtime attributes — invisible to the LLM, but accessible to your Talent logic.

// Build a prompt with business context
Prompt prompt = Prompt.of("I need to check order #12345")
    .attrPut("tenant_id", "tenant_abc")
    .attrPut("user_role", "ADMIN")
    .attrPut("user_level", "VIP");

model.prompt(prompt).call();

Inside your Talent, you can access these:

public class OrderManagerTalent implements Talent {

    @Override
    public boolean isSupported(Prompt prompt) {
        // Only activate if we have a valid tenant context
        return prompt.attr("tenant_id") != null 
            && prompt.getUserContent().contains("order");
    }

    @Override
    public String getInstruction(Prompt prompt) {
        String tenant = prompt.attrOrDefault("tenant_name", "unknown");
        return "You are the order manager for [" + tenant + 
               "]. Only handle this tenant's data.";
    }

    @Override
    public Collection<FunctionTool> getTools(Prompt prompt) {
        List<FunctionTool> tools = new ArrayList<>();
        tools.add(new OrderQueryTool());

        // Only admins get the cancel tool
        if ("ADMIN".equals(prompt.attr("user_role"))) {
            tools.add(new OrderCancelTool());
        }

        return tools;
    }
}

Registering Talents — Global vs Per-Request

Global registration (for always-on capabilities)

ChatModel model = ChatModel.of(config)
    .defaultTalentAdd(securityAuditTalent)   // always active
    .defaultTalentAdd(0, translationTalent)  // with priority (index)
    .build();

Per-request injection (for dynamic scenarios)

model.prompt("What's the weather in Tokyo?")
    .options(o -> {
        o.talentAdd(weatherTalent);
        o.talentAdd(2, languageTalent); // with priority
    })
    .call();

Priority matters

Talents are processed in registration order. Instructions are accumulated into the System Message sequentially. The framework "colors" each tool with its Talent's identity, so the model associates the right SOP with the right tool set.

When to Use Talents vs Plain Tools

Scenario	Use Tools	Use Talents
Simple stateless function	✅
Needs SOP instructions		✅
Dynamic activation by context		✅
Permission-based tool filtering		✅
Single-purpose utility	✅
Multi-tool coordination		✅

Rule of thumb: If your tool needs more than a description to explain when and how to use it, wrap it in a Talent.

Putting It All Together: A Multi-Tenant Support Agent

Here's a complete example showing how Talents make multi-tenant support clean:

@Component
public class TenantAwareSupportAgent {

    @Inject
    private TenantService tenantService;

    private final ChatModel model;

    public TenantAwareSupportAgent() {
        this.model = ChatModel.of(config)
            .defaultTalentAdd(new OrderManagerTalent())
            .defaultTalentAdd(new TechSupportTalent())
            .defaultTalentAdd(new BillingTalent())
            .build();
    }

    public String handle(String userMessage, String tenantId, String role) {
        // Load tenant context
        Tenant tenant = tenantService.findById(tenantId);

        Prompt prompt = Prompt.of(userMessage)
            .attrPut("tenant_id", tenant.id())
            .attrPut("tenant_name", tenant.name())
            .attrPut("user_role", role);

        ChatResponse resp = model.prompt(prompt).call();
        return resp.getMessage();
    }
}

The calling code is clean. The Talent logic is self-contained. And the model only sees the tools relevant to the current request.

The One Thing I Wish I Knew Earlier

Talents aren't just "tools with instructions." They're decision boundaries for your AI. Each Talent draws a clear line: "I handle this domain, and here's exactly how." The model doesn't have to guess which tool to use — the Talent's SOP guides it precisely.

This is especially noticeable when you have 10+ tools. Before Talents, the model would occasionally call the wrong tool or try to use a tool outside its intended context. After moving to Talents with isSupported guards, those issues largely disappeared.

Next Steps

The Solon AI docs have more depth on:

If you're building production AI agents with Solon, Talents are the architecture pattern you didn't know you needed. Try wrapping your next tool set into a Talent — the difference in model behavior is immediate.

Solon AI Talents: Building Modular, Context-Aware AI Agents Beyond Simple Tools

Solon Framework — Thu, 09 Jul 2026 11:24:06 +0000

Solon AI Talents: Building Modular, Context-Aware AI Agents Beyond Simple Tools

I've been there. And after spending some time with Solon's AI framework, I found something that changed how I think about agent architecture: Talents.

The Problem with Plain Tool Orchestration

Let's say you're building an internal support agent. It needs to:

Search the knowledge base
Check order status
Reset user passwords
Escalate to admin (for admins only)
Access billing info (for finance team only)

With plain tools, you'd typically do:

model.prompt("I need to reset my password")
    .options(o -> {
        o.toolAdd(new KbSearchTool());
        o.toolAdd(new OrderStatusTool());
        o.toolAdd(new PasswordResetTool());
        if ("admin".equals(role)) {
            o.toolAdd(new AdminEscalationTool());
        }
        if ("finance".equals(role)) {
            o.toolAdd(new BillingTool());
        }
    })
    .call();

What Are Talents?

Solon Talents are self-contained capability modules — think of them as mini-agents within your agent. Each Talent bundles three things:

Awareness (isSupported) — Can I handle this request?
Instruction (getInstruction) — What SOP should the model follow when using me?
Execution (getTools) — What tools do I expose?

When you register Talents, the framework automatically:

Filters inactive Talents based on user intent (saves tokens)
Injects only relevant instructions into the System Message
"Colors" each tool with its Talent's metadata — so the model knows exactly which SOP applies to which tool

Defining a Talent

There are two ways to build a Talent. I'll show both.

Way 1: Declarative with TalentDesc (Quick & Dynamic)

When you need something fast and don't want to create a new class:

TalentDesc orderExpert = new TalentDesc("order_expert")
    .description("Order management assistant")
    // Only activate when user mentions orders
    .isSupported(prompt -> 
        prompt.getUserContent().contains("order"))
    // Dynamic instruction based on user level
    .instruction(prompt -> {
        if ("VIP".equals(prompt.attr("user_level"))) {
            return "This is a VIP customer. Prioritize fast-track processing.";
        }
        return "Process orders using standard procedures.";
    })
    .toolAdd(new OrderQueryTool())
    .toolAdd(new OrderCancelTool());

Then register it:

ChatModel model = ChatModel.of(config)
    .defaultTalentAdd(orderExpert)
    .build();

Way 2: OOP with AbsTalent (For Complex Logic)

When you need dependency injection, state management, or complex business logic:

@Component
public class TechSupportTalent extends AbsTalent {

    @Inject
    private KbService kbService;

    @Override
    public String name() {
        return "tech_support";
    }

    @Override
    public String description() {
        return "Technical support specialist — handles troubleshooting and config resets";
    }

    @Override
    public boolean isSupported(Prompt prompt) {
        String content = prompt.getUserContent();
        return content != null && (
            content.contains("error") ||
            content.contains("bug") ||
            content.contains("故障")
        );
    }

    @Override
    public String getInstruction(Prompt prompt) {
        return """
            You are a technical support specialist. Follow these SOPs:
            1. First search the knowledge base for known solutions
            2. Verify the user's Solon version before suggesting fixes
            3. If modifying production config, clearly state the risks
            """;
    }

    @ToolMapping(name = "search_kb", 
                 description = "Search the knowledge base for solutions")
    public String searchKb(@Param("query") String query) {
        return kbService.search(query);
    }

    @ToolMapping(
        name = "reset_config",
        description = "Reset system configuration (high-risk operation)",
        meta = "{'danger': true, 'confirm_msg': 'Service will restart. Proceed?'}"
    )
    public String resetConfig(@Param("serviceName") String serviceName) {
        return "Service [" + serviceName + "] config reset, restarting...";
    }
}

Dynamic Context Injection with Prompt Attrs

This is where Talents really shine. The Prompt object carries runtime attributes — invisible to the LLM, but accessible to your Talent logic.

// Build a prompt with business context
Prompt prompt = Prompt.of("I need to check order #12345")
    .attrPut("tenant_id", "tenant_abc")
    .attrPut("user_role", "ADMIN")
    .attrPut("user_level", "VIP");

model.prompt(prompt).call();

Inside your Talent, you can access these:

public class OrderManagerTalent implements Talent {

    @Override
    public boolean isSupported(Prompt prompt) {
        // Only activate if we have a valid tenant context
        return prompt.attr("tenant_id") != null 
            && prompt.getUserContent().contains("order");
    }

    @Override
    public String getInstruction(Prompt prompt) {
        String tenant = prompt.attrOrDefault("tenant_name", "unknown");
        return "You are the order manager for [" + tenant + 
               "]. Only handle this tenant's data.";
    }

    @Override
    public Collection<FunctionTool> getTools(Prompt prompt) {
        List<FunctionTool> tools = new ArrayList<>();
        tools.add(new OrderQueryTool());

        // Only admins get the cancel tool
        if ("ADMIN".equals(prompt.attr("user_role"))) {
            tools.add(new OrderCancelTool());
        }

        return tools;
    }
}

Registering Talents — Global vs Per-Request

Global registration (for always-on capabilities)

ChatModel model = ChatModel.of(config)
    .defaultTalentAdd(securityAuditTalent)   // always active
    .defaultTalentAdd(0, translationTalent)  // with priority (index)
    .build();

Per-request injection (for dynamic scenarios)

model.prompt("What's the weather in Tokyo?")
    .options(o -> {
        o.talentAdd(weatherTalent);
        o.talentAdd(2, languageTalent); // with priority
    })
    .call();

Priority matters

When to Use Talents vs Plain Tools

Scenario	Use Tools	Use Talents
Simple stateless function	✅
Needs SOP instructions		✅
Dynamic activation by context		✅
Permission-based tool filtering		✅
Single-purpose utility	✅
Multi-tool coordination		✅

Rule of thumb: If your tool needs more than a description to explain when and how to use it, wrap it in a Talent.

Putting It All Together: A Multi-Tenant Support Agent

Here's a complete example showing how Talents make multi-tenant support clean:

@Component
public class TenantAwareSupportAgent {

    @Inject
    private TenantService tenantService;

    private final ChatModel model;

    public TenantAwareSupportAgent() {
        this.model = ChatModel.of(config)
            .defaultTalentAdd(new OrderManagerTalent())
            .defaultTalentAdd(new TechSupportTalent())
            .defaultTalentAdd(new BillingTalent())
            .build();
    }

    public String handle(String userMessage, String tenantId, String role) {
        // Load tenant context
        Tenant tenant = tenantService.findById(tenantId);

        Prompt prompt = Prompt.of(userMessage)
            .attrPut("tenant_id", tenant.id())
            .attrPut("tenant_name", tenant.name())
            .attrPut("user_role", role);

        ChatResponse resp = model.prompt(prompt).call();
        return resp.getMessage();
    }
}

The calling code is clean. The Talent logic is self-contained. And the model only sees the tools relevant to the current request.

The One Thing I Wish I Knew Earlier

Next Steps

The Solon AI docs have more depth on:

Debugging ReActAgent 'Tool Message Order' Error in Solon AI

Solon Framework — Wed, 08 Jul 2026 08:28:50 +0000

If you're using Solon's ReActAgent to build multi-step AI agents, you might hit a frustrating error after the first tool call succeeds:

Error code:400, message:{"code":20015,"message":"Value error, after tool message, next must be user or assistant message","data":null}

This isn't a hypothetical scenario — it happened to a real user (GitHub issue #121) who upgraded from Solon AI v3.9.3 to v3.10.7. The agent worked fine for the first round of reasoning and tool execution, then failed consistently on subsequent steps.

What Was Happening

The user had a ReActAgent configured with multiple tools, including one that queries dietary data by date. When the agent needed to call the same tool multiple times (e.g., "query my diet for the past 3 days"), each tool call created a message in the conversation history. The problem was in the message ordering — after a tool response, the next message needed to be a user or assistant message, but the framework was producing a malformed sequence.

Here's the error in context:

WARN: ReActAgent [react_agent] retry 1/3 due to: 
Error code:400, message:{"code":20015,"message":"Value error, after tool message, next must be user or assistant message","data":null}

The error repeated 3 times until the agent gave up with:

ReActAgent [react_agent] finished, abnormal:true, finalAnswer: 抱歉，暂时无法使用模型服务

The Root Cause

The issue was in the ReActAgent's message handling logic in v3.10.7. When the agent invoked a tool and received a response, the subsequent message construction didn't properly align with the LLM API's expected message format. The model (DeepSeek-V4-Pro in this case) enforced stricter message ordering rules — specifically, after a tool role message, the next message must be user or assistant, not another tool message.

The user's configuration:

ReActAgent robot = ReActAgent.of(chatModel)
    .role("You are a super agent...")
    .planningMode(true)
    .instruction(Pmp.CHAT_INSTRUCTION)
    .defaultToolContextPut("token", token)
    .sessionWindowSize(10)
    .modelOptions(o -> o
        .temperature(0.1F)
        .optionSet("enable_thinking", false))
    .build();

The Fix

The issue was resolved in Solon AI v4.0.0, which was released shortly after the bug report. The v4.0.0 release included a complete overhaul of the message formatting logic to properly handle multi-tool-call sequences.

Workaround for v3.10.x

If you're stuck on v3.10.x and can't upgrade immediately, you can reduce the likelihood of this error by:

Lowering maxSteps — fewer sequential tool calls reduce the chance of message ordering issues
Adding autoRethink(true) — this tells the agent to reflect and reformat when it hits the message limit

ReActAgent robot = ReActAgent.of(chatModel)
    .planningMode(true)
    .autoRethink(true)  // Added: self-reflection when max turns approach
    // ... rest of config
    .build();

The Real Fix: Upgrade to v4.0.0+

The user was advised to upgrade to v4.0.0, which fixed the underlying issue. The v4.0.0 release notes include:

ReActAgent message format fix — Proper handling of tool call sequences to comply with LLM API message ordering requirements.

Key Takeaways

Always check the message format — Different LLM providers have different rules about message ordering. DeepSeek, OpenAI, and Anthropic all enforce slightly different constraints.
Upgrade to the latest version — Solon AI v4.0.0 fixed this specific issue. If you're on v3.10.x and using ReActAgent with multiple tool calls, upgrading is recommended.
Use autoRethink for resilience — Even with the fix, autoRethink(true) provides a safety net when the agent's reasoning path gets complex.
Test with your specific model — The error manifested with DeepSeek-V4-Pro specifically. Different models may trigger different edge cases.

This article is based on a real GitHub issue: opensolon/solon-ai#121. Solon AI v4.0.0 fixed this issue. Official docs: solon.noear.org/article/1456

Building Conversational Memory in AI Agents with Solon's ChatSession API

Solon Framework — Wed, 08 Jul 2026 08:28:42 +0000

If you've built any LLM-powered application, you've hit this wall: large language models are stateless by design. Every API call is a fresh conversation. The model doesn't remember what you said five messages ago — unless you tell it.

The standard approach is "multi-message prompting": stuff the entire conversation history into each request. But managing that history — trimming old messages, persisting across sessions, handling concurrent users — gets messy fast.

I've been working with Solon's AI module (solon-ai) for a few months, and its ChatSession abstraction solves this cleanly. Let me walk through how it works.

The Problem: Stateless LLMs

When you call chatModel.prompt("Hello").call(), the model has no context. If you ask "What did I just say?", it won't know. The model only sees the current message.

To maintain context, you need to pass previous messages as part of the prompt. This is where ChatSession comes in.

The Solution: ChatSession

Solon's ChatSession interface manages a sequence of messages for a conversation. It records every input and output, and automatically feeds the history back into subsequent prompts.

import org.noear.solon.ai.chat.ChatSession;
import org.noear.solon.ai.chat.session.InMemoryChatSession;

ChatSession chatSession = InMemoryChatSession.builder()
        .maxMessages(10)
        .sessionId("session-1")
        .build();

Usage with synchronous calls

chatModel.prompt("Hello, I'm looking for a laptop recommendation.")
         .session(chatSession)
         .options(o -> {
            o.systemPrompt("You are a helpful tech support agent.");
         })
         .call();

Usage with streaming

chatModel.prompt("What did I ask you about?")
         .session(chatSession)
         .stream()
         .filter(resp -> resp.hasContent())
         .forEach(resp -> System.out.print(resp.getContent()));

The .session(chatSession) call is the key. It tells the model: "Use this session's history as context, and record this interaction too."

Three Built-in Implementations

Solon ships with three ChatSession implementations, each suited for different scenarios:

Implementation	Storage	Best For	Notes
`InMemoryChatSession`	Local memory (Map)	Development, unit tests	Ephemeral — lost on restart
`FileChatSession`	Local file system	Desktop apps, CLI agents	Persistent to disk
`RedisChatSession`	Redis database	Production, high concurrency	Shared across nodes

Web Integration: Full Example with SSE

Here's a complete web endpoint that maintains per-user conversation memory with Server-Sent Events streaming:

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.ChatSession;
import org.noear.solon.ai.chat.session.InMemoryChatSession;
import org.noear.solon.annotation.Controller;
import org.noear.solon.annotation.Header;
import org.noear.solon.annotation.Inject;
import org.noear.solon.annotation.Mapping;
import org.noear.solon.web.sse.SseEvent;
import reactor.core.publisher.Flux;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

@Controller
public class ChatController {
    @Inject
    ChatModel chatModel;

    final Map<String, ChatSession> sessionMap = new ConcurrentHashMap<>();

    @Mapping("chat")
    public Flux<SseEvent> chat(@Header("sessionId") String sessionId, String prompt) {
        ChatSession chatSession = sessionMap.computeIfAbsent(sessionId,
                k -> InMemoryChatSession.builder()
                        .sessionId(k)
                        .maxMessages(20)
                        .build());

        return chatModel.prompt(prompt)
                    .session(chatSession)
                    .options(o -> {
                        o.systemPrompt("You are a helpful assistant.");
                     })
                    .stream()
                    .filter(resp -> resp.hasContent())
                    .map(resp -> new SseEvent().data(resp.getContent()));
    }
}

Serialization for Custom Persistence

If you need to build your own persistence layer (database, S3, etc.), Solon provides serialization utilities for ChatMessage:

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

// Single message: to/from JSON
String json = ChatMessage.toJson(message);
ChatMessage msg = ChatMessage.fromJson(json);

// Batch: to/from NDJSON
String ndjson = ChatMessage.toNdjson(messages);
List<ChatMessage> batch = ChatMessage.fromNdjson(ndjson);

These methods are available since v3.8.0 and make it straightforward to store conversation history in any database.

The ChatSession Interface

For reference, here's the full interface (available in org.noear.solon.ai.chat):

public interface ChatSession {
    String getSessionId();
    List<ChatMessage> getMessages();
    List<ChatMessage> getLatestMessages(int windowSize);
    void removeLatestMessage(int windowSize);
    void addMessage(String userMessage);
    void addMessage(ChatMessage... messages);
    void addMessage(Prompt prompt);
    void addMessage(Collection<? extends ChatMessage> messages);
    boolean isEmpty();
    void clear();
    Map<String, Object> attrs();
}

Practical Tips

Set maxMessages wisely — too few breaks context, too many blows up token usage. Start with 10-20.
Use sessionId for multi-tenancy — map one session per user.
Combine with system prompts — .options(o -> o.systemPrompt(...)) sets persona, .session() handles history.
Production deployments — swap InMemoryChatSession for RedisChatSession when scaling.

Summary

Solon's ChatSession API solves the "stateless LLM" problem with a clean, minimal abstraction. You get three implementations out of the box (in-memory, file, Redis), a simple builder pattern, and seamless integration with both synchronous and streaming calls.

The web integration example above is production-ready — just add Redis and you have a horizontally scalable chat service with full conversation memory.

All code examples are based on Solon v4.0.3. Official documentation: https://solon.noear.org/article/925

Building Conversational Memory in AI Agents with Solon's ChatSession API

Solon Framework — Wed, 08 Jul 2026 04:31:17 +0000

I've been working with Solon's AI module (solon-ai) for a few months, and its ChatSession abstraction solves this cleanly. Let me walk through how it works.

The Problem: Stateless LLMs

When you call chatModel.prompt("Hello").call(), the model has no context. If you ask "What did I just say?", it won't know. The model only sees the current message.

To maintain context, you need to pass previous messages as part of the prompt. This is where ChatSession comes in.

The Solution: ChatSession

Solon's ChatSession interface manages a sequence of messages for a conversation. It records every input and output, and automatically feeds the history back into subsequent prompts.

import org.noear.solon.ai.chat.ChatSession;
import org.noear.solon.ai.chat.session.InMemoryChatSession;

ChatSession chatSession = InMemoryChatSession.builder()
        .maxMessages(10)
        .sessionId("session-1")
        .build();

Usage with synchronous calls

chatModel.prompt("Hello, I'm looking for a laptop recommendation.")
         .session(chatSession)                     // Auto-records history
         .options(o -> {
            o.systemPrompt("You are a helpful tech support agent.");
         })
         .call();                                   // First response

Usage with streaming

chatModel.prompt("What did I ask you about?")
         .session(chatSession)                     // Includes all previous messages
         .stream()                                 // Streams response token by token
         .filter(resp -> resp.hasContent())
         .forEach(resp -> System.out.print(resp.getContent()));

The .session(chatSession) call is the key. It tells the model: "Use this session's history as context, and record this interaction too."

Three Built-in Implementations

Solon ships with three ChatSession implementations, each suited for different scenarios:

Implementation	Storage	Best For	Notes
`InMemoryChatSession`	Local memory (Map)	Development, unit tests, low-frequency demos	Ephemeral — lost on restart
`FileChatSession`	Local file system	Desktop apps, CLI agents, single-machine tools	Persistent to disk — survives restarts
`RedisChatSession`	Redis database	Distributed environments, production, high concurrency	Shared across nodes

InMemoryChatSession

Best for single-server scenarios where you don't need persistence:

ChatSession session = InMemoryChatSession.builder()
        .maxMessages(20)
        .sessionId("user-123")
        .build();

FileChatSession

For applications that need to survive restarts — like a CLI tool or desktop app:

// FileChatSession persists conversation history to disk
// Automatically reads/writes from a local file path

RedisChatSession

For production deployments with multiple instances:

// RedisChatSession shares conversation state across all nodes
// Perfect for load-balanced web applications

Web Integration: Full Example with SSE

Here's where it gets practical. A complete web endpoint that maintains per-user conversation memory with Server-Sent Events streaming:

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.ChatSession;
import org.noear.solon.ai.chat.session.InMemoryChatSession;
import org.noear.solon.annotation.Controller;
import org.noear.solon.annotation.Header;
import org.noear.solon.annotation.Inject;
import org.noear.solon.annotation.Mapping;
import org.noear.solon.web.sse.SseEvent;
import reactor.core.publisher.Flux;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

@Controller
public class ChatController {
    @Inject
    ChatModel chatModel;

    final Map<String, ChatSession> sessionMap = new ConcurrentHashMap<>();

    @Mapping("chat")
    public Flux<SseEvent> chat(@Header("sessionId") String sessionId, String prompt) {
        // Get or create session per user
        ChatSession chatSession = sessionMap.computeIfAbsent(sessionId,
                k -> InMemoryChatSession.builder()
                        .sessionId(k)
                        .maxMessages(20)
                        .build());

        // Stream response with memory
        return chatModel.prompt(prompt)
                    .session(chatSession)
                    .options(o -> {
                        o.systemPrompt("You are a helpful assistant.");
                     })
                    .stream()
                    .filter(resp -> resp.hasContent())
                    .map(resp -> new SseEvent().data(resp.getContent()));
    }
}

The sessionMap.computeIfAbsent pattern ensures each sessionId gets its own conversation context. You could swap InMemoryChatSession for FileChatSession or RedisChatSession without changing anything else.

Serialization: For Custom Persistence

If you need to build your own persistence layer (database, S3, etc.), Solon provides serialization utilities for ChatMessage:

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

// Single message: to/from JSON
String json = ChatMessage.toJson(message);
ChatMessage msg = ChatMessage.fromJson(json);

// Batch: to/from NDJSON
String ndjson = ChatMessage.toNdjson(messages);
List<ChatMessage> batch = ChatMessage.fromNdjson(ndjson);

These methods are available since v3.8.0 and make it straightforward to store conversation history in any database.

The ChatSession Interface

For reference, here's the full interface (available in org.noear.solon.ai.chat):

public interface ChatSession {
    String getSessionId();
    List<ChatMessage> getMessages();

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

    // Convenience methods
    default void addMessage(String userMessage) {
        addMessage(ChatMessage.ofUser(userMessage));
    }
    default void addMessage(ChatMessage... messages) {
        addMessage(Arrays.asList(messages));
    }
    default void addMessage(Prompt prompt) {
        addMessage(prompt.getMessages());
    }
    void addMessage(Collection<? extends ChatMessage> messages);

    boolean isEmpty();
    void clear();

    // Temporary attributes (not persisted)
    Map<String, Object> attrs();
}

Practical Tips

Set maxMessages wisely — too few breaks context, too many blows up token usage. Start with 10-20 and adjust based on your use case.
Use sessionId for multi-tenancy — map one session per user/thread to keep conversations isolated.
Combine with system prompts — the .options(o -> o.systemPrompt("...")) call sets the model's persona, while .session() handles the conversation history.
Production deployments — swap InMemoryChatSession for RedisChatSession when you scale beyond a single instance.

Summary

The web integration example above is production-ready — just add Redis and you have a horizontally scalable chat service with full conversation memory.

All code examples are based on Solon v4.0.3. Official documentation: solon.noear.org/article/925

How We Automated Supply Chain Anomaly Management with Solon TeamAgent

Solon Framework — Mon, 06 Jul 2026 08:38:53 +0000

Building a Supply Chain Monitoring Agent with Solon TeamAgent

Our warehouse manager was spending 3 hours every morning checking inventory levels across 4 warehouses. By the time he finished the check, some items were already out of stock.

We needed something that could monitor inventory, detect anomalies, and coordinate replenishment automatically. The challenge was that this involved multiple different systems working together: inventory DB, supplier API, order forecasting, and exception handling.

Solon's TeamAgent turned out to be a perfect fit for this kind of multi-system coordination.

Why TeamAgent Instead of ReActAgent?

ReActAgent is a single AI agent that thinks and acts sequentially. For our supply chain scenario, we had several distinct responsibilities:

Agent	Responsibility	Tools
Inventory Monitor	Periodically check stock levels	`get_stock_level()`, `get_lead_time()`
Order Forecaster	Predict demand based on history	`get_sales_trend()`, `get_seasonal_factor()`
Replenishment Coordinator	Generate purchase orders	`calc_reorder_qty()`, `create_po()`
Exception Handler	Escalate anomalies	`check_supplier_status()`, `notify_manager()`

Each of these is a self-contained domain. Having one giant ReActAgent handle all of them would be messy. TeamAgent lets us define specialized sub-agents that work together through a collaboration protocol.

What Is TeamAgent?

From the official docs, TeamAgent is Solon's multi-agent coordination framework. Think of it as:

A team leader who assigns tasks to specialists and aggregates their results.

Each sub-agent (called a "member") is itself a ReActAgent with its own tools and identity. The TeamAgent decides which member should handle each part of a complex request.

Implementing the Supply Chain Monitor

1. Define Domain Tools

Each sub-agent needs its own tools. Here's the inventory monitor's tool:

public class InventoryTools extends AbsToolProvider {
    @ToolMapping(description = "Get current stock level for a specific SKU at a warehouse")
    public String get_stock_level(
            @Param(description = "Warehouse code, e.g. WH-SH, WH-BJ") String warehouse,
            @Param(description = "SKU identifier") String sku) {
        // In production, this queries the actual inventory DB
        return "{\"warehouse\":\"" + warehouse + "\", \"sku\":\"" + sku 
             + "\", \"qty\": 85, \"minStock\": 100, \"maxStock\": 500}";
    }

    @ToolMapping(description = "Get replenishment lead time for a SKU")
    public String get_lead_time(@Param(description = "SKU identifier") String sku) {
        return "{\"sku\":\"" + sku + "\", \"leadTimeDays\": 7}";
    }
}

public class ReplenishmentTools extends AbsToolProvider {
    @ToolMapping(description = "Calculate reorder quantity based on current stock and forecast")
    public String calc_reorder_qty(
            @Param(description = "Current stock") int currentStock,
            @Param(description = "Min stock threshold") int minStock,
            @Param(description = "Daily forecast demand") int dailyDemand,
            @Param(description = "Lead time in days") int leadTimeDays) {
        int reorderQty = (dailyDemand * (leadTimeDays + 3)) - currentStock;
        return "{\"reorderQty\": " + Math.max(reorderQty, 0) + "}";
    }

    @ToolMapping(description = "Create a purchase order in the ERP system")
    public String create_po(
            @Param(description = "SKU") String sku,
            @Param(description = "Quantity to order") int qty,
            @Param(description = "Supplier code") String supplier) {
        return "{\"poNumber\": \"PO-2026-07-\" + System.currentTimeMillis() 
             + \", \"sku\": \"" + sku + "\", \"qty\": " + qty 
             + ", \"supplier\": \"" + supplier + "\", \"status\": \"submitted\"}";
    }
}

2. Build Sub-Agents

Each sub-agent is a standalone ReActAgent with its own role description and tools:

// Inventory Monitor Agent
ReActAgent inventoryAgent = ReActAgent.of(chatModel)
        .role("You are an inventory monitoring specialist. " +
              "Check stock levels and identify items below minimum threshold.")
        .defaultToolAdd(new InventoryTools())
        .build();

// Replenishment Coordinator Agent
ReActAgent replenishAgent = ReActAgent.of(chatModel)
        .role("You are a replenishment specialist. " +
              "Calculate optimal order quantities and create purchase orders.")
        .defaultToolAdd(new ReplenishmentTools())
        .build();

// Exception Handler Agent
ReActAgent exceptionAgent = ReActAgent.of(chatModel)
        .role("You are an exception handler. " +
              "Escalate critical supply chain issues to management.")
        .defaultToolAdd(new ExceptionTools())
        .build();

3. Assemble the Team

// Build TeamAgent with the three sub-agents
TeamAgent supplyChainTeam = TeamAgent.of(chatModel)
        .addMember(inventoryAgent)
        .addMember(replenishAgent)
        .addMember(exceptionAgent)
        .protocol(TeamProtocol.SEQUENTIAL) // Execute members one by one
        .build();

// Execute a monitoring round
AgentSession session = InMemoryAgentSession.of("supply_chain_round_001");

String task = "Run daily inventory check for warehouse WH-SH. " +
              "Check SKU 'HDD-2TB', current stock is 85, min threshold is 100. " +
              "If below threshold, calculate reorder qty and create PO.";

String result = supplyChainTeam.prompt(task)
        .session(session)
        .call()
        .getContent();

4. The Execution Flow

When we run this, TeamAgent orchestrates the work:

TeamAgent receives the task and assigns it to the Inventory Monitor
Inventory Monitor calls get_stock_level() → finds stock (85) below threshold (100)
TeamAgent passes "below threshold, need replenishment" to Replenishment Coordinator
Replenishment Coordinator calls calc_reorder_qty() and create_po() → PO created
TeamAgent compiles the final report with all actions taken

Parallel Monitoring with `TeamProtocol.NONE`

For checking multiple warehouses simultaneously, we can use the NONE protocol (free mode) which lets all members work in parallel:

TeamAgent parallelTeam = TeamAgent.of(chatModel)
        .addMember(inventoryAgent)
        .protocol(TeamProtocol.NONE) // All members work independently
        .build();

String result = parallelTeam.prompt(
    "Check stock levels for all 4 warehouses: WH-SH, WH-BJ, WH-GZ, WH-CD")
        .call()
        .getContent();

Each inventory agent instance checks one warehouse in parallel, cutting total time by ~75%.

Real Deployment Notes

The official TeamAgent docs mention several config options we found useful:

# application.yml
solon.ai.team:
  max_turns: 15        # Max total reasoning cycles
  timeout: 60000       # 60s timeout for team execution
  protocol: sequential # sequential or none

We run this as a scheduled job every 2 hours:

@Scheduled(cron = "0 0 */2 * * ?")
public void scheduledInventoryCheck() {
    String result = supplyChainTeam.prompt(
        "Run routine inventory check. Report any items below threshold " +
        "and auto-create replenishment POs where possible.")
        .call()
        .getContent();

    // Log results and alert on exceptions
    log.info("Supply chain check complete: {}", result);
}

Results

After deploying this setup:

Inventory checks that previously took 3 hours of manual work now run in under 30 seconds
Replenishment POs are auto-generated when stock dips below threshold
Exception handler only escalates truly unusual cases (supplier delays, system errors)
The team can focus on strategic work instead of routine monitoring

All code based on Solon v4.0.3. Real API references: article/1283 (TeamAgent), article/1296 (TeamAgent config), article/1299 (NONE protocol).

How We Built an AI After-Sales Engine for E-Commerce Using Solon ReActAgent

Solon Framework — Mon, 06 Jul 2026 08:38:19 +0000

All code based on official Solon documentation (article/1285, article/1286, article/1329).

The Problem

Last month, our after-sales support team was drowning in tickets.

Hundreds of "order not received" complaints came in daily. Our CS reps had to switch between the order system, logistics system, and compensation system for every single case. Average handling time: 15 minutes per ticket. During promotions, the backlog hit 3,000+ tickets.

I thought: the workflow is always the same — look up the order, check logistics, determine responsibility, execute compensation. Why not let AI handle this flow?

So I built an AI-driven after-sales decision engine using Solon's ReActAgent.

What Is Solon's AI Agent?

Solon introduced AI Agent capabilities starting from v3.8. The core component is ReActAgent — think of it as an LLM that can call tools.

Instead of just chatting, ReActAgent follows a "Think -> Act -> Observe -> Re-think" loop:

Receives a customer complaint
Think: "I need to look up this order"
Act: Calls get_order(orderId) -> gets order details
Observe: The order has tracking number track_123
Re-think: "Got the tracking number, let me check logistics status"
Act: Calls get_logistic_status(trackNo)
Observe: Status is "lost"
Re-think: "Order amount is $158, > $100, should issue a refund"
Act: Calls apply_compensation("refund", 158)

The entire chain runs without human intervention.

Defining Business Tools

In Solon, tools extend AbsToolProvider with @ToolMapping annotations:

public static class OrderTools extends AbsToolProvider {
    @ToolMapping(description = "Query order details by order ID")
    public String get_order(@Param(description = "Order ID") String orderId) {
        if ("ORD_20251229".equals(orderId)) {
            return "{\"orderId\":\"ORD_20251229\", \"amount\": 158.0, " +
                   "\"trackNo\": \"track_123\", \"sku\": \"Smart Headphones\"}";
        }
        return "{\"error\": \"Order not found\"}";
    }
}

public static class LogisticTools extends AbsToolProvider {
    @ToolMapping(description = "Query shipping status by tracking number")
    public String get_logistic_status(@Param(description = "Tracking number") String trackNo) {
        if ("track_123".equals(trackNo)) {
            return "{\"status\": \"lost\", \"info\": \"Lost at Shanghai center\"}";
        }
        return "{\"error\": \"Tracking number not found\"}";
    }
}

public static class MarketingTools extends AbsToolProvider {
    @ToolMapping(description = "Issue compensation. Small orders: coupon; Large: refund")
    public String apply_compensation(
            @Param(description = "Strategy: coupon or refund") String strategy,
            @Param(description = "Order amount") double amount) {
        if ("refund".equals(strategy) && amount > 100) {
            return "[System] Refund submitted for $" + amount;
        } else if ("coupon".equals(strategy)) {
            return "[System] $20 coupon credited.";
        }
        return "[Manual] Strategy mismatch, escalated to human agent.";
    }
}

Assembling and Running the Agent

ChatModel chatModel = LlmUtil.getChatModel();

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(new OrderTools())
        .defaultToolAdd(new LogisticTools())
        .defaultToolAdd(new MarketingTools())
        .modelOptions(o -> o.temperature(0.0))
        .maxTurns(10)
        .autoRethink(true)
        .build();

AgentSession session = InMemoryAgentSession.of("job_001");
String result = agent.prompt("My order ORD_20251229 hasn't arrived. Can you check?")
    .session(session).call().getContent();
System.out.println(result);

Adding HITL (Human-In-The-Loop) Approval

Refunds involve money. Solon provides HITLInterceptor for human oversight:

HITLInterceptor hitl = new HITLInterceptor()
    .onSensitiveTool("apply_compensation")
    .onTool("apply_compensation", (trace, args) -> {
        double amount = Double.parseDouble(args.get("amount").toString());
        return amount > 100 ? "Large refund requires approval" : null;
    });

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(new OrderTools())
        .defaultToolAdd(new LogisticTools())
        .defaultToolAdd(new MarketingTools())
        .defaultInterceptorAdd(hitl)
        .build();

Approval Endpoints

Endpoint	Method	Purpose
`/ai/hitl/call`	POST	Submit query; returns pending if intercepted
`/ai/hitl/task`	GET	Get pending task details
`/ai/hitl/submit`	POST	Approve/reject

HITLTask task = HITL.getPendingTask(session);

if ("approve".equals(action)) {
    HITL.submit(session, task.getToolName(),
        HITLDecision.approve().comment("Verified by admin"));
} else {
    HITL.submit(session, task.getToolName(),
        HITLDecision.reject("Risk rejected by admin"));
}

// Resume execution
ReActResponse resp = agent.prompt().session(session).call();

Real-World Impact

Metric	Before	After
Time per ticket	~15 min	<10 sec (auto) / ~2 min (HITL)
CS team workload	Manual every ticket	Only ~30% need human review
Response to customer	Hours	Seconds

Final Thoughts

Solon's ReActAgent bridges the gap between people and systems. Clean tool definitions, flexible injection, HITL approval out-of-the-box.

Official docs: article/1285 | article/1286 | article/1329