Building a ReAct Agent from Scratch (Part 1): What Is an Agent?

Agent

ReAct

LLM

TypeScript

DeepSeek

2 hours ago2110 words·11 min read

What You'll Learn

The fundamental difference between a plain LLM API call and an Agent
An intuitive understanding of why LLMs need to "call tools"
The core intuition behind the ReAct Agent loop
A mental model: Agent = LLM + Tools + Loop

Prerequisites

You have Node.js / TypeScript development experience and can read basic async/await and TypeScript types
You've used (or at least heard of) the OpenAI API or similar LLM APIs — the kind where you send a message and get a response back
If you haven't, no worries: this article starts from the simplest possible API call

Starting from a Real Scenario

Imagine you're building a CLI tool. Your boss says: "Add a smart Q&A feature — users type questions, we call a large language model to answer them."

You roll up your sleeves, npm install openai, and write this:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.deepseek.com',
  apiKey: process.env.DEEPSEEK_API_KEY,
});

async function ask(question: string): Promise<string> {
  const response = await client.chat.completions.create({
    model: 'deepseek-chat',
    messages: [{ role: 'user', content: question }],
  });
  return response.choices[0]?.message?.content ?? '';
}

console.log(await ask('What is the capital of France?'));
// → The capital of France is Paris.

It works. Perfect. Your boss praises you and then says: "Great — now add a feature to let users ask 'What time is it right now?'"

Easy enough, you think — just send the question to DeepSeek:

console.log(await ask('What time is it right now?'));
// → Sorry, as an AI assistant, I cannot access real-time information.
// Please check the clock on your device...

And there's the problem: the LLM doesn't know "what time it is now."

This isn't a DeepSeek issue — it's a universal limitation of all LLMs. An LLM's knowledge stops at the cutoff date of its training data. Think of it like a person locked inside a library — they can recite every book by heart, but if you ask "is it raining outside?", all they can do is guess.

Your boss continues: "Alright, different feature — let users enter a math expression, and we calculate it for them."

console.log(await ask('What is 128731 × 46291?'));
// → 128731 × 46291 = 5958834521
// (The correct answer is actually 5958833521... the LLM got it wrong)

LLMs frequently make errors on complex calculations. They aren't actually "computing" — they're guessing what the next token is likely to be. For large-number multiplication, the chance of guessing wrong is high.

Finally, your boss adds: "Oh, also — users might ask to 'check what's written in README.md, then create a SUMMARY.txt to summarize it.'"

Now it clicks: a plain LLM call can only chat. It can't read files, can't write files, can't do math, can't check the time, can't perform any "action." It's just a text generator.

The Core Problem: What Is the LLM Missing?

To summarize, LLMs have three clear shortcomings:

No real-time information: they don't know the current time, today's weather, or live stock prices
Unreliable computation: complex arithmetic and formulas are error-prone
No ability to act: they can't read or write files, make HTTP requests, or query a database

It's like having a brilliant person strapped to a chair — they can think, reason, and give you excellent advice, but their hands are tied. They can't do anything.

So here's the question: what if we untie them and let them reach for tools themselves?

Intuition: Giving the LLM a Set of "Helper Functions"

Going back to the "what time is it" problem, you might think: easy — call new Date() first, inject it into the prompt, then send it to the LLM:

const now = new Date().toLocaleString('en-US', { timeZone: 'America/New_York' });
const answer = await ask(`The current time is ${now}. Please tell the user what time it is.`);
// → The current time is Tuesday, July 14, 2026 at 4:30:00 PM.

This approach is correct — you prepare information the LLM doesn't know in advance, stuff it into the prompt, and the LLM answers based on it.

But the problem is: who decides "what information needs to be prepared, and when"?

In the example above, it was you — the developer — hardcoding new Date() in your code. But what if the user asks not "what time is it" but "what day of the week is it?" or "what's 12 times 17?" or "what's written in README.md?" Can you predict all possible cases ahead of time?

Obviously not. You need a smarter approach: let the LLM decide what information it needs, and have the program fetch it.

The idea goes like this:

Send the user's question to the LLM
The LLM reads the question and tells the program: "I need to know the current time" or "I need to read README.md"
The program executes that action and gets the result
Feed the result back to the LLM so it can continue thinking
Repeat steps 2–4 until the LLM decides it has enough information and gives a final answer

This is the core idea of an Agent — the LLM plays the role of the brain (thinking, deciding), while the program plays the role of hands and feet (executing actions, gathering information). The two alternate.

A Minimal Prototype: An LLM That "Can Do Math"

Let's build the smallest possible version of this idea. We'll solve just one problem: make the LLM correctly calculate 128731 × 46291.

The approach is straightforward:

Prepare a calculate(expression) function
Tell the LLM: "If you need to do math, don't do it yourself — use a specific format to tell me, and I'll do it for you."
The LLM issues the instruction "calculate 128731 × 46291 for me"
We run calculate('128731 * 46291') and return the result to the LLM
The LLM sees the result and gives the final answer

We'll break this into two steps.

Step 1: Prepare the tool function

function calculate(expression: string): string {
  // Safety check: only allow digits and operators
  if (!/^[\d\s+\-*/().%]+$/.test(expression)) {
    return `Illegal expression: ${expression}`;
  }
  try {
    const result = Function(`"use strict"; return (${expression})`)();
    return `${expression} = ${result}`;
  } catch {
    return `Unable to compute: ${expression}`;
  }
}

console.log(calculate('128731 * 46291'));
// → 128731 * 46291 = 5958833521

Step 2: Teach the LLM to "ask for help"

We need to design a System Prompt that tells the LLM the rules:

const SYSTEM_PROMPT = `You are an intelligent assistant. You can use a calculator tool for math.

When you need to perform a calculation, you must output in the following format:
Action: calculate
Action Input: {"expression": "<expression>"}

When you have a final answer, output in the following format:
Final Answer: <your answer>

Remember: do not do mental math. Use the tool.`;

Now let's implement the entire interaction flow — this is essentially the simplest possible ReAct loop:

async function miniAgent(question: string): Promise<string> {
  const messages: { role: string; content: string }[] = [
    { role: 'system', content: SYSTEM_PROMPT },
    { role: 'user', content: question },
  ];

  for (let step = 0; step < 5; step++) {
    // 1. Call the LLM
    const response = await client.chat.completions.create({
      model: 'deepseek-chat',
      messages: messages as any,
    });
    const text = response.choices[0]?.message?.content ?? '';
    console.log(`[Round ${step + 1}] LLM output:\n${text}\n`);

    // 2. Check if a final answer was given
    const finalMatch = text.match(/Final Answer:\s*([\s\S]*?)$/);
    if (finalMatch) {
      return finalMatch[1].trim();
    }

    // 3. Check if a tool needs to be called
    const actionMatch = text.match(/Action:\s*([^\n\r]*)/);
    const inputMatch = text.match(/Action Input:\s*([^\n\r]*)/);
    if (!actionMatch || !inputMatch) {
      // No Action and no Final Answer — return the text as-is
      return text;
    }

    const action = actionMatch[1].trim();
    const input = inputMatch[1].trim();

    // 4. Execute the corresponding tool
    let observation: string;
    if (action === 'calculate') {
      const { expression } = JSON.parse(input);
      observation = calculate(expression);
    } else {
      observation = `Unknown tool: ${action}`;
    }

    // 5. Feed the tool result back to the LLM
    messages.push({ role: 'assistant', content: text });
    messages.push({ role: 'user', content: `Observation: ${observation}` });
    console.log(`Observation: ${observation}\n`);
  }

  return 'Sorry, I thought for too many rounds and still couldn\'t reach an answer.';
}

// Give it a try
console.log(await miniAgent('What is 128731 × 46291?'));

Run this code and your terminal will output something like:

txt

[Round 1] LLM output:
Action: calculate
Action Input: {"expression": "128731 * 46291"}

Observation: 128731 * 46291 = 5958833521

[Round 2] LLM output:
Final Answer: 128731 × 46291 = 5,958,833,521

It works! The LLM no longer tries to do mental math. Instead, it receives the question, determines "I need the calculator," outputs an Action instruction, we execute it and return the result, and the LLM produces a Final Answer based on that result.

From a "Single Calculator" to a General Agent

The example above can only do calculation. But let's review what we actually did:

calculate is a Tool
The LLM decides "whether to use a tool and which tool to use" — that's Reasoning
The program executes the tool and returns the result — that's Acting
The tool result is fed back to the LLM — that's Observation
The cycle of Reasoning → Acting → Observation repeats until a final answer emerges

If we swap calculate for readFile, writeFile, getCurrentTime, runShell... the Agent's capabilities expand infinitely.

Think of it like a person:

The brain (LLM) handles thinking and decision-making
The toolbox (Tools) contains a calculator, a clock, a file system...
The loop continuously cycles through "think → act → observe → think again"

This is the ReAct (Reasoning + Acting) pattern — proposed by Google DeepMind in 2022, and still the core paradigm behind most LLM Agents today.

The minimal prototype we built above essentially implements the skeleton of a ReAct Agent. In the remaining articles, we'll progressively flesh out this skeleton:

More robust output format parsing (handling the LLM's various ways of "not following instructions")
More tools (file I/O, shell execution, directory listing...)
Streaming output (seeing the LLM's "thought process" in real time)
Conversation memory (managing multi-turn dialogue context)
Complex task planning (the Plan-Exec pattern)

Hands-On Practice

Exercise 1: Understanding the Loop (10 min)

Take the miniAgent code above, fill in the missing imports and configuration, and run it to completion. Watch the terminal as the LLM progresses through each round — observe the full Action → Observation → Final Answer flow.

Exercise 2: Add a Tool (15 min)

We currently only have one tool: calculate. Following its format, add a getCurrentTime tool:

Accepts parameters (doesn't actually need any — just return the current time in your timezone)
Describe the tool in the System Prompt
In the loop, check for action === 'getCurrentTime' and execute it

Try asking the Agent: "What time is it right now? How many hours until the end of the day?"

Advanced Challenge: Fix Edge Cases

What's wrong with the current implementation? Try these inputs:

Input "Hello" — no tool needed, can it just output a Final Answer?
The LLM outputs malformed JSON (an extra comma, for example) — does the program crash?
The LLM calls two tools in a single response (two Action blocks) — what happens?

Try fixing these issues. You'll start to appreciate just how many edge cases a real-world Agent implementation has to handle.

Summary & Key Terms

LLM limitations: no real-time information, unreliable computation, no ability to act — it's just a text generator "strapped to a chair"
What an Agent is: LLM (brain) + Tools (hands and feet) + Loop (the cycle of think → act → observe → think again)
The ReAct pattern: Reasoning + Acting — the LLM and tools collaborate in turns until the task is complete
Minimal prototype: you can build a "math-capable" Agent in under 60 lines of code

Keywords: LLM, Agent, ReAct, Tool, Action, Observation, Final Answer, System Prompt, Agent Loop