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

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 d, 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).

A naive design puts approval outside the agent:

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

So the break point is exact: the model has already chosen transfer(amount=2000)

, but the tool has not executed yet.

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

.

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(...)

.

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  these tools
        .onSensitiveTool("transfer")
        // or  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(...)

onTool(name, strategy)

null

to let it passThat keeps low-risk automation fast while still fencing the dangerous path.

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:

resp.getTrace().isPending()

, return the HITLTask

to your admin UIHITLDecision

agent.prompt().session(session).call()

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

transfer(...)

. The interceptor stores a HITLTask

and interrupts.HITL.approve(session, "transfer")

HITL.reject(session, "transfer", "account anomaly")

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

call()

consumes the decision, runs (or skips) the tool, and the agent produces the final answer from a real observation.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.

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.

onSensitiveTool

is blunt and safe. onTool

with a predicate keeps small automated refunds / transfers flowing while still catching the expensive mistakes.

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.

AbsToolProvider

• @ToolMapping

HITLInterceptor

trace.isPending()

HITL.submit

/ approve

/ reject

AgentSession

without replaying the user promptOfficial docs used for this article:

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.

source & further reading

dev.to — original article Bayesian Neural Networks Which LLM should I actually code with? I built a small benchmark to find out Detecta si tu modelo de materiales hace trampa con la 'huella bibliográfica'