examples/09_react-agent/CODE.md

# Code Explanation: react-agent.js

This example implements the **ReAct pattern** (Reasoning + Acting), a powerful approach for multi-step problem-solving with tools.

## What is ReAct?

ReAct = **Rea**soning + **Act**ing

The agent alternates between:
1. **Thinking** (reasoning about what to do)
2. **Acting** (using tools)
3. **Observing** (seeing tool results)
4. Repeat until problem is solved

## Key Components

### 1. ReAct System Prompt (Lines 20-52)
```javascript

const systemPrompt = `You are a mathematical assistant that uses the ReAct approach.



CRITICAL: You must follow this EXACT pattern:



Thought: [Explain what calculation you need]

Action: [Call ONE tool]

Observation: [Wait for result]

Thought: [Analyze result]

Action: [Call another tool if needed]

...

Thought: [Once you have all information]

Answer: [Final answer and STOP]

```

**Key instructions:**
- Explicit step-by-step pattern
- One tool call at a time
- Continue until final answer
- Stop after "Answer:"

### 2. Calculator Tools (Lines 60-159)

Four basic math operations:
```javascript

const add = defineChatSessionFunction({...});

const multiply = defineChatSessionFunction({...});

const subtract = defineChatSessionFunction({...});

const divide = defineChatSessionFunction({...});

```

Each tool:
- Takes two numbers (a, b)
- Performs operation
- Logs the call
- Returns result as string

### 3. ReAct Agent Loop (Lines 164-212)

```javascript

async function reactAgent(userPrompt, maxIterations = 10) {

    let iteration = 0;

    let fullResponse = "";

    

    while (iteration < maxIterations) {

        iteration++;

        

        // Prompt the LLM

        const response = await session.prompt(

            iteration === 1 ? userPrompt : "Continue your reasoning.",

            {

                functions,

                maxTokens: 300,

                onTextChunk: (chunk) => {

                    process.stdout.write(chunk);  // Stream output

                    currentChunk += chunk;

                }

            }

        );

        

        fullResponse += currentChunk;

        

        // Check if final answer reached

        if (response.toLowerCase().includes("answer:")) {

            return fullResponse;

        }

    }

}

```

**How it works:**
1. Loop up to maxIterations times
2. On first iteration: send user's question
3. On subsequent iterations: ask to continue
4. Stream output in real-time
5. Stop when "Answer:" appears
6. Return full reasoning trace

### 4. Example Query (Lines 215-220)

```javascript

const queries = [

    "A store sells 15 items Monday at $8 each, 20 items Tuesday at $8 each, 

     10 items Wednesday at $8 each. What's the average items per day and total revenue?"

];

```

Complex problem requiring multiple calculations:
- 15 × 8
- 20 × 8
- 10 × 8
- Sum results
- Calculate average
- Format answer

## The ReAct Flow

### Example Execution

```

USER: "A store sells 15 items at $8 each and 20 items at $8 each. Total revenue?"



Iteration 1:

Thought: First I need to calculate 15 × 8

Action: multiply(15, 8)

Observation: 120



Iteration 2:

Thought: Now I need to calculate 20 × 8

Action: multiply(20, 8)

Observation: 160



Iteration 3:

Thought: Now I need to add both results

Action: add(120, 160)

Observation: 280



Iteration 4:

Thought: I have the total revenue

Answer: The total revenue is $280

```

**Loop stops** because "Answer:" was detected.

## Why ReAct Works

### Traditional Approach (Fails)
```

User: "Complex math problem"

LLM: [Tries to calculate in head]

→ Often wrong due to arithmetic errors

```

### ReAct Approach (Succeeds)
```

User: "Complex math problem"

LLM: "I need to calculate X"

  → Calls calculator tool

  → Gets accurate result

  → Uses result for next step

  → Continues until solved

```

## Key Concepts

### 1. Explicit Reasoning
The agent must "show its work":
```

Thought: What do I need to do?

Action: Do it

Observation: What happened?

```

### 2. Tool Use at Each Step
```

Don't calculate: 15 × 8 = 120 (may be wrong)

Do calculate: multiply(15, 8) → 120 (always correct)

```

### 3. Iterative Problem Solving
```

Complex Problem → Break into steps → Solve each step → Combine results

```

### 4. Self-Correction
Agent can observe bad results and try again:
```

Thought: That doesn't look right

Action: Let me recalculate

```

## Debug Output

The code includes PromptDebugger (lines 228-234):
```javascript

const promptDebugger = new PromptDebugger({

    outputDir: './logs',

    filename: 'react_calculator.txt',

    includeTimestamp: true

});

await promptDebugger.debugContextState({session, model});

```

Saves complete prompt history to logs for debugging.

## Expected Output

```

========================================================

USER QUESTION: [Problem statement]

========================================================



--- Iteration 1 ---

Thought: First I need to multiply 15 by 8

Action: multiply(15, 8)



   🔧 TOOL CALLED: multiply(15, 8)

   📊 RESULT: 120



Observation: 120



--- Iteration 2 ---

Thought: Now I need to multiply 20 by 8

Action: multiply(20, 8)



   🔧 TOOL CALLED: multiply(20, 8)

   📊 RESULT: 160



... continues ...



--- Iteration N ---

Thought: I have all the information

Answer: [Final answer]



========================================================

FINAL ANSWER REACHED

========================================================

```

## Why This Matters

### Enables Complex Tasks
- Multi-step reasoning
- Accurate calculations
- Self-correction
- Transparent process

### Foundation of Modern Agents
This pattern powers:
- LangChain agents
- AutoGPT
- BabyAGI
- Most production agent frameworks

### Observable Reasoning
Unlike "black box" LLMs, you see:
- What the agent is thinking
- Which tools it uses
- Why it makes decisions
- Where it might fail

## Best Practices

1. **Clear system prompt**: Define exact pattern
2. **One tool per action**: Don't combine operations
3. **Limit iterations**: Prevent infinite loops
4. **Stream output**: Show progress
5. **Debug thoroughly**: Use PromptDebugger

## Comparison

```

Simple Agent vs ReAct Agent

────────────────────────────

Single prompt/response      Multi-step iteration

One tool call (maybe)       Multiple tool calls

No visible reasoning        Explicit reasoning

Works for simple tasks      Handles complex problems

```

This is the state-of-the-art pattern for building capable AI agents!