Building a ReAct Agent from Scratch

1. Quick anchor

An "AI agent" is not a model. It is a loop around a model. The model proposes an action, your code executes it, the result goes back into the context, and the loop repeats until the model decides it is done. Strip away every framework and that is all an agent is — four moving parts: a model, a set of tools, an accumulating memory (the message list), and a stop condition.

ReAct (Reason + Act, Yao et al., 2022) is the simplest useful shape of that loop: the model reasons in natural language about what to do, acts by calling a tool, observes the result, and reasons again. Modern LLMs do this natively through tool-use / function-calling APIs — you no longer parse "Action: search[...]" out of free text the way the original paper did; the model emits a structured tool_use block and the API hands it to you typed.

If you can write this loop from memory, you understand 80% of what production agent frameworks (LangGraph, the OpenAI Agents SDK, the Claude Agent SDK) do for you. The other 20% — durability, sub-agents, context management — is the subject of the rest of this pillar.

2. Why interviewers probe this

Every agent question at a frontier lab bottoms out here. The interviewer is checking whether you see an agent as a loop you control or as magic a library does. The tell at each level:

• IC3/IC4 — Can you name the four parts and write the loop without a framework? Do you append the assistant's tool_use to history before sending the result back (the #1 beginner bug)?
• IC5 — Can you articulate the agent-vs-workflow decision, and the ReAct-vs-plan-execute tradeoff, in terms of cost, latency, and failure modes — not vibes?
• IC6+ — Can you reason about where the loop breaks at scale: context growth, error compounding, non-determinism, and how you'd bound and observe it?

A senior who says "I'd just use LangGraph" without being able to draw the loop underneath is a red flag. The library is fine; not knowing what it does is not.

3. Concept build-up

3.1 The loop, precisely

messages = [user_request]
while True:
    response = model(messages, tools)        # REASON: model picks an action
    messages.append(response)                # remember what it decided
    if response has no tool calls:
        return response.text                 # STOP: model is done
    for call in response.tool_calls:         # ACT: run the tools
        result = execute(call)
        messages.append(result)              # OBSERVE: feed results back

Three invariants make or break this:

1. Append the assistant turn before the tool results. The API requires the tool_use block and its matching tool_result to both be in history, in order, with matching IDs. Skip the assistant turn and you get a 400.
2. Return all tool results in a single user turn. If the model requested three tools in parallel, you send back three tool_result blocks together, not one message each.
3. The stop condition is the model's, not yours — you stop when it stops calling tools (stop_reason == "end_turn"), with a hard iteration cap as a backstop.

3.2 ReAct vs Plan-Execute vs a plain workflow

ReAct decides the next action after seeing each result. That adaptivity is its strength and its cost: every step is a fresh model call.

A plan-execute agent (next lesson) makes a plan once, then executes it, calling the model far less often — cheaper and faster, but brittle if the plan was wrong.

And often you need neither. Anthropic's Building Effective Agents draws the line that frontier interviewers expect you to draw:

Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents are systems where the LLM dynamically directs its own process and tool usage.

If you can write the control flow as a fixed pipeline (classify → retrieve → answer), do that — it is deterministic, debuggable, and cheap. Reach for an agent loop only when the steps genuinely cannot be known in advance. "The simplest thing that works" is the senior answer almost every time.

Step through the difference yourself — watch the model-call counts diverge on the same task:

3.3 Tools are an interface, not an afterthought

The model only knows what your tool descriptions tell it. A vague search(q) gets misused; a precise "Search internal docs. Call this whenever the answer depends on company-specific information you don't already know" gets used correctly. Recent Opus models reach for tools more conservatively, so prescriptive, when-to-call descriptions measurably raise the right-call rate. Tool design is a first-class skill — it gets its own lesson (Tool Use & MCP).

4. Minimal implementation

Here is a complete ReAct agent against the Claude Messages API — no framework, ~40 lines of real logic. The full runnable file (with a CLI and a mock-LLM fallback so it runs with no API key) is in ai-eng-wiki/examples/agents/react_agent.py.

from anthropic import Anthropic
 
client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment
 
# 1) TOOLS — schema the model sees, plus the Python that actually runs.
TOOLS = [
    {
        "name": "calculator",
        "description": "Evaluate an arithmetic expression like (3 + 4) * 2. "
                       "Call this for any non-trivial math instead of doing it in your head.",
        "input_schema": {
            "type": "object",
            "properties": {"expression": {"type": "string"}},
            "required": ["expression"],
        },
    },
    {
        "name": "get_weather",
        "description": "Get the current weather for a city. Call when the user asks about weather.",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"],
        },
    },
]
 
def run_tool(name: str, args: dict) -> str:
    if name == "calculator":
        # Restrict to arithmetic so eval is safe.
        expr = args["expression"]
        if not all(c in "0123456789+-*/(). " for c in expr):
            return "Error: only arithmetic is allowed."
        return str(eval(expr))
    if name == "get_weather":
        return f"{args['location']}: 21°C, partly cloudy."
    return f"Unknown tool: {name}"
 
# 2) THE LOOP — reason, act, observe, repeat.
def agent(user_msg: str, max_turns: int = 6) -> str:
    messages = [{"role": "user", "content": user_msg}]
    for _ in range(max_turns):                       # hard cap = the backstop
        resp = client.messages.create(
            model="claude-opus-4-8",                 # swap to claude-sonnet-4-6 / -haiku-4-5 for cost
            max_tokens=1024,
            system="You solve the task by reasoning and using tools. "
                   "State each step briefly ('Thought: ...') before acting.",
            tools=TOOLS,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})  # INVARIANT 1
 
        if resp.stop_reason != "tool_use":           # STOP: model is done
            return "".join(b.text for b in resp.content if b.type == "text")
 
        results = []
        for block in resp.content:                   # ACT on every requested tool
            if block.type == "tool_use":
                out = run_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,          # IDs must match
                    "content": out,
                })
        messages.append({"role": "user", "content": results})  # INVARIANT 2: all results, one turn
    return "Stopped: hit the turn limit."
 
print(agent("What's the weather in Tokyo, and what is (18 * 7) + 12?"))

Read the loop against the three invariants in §3.1 — they are all right there. The eval is gated to arithmetic characters; in production you would never eval model output without a sandbox, but for a calculator tool the character whitelist is a reasonable guard.

Now run a real one. The playground below streams an actual Claude tool-use trace (or a deterministic mock if no key is set) — every Thought, every tool call, every observation, exactly as the loop above produces them:

5. Production tradeoffs

The toy loop is correct but not production-ready. The gap is what IC5+ interviews live in:

| Determinism | none | Agents are non-deterministic; gate side-effecting tools (send_email, deploy) behind confirmation. |

Two senior instincts worth stating out loud in an interview:

• Make hard-to-reverse actions tools, and gate them. A send_email tool can be intercepted and confirmed; bash -c "curl ..." cannot. Reversibility drives the tool surface (this is the heart of agent design).
• The model is ~20% of a production agent. The other 80% is the harness: orchestration, memory, guardrails, evals, observability. Saying this signals you have shipped one.

6. How it's asked

7. Pitfalls & flashcards

• Forgetting to append the assistant turn before the tool results → API 400. The single most common bug.
• Splitting parallel tool results across turns instead of one user message with all tool_result blocks.
• Raising on tool failure instead of returning an error result the model can recover from.
• No iteration cap → a flaky tool becomes an infinite, expensive loop.
• Treating "use an agent" as the default. Most tasks are workflows. Agents cost more and fail in more ways; justify them.

Flashcard. Agent = model + tools + memory + stop condition, run in a loop. ReAct = reason→act→observe, one model call per step: adaptive but pricey. Use the simplest thing that works — workflow < plan-execute < ReAct in order of how much you should have to justify it.

8. Further reading

• ReAct: Synergizing Reasoning and Acting in Language Models — Yao et al., 2022 (arxiv.org/abs/2210.03629).
• Building Effective Agents — Anthropic (anthropic.com/research/building-effective-agents).
• Claude tool-use overview — the API shape used above (platform.claude.com).
• Next: Planner–Executor & Multi-Agent Orchestration — when one loop isn't enough.