What Is ReAct Architecture? Build a Fault‑Diagnosis Agent That Gains 200% Accuracy

Why Ordinary Agents Fail at Fault Diagnosis

When the author’s company first launched an AI‑driven troubleshooting feature, the plain agent often fabricated answers or gave generic, useless steps, leading to three user complaints within a week. Accuracy was roughly 30%.

How ReAct Solves the Problem

ReAct replaces the "intuition‑only" output with a loop of Reasoning → Acting → Observing → Re‑reasoning → Re‑acting . The agent thinks like a human, invoking tools, observing results, and iterating until a concrete solution is found.

Example for a CPU‑high alert:

Reason: "CPU is high, maybe due to slow SQL; check the slow‑log."

Act: call the slow‑log tool.

Observe: a SQL query took 2 seconds and consumed 70% of CPU.

Reason: "The query likely lacks an index; examine its execution plan."

Act: call the explain‑SQL tool.

Observe: the plan shows a full table scan on 1 million rows.

Conclusion: add an index on create_time to resolve the issue.

Ordinary Agent vs. ReAct Agent – Real‑World Comparison

Question: "Order service CPU usage is 85%, help me find the cause."

Ordinary Agent Answer – lists generic possibilities (code loop, memory leak, traffic spike, many slow SQLs) without concrete steps.

ReAct Agent Answer – follows the reasoning‑acting loop:

Reason : suspect slow SQL, call get_mysql_slow_log(dbName="order").

Act : invoke the tool.

Observe : one query SELECT * FROM order WHERE create_time > '2026-04-01' took 2.3 s, 70% CPU.

Reason : likely missing index, call explain_sql(...).

Act : invoke the explain tool.

Observe : create_time has no index, full scan of 1 M rows.

Conclusion : add a plain index – ALTER TABLE order ADD INDEX idx_create_time(create_time); The ReAct response provides a complete, evidence‑backed solution, which the author says outperformed a senior operations engineer.

Three‑Step Implementation with Spring AI

Step 1 – System Prompt : Define the reasoning template that forces the agent to output in the 【思考】…【行动】…【观察】 format and forbids hallucination.

String reactSystemPrompt = """
你是一个专业的运维故障排查专家，你需要按照以下步骤处理用户的问题：
1. 首先分析用户的问题，思考你需要做什么才能解决问题
2. 如果需要调用工具，明确你要调用什么工具，需要什么参数
3. 调用工具拿到结果后，分析结果，思考下一步该做什么
4. 重复思考→行动→观察的过程，直到你找到问题的根因和解决方案
5. 最后给出完整的排查过程和解决方案
思考的时候你要按照这个格式输出：
【思考】你的思考过程
【行动】调用工具名(参数名=参数值)
【观察】工具返回的结果
注意：
- 不要编造信息，所有结论必须基于工具返回的结果
- 不要跳步骤，每次只调用一个工具，拿到结果后再思考下一步
- 如果工具返回的信息足够解决问题，直接给出结论
""";

Step 2 – ChatClient Configuration : Register the two MCP tools (slow‑log and CPU usage), set defaultMaxToolCalls(10) to prevent infinite loops, and attach the system prompt.

@Configuration
public class ReActAgentConfig {
    @Bean
    public ChatClient reActChatClient(ChatClient.Builder builder, ToolCallbackProvider toolCallbackProvider) {
        return builder
            .defaultSystem(reactSystemPrompt)
            .defaultTools(toolCallbackProvider.getToolCallbacks()) // up to 10 calls
            .defaultMaxToolCalls(10)
            .build();
    }
}

Step 3 – Controller : Expose a simple HTTP endpoint that forwards the user question to the configured ChatClient.

@RestController
public class ReActAgentController {
    private final ChatClient reActChatClient;
    public ReActAgentController(ChatClient reActChatClient) { this.reActChatClient = reActChatClient; }
    @GetMapping("/ai/react/chat")
    public String chat(@RequestParam String question) {
        return reActChatClient.prompt()
            .user(question)
            .call()
            .content();
    }
}

Running the service and calling

http://localhost:8080/ai/react/chat?question=订单服务CPU 85%了，帮我排查一下原因

returns the same detailed diagnosis shown earlier.

Core Components of a ReAct Agent

System Prompt (Reasoning Template) – the brain that defines the loop and output format.

Tool Set – concrete functions the agent can invoke (e.g., slow‑log query, SQL explain, CPU monitor). Too many tools cause confusion; keep the set ≤10 and split into sub‑agents if needed.

Memory Store – retains the reasoning steps and tool results across turns. Spring AI uses an in‑memory store by default; production systems should replace it with Redis or a database for persistence.

@Configuration
public class MemoryConfig {
    @Bean
    public ChatMemory chatMemory() {
        // Replace with RedisChatMemory or JdbcChatMemory in production
        return new InMemoryChatMemory();
    }
}

Inject the memory into the ChatClient via .defaultChatMemory(chatMemory) so the agent remembers prior context even after restarts.

Five Production‑Level Pitfalls to Avoid

Vague prompts – the agent ignores rules and hallucinates; write detailed, example‑rich prompts.

No limit on tool calls – can cause endless loops and huge token costs; always set defaultMaxToolCalls.

Unclear tool descriptions – the agent won’t know which tool to pick; provide precise @Tool annotations.

Token overflow from long context – after several rounds, prune or summarize context every few steps.

Unstructured tool output – return JSON or a fixed format; otherwise the agent cannot parse results and may fabricate answers.

Conclusion

ReAct has become the de‑facto architecture for production‑ready AI agents. By adding a clear reasoning loop, tool integration, and memory, even a simple agent can handle complex troubleshooting tasks with accuracy gains of over 200% compared to naïve approaches. The next article will explore graph‑engine‑based multi‑node ReAct workflows.