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 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:

1. agent finishes
2. your service notices a risky side effect
3. 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:

1. onSensitiveTool(...) — any call is pending
2. 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:

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

The closed loop in plain language

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

1. Trigger — ReAct plans, then tries transfer(...). The interceptor stores a HITLTask and interrupts.
2. Review — an operator opens the pending task, sees tool name + args.
3. 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")));

1. 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.