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

Solon AI has introduced a Human-in-the-Loop (HITL) interceptor for its ReActAgent that pauses sensitive tool calls—such as money transfers or data deletions—before execution, allowing human review and correction without rebuilding the conversation. The feature uses official Solon APIs, including HITLInterceptor, HITLTask, and HITLDecision, and supports conditional pausing based on tool name or argument thresholds. This enables teams to keep low-risk automation fast while adding safety gates for dangerous operations.

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 . 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 . python 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 ... . python 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 ... onTool name, strategy null to let it passThat keeps low-risk automation fast while still fencing the dangerous path. python 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 UI HITLDecision 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.