Abstract editorial illustration in deep blue, slate and warm neutral tones (description pending review)

Build Your First AI Agent Loop in Node.js (No API Key Required)

by

Tested by TNT Review — record TNT-TEST-2026-10-04-004, 5 October 2026. We ran the agent loop below against a multi-step request and a request with no matching tool, and both runs are captured verbatim in Verification.

The problem

“AI agent” gets used for two different things: the loop that takes a request, decides what to do, calls a tool, looks at the result, and decides what to do next — and the large language model that usually sits inside that loop making the decisions. Beginners trying to learn agents often start by wiring up a paid model API, which means the first thing they debug is billing and prompt formatting, not the loop itself.

This guide builds the loop on its own, with the decision-making step replaced by a few plain rules instead of a model call. It costs nothing to run, it is the same shape as a real agent, and you can swap in a real model later without changing anything else.

Expected outcome

By the end of this guide you will have a working agent loop with two tools (a unit converter and a word counter), and you will understand exactly which one line you would replace to turn it into a real LLM-powered agent.

Requirements and costs

  • Node.js (version 18 or newer).
  • Cost: free. No API key, no account, no network call.

How the loop works

Every tool-using agent, no matter how it is built, runs the same four-part loop:

  1. Plan — break the request into steps and decide what each one needs.
  2. Act — call a tool with that step’s input.
  3. Observe — look at what the tool returned.
  4. Repeat — move to the next step, or stop.

In a real agent, a language model does the planning: it reads the request and the tool list and decides which tool to call and with what input. In this starter, a plain rule does that job instead — it splits the request on “then” or a comma, then checks each piece against each tool’s own match() function. That is the only part you would replace with a model call. The loop, the tools, and the transcript format all stay exactly the same.

Step-by-step implementation

  1. Download the starter from the link below and save agent-loop.js anywhere.
  2. Open a terminal in that folder.
  3. Run it with a request in quotes: 
    node agent-loop.js "convert 12 miles to km, then count the words in: the quick brown fox"
  4. Read the transcript. Each step shows which tool was chosen (or “none” if nothing matched) and what it returned.
  5. Add your own tool by adding an entry to the TOOLS object with a match(text) function (decides if this tool applies) and a run(text) function (does the work and returns a plain object).

A real example

$ node agent-loop.js "convert 12 miles to km, then count the words in: the quick brown fox"
{
  "request": "convert 12 miles to km, then count the words in: the quick brown fox",
  "transcript": [
    { "step": "convert 12 miles to km", "action": "convert_distance",
      "observation": { "ok": true, "value": 19.31, "from": "miles", "to": "km" } },
    { "step": "count the words in: the quick brown fox", "action": "word_count",
      "observation": { "ok": true, "value": 4, "sample": "the quick brown fox" } }
  ]
}

$ node agent-loop.js "tell me a joke"
{
  "request": "tell me a joke",
  "transcript": [
    { "step": "tell me a joke", "action": "none", "observation": "no matching tool for this step" }
  ]
}

The second run matters as much as the first: a request neither tool understands is reported honestly as “no matching tool,” not guessed at. A real model-based planner can still fail the same way if the request does not match anything it knows how to do — the loop’s job is to make that failure visible, not to paper over it.

Verification and troubleshooting

What we tested, on 5 October 2026 (record TNT-TEST-2026-10-04-004): the two-step conversion-and-count request above, which correctly ran both tools in order and returned the right values (19.31 km, 4 words); and a request with no matching tool (“tell me a joke”), which correctly reported no match rather than silently doing nothing or crashing.

Troubleshooting:

  • It says “usage: node agent-loop.js…” and stops. You ran it with no request text. Put your request in quotes after the command.
  • A step you expected to match a tool says “none.” Check the tool’s match() function — it is a plain regular expression, so it only recognises the phrasing it was written for. This is expected for a rules-based planner; it is exactly the limitation a real model-based planner removes.
  • Two tools could both apply and you want to force one. Reorder the TOOLS object — the loop tries them in declaration order and uses the first match.

Limitations and alternatives

This is deliberately not a real AI agent: the planning step is fixed rules, not a model, so it can only do what its regular expressions anticipate. It cannot handle ambiguous phrasing, cannot ask a clarifying question, and cannot invent a plan for a tool combination its author did not foresee. The entire point is that the loop, tool contract and transcript are identical to a real agent’s, so once you replace planSteps() with a call to a language model (passing it the request and the list of available tools, and asking for a tool name and input back), everything downstream keeps working unchanged.

The alternative is starting directly with a hosted agent framework and a paid model API, which gets you a smarter planner immediately but means your first debugging session is billing, authentication and prompt formatting rather than the agent loop itself.

Free resources

The download contains the full agent loop with both tools, ready to run and extend.

Download the agent loop starter (ZIP, 2 KB)

Is there a paid version?

Not yet. This is the complete method. TNT Review has sold nothing to date and has no checkout, so any price we discuss in future should be read as a hypothesis, not an offer.

Leave a comment