Designing a Stateless Reducer Agent
Introduction: Designing a Stateless Reducer Agent
In this unit, we're going to organize tool-calling agent logic into a clean, reusable pattern: the stateless reducer agent. This architecture is built on a simple principle: each agent step should behave like a reducer-style state transition with a clear state-in/state-out interface. Context in, updated context out. This does not mean the implementation is side-effect-free: each step may call the LLM, execute tools, and append to context, but the caller still provides all meaningful state and receives the updated state back. By making the execution history explicit, you make steps easier to inspect and test. Exact replay still requires a saved pre-step snapshot and a recorded model response. You'll also see how to build small, focused agents that do one thing well.
The finished agent exposes run(context) as its public entry point. Practices 1–3 temporarily expose some fields and methods so we can inspect each piece as we build it; the complete class makes those implementation details private. It accepts a ContextItem[] and returns a Promise<RunResult>. That result contains the updated context, a status ("running", "complete", "failed", or "max_steps_reached"), and the final answer if the agent finished. This clean interface makes the agent composable and straightforward to reason about.
The Stateless Reducer Pattern
At the heart of this architecture is a simple but powerful idea: your agent is an async function that transforms state. Instead of maintaining internal variables that change over time, the agent receives a ContextItem[] as input, processes one step of work, and returns a RunResult containing the updated context, a status, and an optional final answer.
The flow looks like this: context → updated context + status + finalAnswer. The agent takes the current ContextItem[] — which includes the conversation history, tool calls, and tool outputs — asks the model what to do next, executes any requested tools, and returns the result as a well-typed RunResult.
One practical note: while the stateless reducer pattern is stateless from the caller's perspective (the caller passes in all the state it cares about and gets back a complete result), the internal implementation uses context.push() to mutate the array in place during a step. This is a pragmatic choice that keeps the code simple, and it does not break the pattern: the agent's logic depends only on the input ContextItem[], not on any hidden internal fields or side effects.
Note on Implementation: The reducer pattern conceptually favors immutability — returning a new copy of state rather than mutating the existing one. For simplicity in these early units, we mutate the context array in place with
.push(). The core principle remains: the agent's logic depends only on the input context, not on internal object attributes.
Why does "stateless" matter? Because the caller holds the execution history, we can inspect and resume from a saved pre-step snapshot. Reproducing an identical step also requires a recorded or mocked model response: nextStep mutates the supplied array, and a fresh API call may choose a different action. You can pause execution, serialize the context to disk or a database, and resume later. You can test individual steps in isolation. You can even run multiple instances of the agent in parallel, each processing different contexts, without worrying about shared mutable state. This predictability is what makes the pattern so valuable for production systems.
Organizing Your Agent Files
Before we dive into the code, let's understand how the project is organized. This structure keeps your code clean and separates concerns: schemas live in JSON files, tool implementations live in TypeScript modules, shared types live in a dedicated file, and the agent logic lives in its own file.
The agent.ts file contains the Agent class that orchestrates the reducer loop. The models/state.ts file holds the shared TypeScript types — ContextItem, RunResult, and AgentStatus — used throughout the codebase. The tools/schemas/ directory holds JSON files that define what tools the model can call; these are the contracts between your agent and the model. The tools/functions/ directory contains the actual TypeScript implementations of those tools, which are just ordinary exported functions. The main.ts entry point shows how to wire everything together and run the agent. Let's start by defining the shared types that the rest of the code relies on.
Defining the Shared State Types
Before we write any logic, let's define the types that everything else depends on. They live in src/core/models/state.ts and describe the shape of the data flowing through the agent.
AgentStatus: A string literal union that captures exactly where the agent is in its lifecycle. Using specific strings like"complete"or"max_steps_reached"instead of a plainstringallows TypeScript to catch typos and forces you to handle each exhaustive case in your logic.ContextItem: A discriminated union representing the three kinds of entries in the conversation history.{ role: "user" }represents the initial request.{ type: "function_call" }records a tool the model decided to call, including itsarguments(as a JSON string) and a uniquecall_id.{ type: "function_call_output" }holds the result of that tool, linked back via the samecall_id.
RunResult: The typed object returned by therun()method. By bundling the updatedcontext, the currentstatus, and thefinalAnswerinto a named object rather than a positional tuple, we make the agent's output self-documenting and easy to destructure.
With the data shapes pinned down, let's look at the tool schemas.
Defining Math Tool Schemas
The tool schemas are organized into JSON files, making them easy to maintain and version separately from your code. The math tool schemas live in src/core/tools/schemas/math.json, and each schema describes one mathematical operation.
Each schema has a function type, a name, a description, and a parameters object defining the expected arguments. The required array ensures the model must provide both a and b, and "additionalProperties": false prevents unexpected fields. The file contains similar schemas for multiply_numbers, subtract_numbers, divide_numbers, power, and square_root. By keeping these in a JSON file, you can update the tool descriptions or add new tools without touching your TypeScript code. Now let's look at the special tool that signals completion.
Defining the Final Answer Tool
The final_answer tool is defined separately in src/core/tools/schemas/final_answer.json. This tool signals that the agent's work is complete and provides the final result to the user.
When the model calls final_answer, the agent knows to stop the loop and return the result. This tool takes a single parameter: the answer string containing the final response. By making completion an explicit tool call, we give the model a clear way to signal it has finished, and we can detect that signal in our code to terminate the reducer loop gracefully. With schemas defined, let's look at the tool implementations.
Implementing Tool Functions
The corresponding TypeScript functions live in src/core/tools/functions/math.ts. These are ordinary exported functions that perform the actual calculations when the model requests them.
All parameters are typed as number, which keeps the function signatures clean and self-documenting. Two functions include their own domain validation: divideNumbers checks for division by zero and throws an Error, and squareRoot prevents taking the square root of a negative number. When the model requests an invalid operation, the agent catches these errors and feeds them back as structured output, giving the model a chance to self-correct. Note that numeric type validation — ensuring the argument is actually a finite number — is handled separately by the numberArg() helper in the agent itself, which we'll see shortly.
Setting Up the Agent Class Structure
Now let's build the Agent class. We'll start with the AgentOptions interface and the constructor that uses it.
The constructor uses an options object pattern instead of positional parameters. This is a common TypeScript idiom: rather than writing new Agent("gpt-5", "low", "", 10), you write new Agent({ model: "gpt-5" }) and only pass the values you want to override. All properties on AgentOptions are marked optional with ?, and the ?? (nullish coalescing) operator provides defaults inside the constructor body.
Each field on the class is private readonly, meaning it can only be set once (in the constructor) and cannot be accessed from outside the class. The OpenAI client is initialized inline as private readonly client = new OpenAI(), which automatically picks up your OPENAI_API_KEY environment variable.
The systemPrompt tells the model it's an autonomous agent and must always call tools for computations. The extraInstructions option lets you extend the base prompt without editing the class code — useful for domain-specific guidance.
Loading Tool Schemas
The constructor also loads the tool schemas from the JSON files. Because the code runs as an ES module, we use Node.js path utilities along with import.meta.url to locate the schemas directory relative to the current file.
import.meta.url gives us the URL of the current module. We pass it through fileURLToPath to get a regular file path, then dirname gives us the directory it lives in. From there, join builds the path to the tools/schemas folder. readFileSync synchronously reads each JSON file, and JSON.parse parses it into a JavaScript value.
Because TypeScript doesn't know the shape of arbitrary JSON, we use as Tool[] and as Tool to tell the compiler these values conform to the Tool type from the OpenAI SDK. Finally, the spread operator ...mathSchemas unpacks the array of math schemas, and both files are combined into a single this.toolSchemas list that the agent will pass to the model on every call.
Separating Concerns into Methods
Before we dive into the execution logic, let's understand how the work inside Agent is divided. We'll break it into three async methods:
callLlm— Sends the current context to the model and returns its output items asResponseOutputItem[]nextStep— Executes one complete step: calls the model, executes tools, updates context, and returns aRunResultrun— Orchestrates the full loop, callingnextSteprepeatedly until the agent completes or hits the step limit
Why separate these concerns? Because each method does one thing well. If you need to change how you call the model, you change callLlm. If you need to test a single step in isolation, you call nextStep directly. If you need to add logging or checkpointing, you modify run without touching the core reducer logic. This separation makes the code easier to understand, test, and extend. Let's start with model communication.
Calling the LLM with Context
The callLlm method handles communication with the model, passing the full context and requiring it to use a tool.
This is a thin async wrapper around the OpenAI Responses API. It takes the current ContextItem[] as input and passes it directly to this.client.responses.create(...). The instructions parameter provides the system-level guidance, input carries the full conversation history typed as ContextItem[], and tools tells the model which functions it can call as a Tool[]. Setting tool_choice to "required" enforces that the model must call a tool — it cannot respond with plain text.
The reasoning parameter is conditional: when model === "gpt-5", we include { effort: this.reasoningEffort }; otherwise, we pass undefined so the field is omitted entirely. The method returns response.output — a ResponseOutputItem[] — rather than the full response object, giving callers only what they need. By passing the full context on every call, we ensure the model has all the information it needs to make the next decision.
Processing Tool Calls
Once the model returns its output items, we need to extract and record any function calls. The first part of nextStep handles this.
The method starts by calling callLlm to get the model's ResponseOutputItem[], then loops over the items. The isFunctionCall(item) call is a type guard — a function defined at the module level that checks item.type === "function_call" and narrows the TypeScript type accordingly, so we only process actual tool requests and skip anything else the model might include in its output.
For each function call, we first parse the arguments with JSON.parse(item.arguments), then push a function_call entry to the context. Note that the entry is appended to context before we check whether the tool is final_answer — this ensures the context always reflects what the model decided, regardless of which branch we take.
When item.name === "final_answer", the method returns a RunResult object directly with status: "complete" and the answer extracted from the parsed arguments. The return type is RunResult — a typed object — rather than a positional tuple, which makes the calling code easier to read and maintain.
Executing Tools with a Switch Statement
For non-completion tools, a switch statement routes each call to the appropriate function. Each case wraps the execution in a try/catch so errors become structured feedback rather than unhandled exceptions.
numberArg(args, "name") is a helper function that extracts a named argument from the parsed object and verifies it is a finite number, throwing a descriptive Error if the check fails. This centralizes argument validation in one place rather than repeating the check in every case.
compactToolError(error) is another helper that converts any caught Error (or unknown thrown value) into a compact JSON string — like {"result": "Error: Division by zero"}. This means the model receives structured feedback it can reason about and use to self-correct on the next step, rather than crashing the whole agent.
The default case handles unknown tool names with the same structured error format. After the switch, the tool output is appended to context as a function_call_output entry, linked to the original request via call_id. When all items have been processed without encountering final_answer, the method returns { context, status: "running", finalAnswer: null }, signaling the loop should continue.
Here are the two helpers referenced above, defined as module-level functions in agent.ts:
The Reducer Loop
The run method ties everything together, implementing the reducer loop that calls nextStep repeatedly until the agent completes or hits the safety boundary.
The method initializes three variables: step tracks the current iteration, status is typed as AgentStatus and starts as "running", and finalAnswer starts as null. The loop continues as long as status === "running" and the step count hasn't exceeded this.maxSteps.
On each iteration, await this.nextStep(context) executes one step and returns a RunResult. We pull context, status, and finalAnswer from the result, updating our local variables. If nextStep returns status: "complete", the while condition fails on the next check and the loop exits cleanly.
After the loop, if status is still "running", the agent reached the step limit without completing — in that case, we update status to "max_steps_reached". Finally, run returns a RunResult with the final context, status, and finalAnswer. The step limit prevents an infinite loop, and normal completion returns a typed result. At this stage, API failures and malformed tool arguments can still throw; Unit 3 adds a try/catch that records a "failed" state.
Running the Agent
Here's the entry point in src/main.ts that creates an Agent and asks it to solve a quadratic equation.
The imports use ESM .js extensions — this is required when targeting ES modules in Node.js, even though the source files are .ts. The initial context is typed as ContextItem[], giving you compile-time safety when constructing the conversation history. Because this is a top-level module, await can be used directly without wrapping it in an async function.
new Agent() uses all defaults: model "gpt-5", reasoningEffort "low", and maxSteps 10. You can customize any of these by passing an AgentOptions object — for example, new Agent({ maxSteps: 5 }) or new Agent({ model: "gpt-4o", maxSteps: 20 }).
When you run this, the agent processes the request step by step: it reasons about the quadratic equation x^2 - 5x + 6 = 0, calls math tools to factor or evaluate the roots, receives the results, and eventually calls final_answer. The output looks something like:
The status: "complete" tells you the agent finished normally, and finalAnswer contains the result. This example shows how all the pieces work together: a typed ContextItem[] goes in, the agent runs its reducer loop, and a RunResult comes out.
Summary and What's Next
You've now built a stateless reducer agent from the ground up. The core pattern is simple: run(context) accepts a ContextItem[], processes one step at a time through nextStep, and returns a RunResult containing the updated context, an AgentStatus, and the finalAnswer. Because the agent's execution depends only on the ContextItem[] it receives — not on any hidden mutable state — the logic is predictable, testable, and composable.
The interface is clean: ContextItem[] in → run() → { context, status, finalAnswer } out. This makes it straightforward to reason about what happened at each step, inspect an execution or reproduce it with a saved pre-step snapshot and a mocked model response, and build on top of this foundation without needing to change its internals.
In the upcoming practice exercises, you'll extend this foundation by adding new tools, handling different types of user requests, and exploring how the reducer pattern makes testing and debugging straightforward.
