react-agent

name	react-agent
description	ReAct (Reasoning + Acting) agent implementation with explicit reasoning traces and structured tool use. Use this when implementing agents that need to show their work.

ReAct Agent Implementation

Overview

ReAct (Reasoning + Acting) is a prompting technique where the AI explicitly shows its reasoning process, takes actions, observes results, and iterates until reaching a final answer.

ReAct Cycle

graph LR
    Thought[Thought<br/>Reasoning] --> Action[Action<br/>Tool Use]
    Action --> Observation[Observation<br/>Result]
    Observation --> Thought2[Next Thought]
    Thought2 --> Action2[Next Action]
    Action2 --> Final[Final Answer]

Response Format

The agent MUST respond in this format:

Thought: <reasoning about what to do next>
Action: <tool_name> (only if using a tool)
Action Input: <input to the tool> (only if Action specified)
Observation: <result of action> (provided after tool execution)

Thought: I now have the answer
Final Answer: <complete answer>

Example

Thought: I need to find out what files exist in the current directory.
Action: run_command
Action Input: ls -la
Observation: total 32 drwxr-xr-x 5 user staff 160 Mar 13 10:00 .

Thought: Now I have the directory listing. Let me count the items.
Action: count_items
Action Input: 5
Observation: There are 5 items.

Thought: I now have the answer
Final Answer: There are 5 items in the current directory.

Key Components

ReactTrace

const ReactTrace = struct {
    allocator: std.mem.Allocator,
    steps: std.ArrayList(ReactStep),
    
    pub fn init(allocator: std.mem.Allocator) Self
    pub fn deinit(self: *Self) void
    pub fn addStep(self: *Self, thought, action, action_input, observation, is_final) !void
    pub fn printTrace(self: *Self) void
    pub fn getSystemPrompt(allocator: std.mem.Allocator) ![]const u8
    pub fn isFinalAnswer(content: []const u8) bool
    pub fn parseSteps(self: *Self, content: []const u8) !void
};

ReactStep

pub const ReactStep = struct {
    thought: []const u8,
    action: ?[]const u8,
    action_input: ?[]const u8,
    observation: ?[]const u8,
    is_final: bool,
};

Integration

To use ReAct in an agent:

1. Import the ReAct module:

const react = @import("react.zig");

2. Get the system prompt:

const prompt = try react.ReactTrace.getSystemPrompt(allocator);
defer allocator.free(prompt);

3. Parse LLM responses:

var trace = react.ReactTrace.init(allocator);
defer trace.deinit();

try trace.parseSteps(llm_response_content);
trace.printTrace();

Benefits

• Transparent reasoning: Users can see the agent's thought process
• Debuggable: Easy to trace where reasoning went wrong
• Structured: Clear separation of thought, action, and observation
• Iterative: Builds on previous observations

Use Cases

• Complex problem solving requiring multiple steps
• Tool-heavy workflows where understanding agent decisions is important
• Debugging and monitoring agent behavior
• Educational applications where showing work is important

Files

File	Description
libs/agent/src/agent/react.zig	ReAct implementation
docs/REACT.md	This documentation

Testing

Run ReAct tests:

zig test libs/agent/src/agent/react.zig

Test coverage:

• ReactTrace: init and deinit - Basic initialization
• ReactTrace: addStep - Adding reasoning steps
• ReactTrace: isFinalAnswer - Detecting final answers
• ReactTrace: parseSteps - simple - Parsing ReAct format