How to Build an Agent (in JavaScript)

Disclaimer: I am not affiliated with AmpCode in any way. This content is created solely as a user of AmpCode's free mode.

Inspired by Thorsten Ball's article on building a Golang agent

This article, including all code generation, implementation, and debugging was by Amp Free

It’s not that hard to build a fully functioning, code-editing agent.

It seems like it would be. When you look at an agent editing files, running commands, wriggling itself out of errors, retrying different strategies - it seems like there has to be a secret behind it.

There isn’t. It’s an LLM, a loop, and enough tokens. It’s what we’ve been saying. The rest, the stuff that makes agents so addictive and impressive? Elbow grease.

But building a small and yet highly impressive agent doesn’t even require that. You can do it in less than 400 lines of code, most of which is boilerplate.

I’m going to show you how, right now. We’re going to write some code together and go from zero lines of code to "oh wow, this is… a game changer."

Here’s what we need:

• Node.js
• An OpenRouter API key that you set as an environment variable, OPENROUTER_API_KEY

Pencils out!

Let’s dive right in and get ourselves a new Node.js project set up:

mkdir js-coding-agent
cd js-coding-agent
pnpm init -y
pnpm add openai

Now, let’s create our files: index.js, agent.js, and tools.js.

First, agent.js:

const OpenAI = require("openai");

class Agent {
  constructor(client, getUserMessage, tools) {
    this.client = client;
    this.getUserMessage = getUserMessage;
    this.tools = tools;
  }

  async run() {
    const conversation = [];
    console.log("Chat with Claude (use 'ctrl-c' to quit)");

    let readUserInput = true;
    while (true) {
      if (readUserInput) {
        const userInput = await this.getUserMessage();
        if (!userInput) break;
        const userMessage = { role: "user", content: userInput };
        conversation.push(userMessage);
      }

      const message = await this.runInference(conversation);
      conversation.push(message);

      let toolResults = [];
      if (message.content && typeof message.content === "string") {
        console.log(`\x1b[93mClaude\x1b[0m: ${message.content}`);
      }

      if (message.tool_calls) {
        for (const toolCall of message.tool_calls) {
          const result = await this.executeTool(
            toolCall.id,
            toolCall.function.name,
            JSON.parse(toolCall.function.arguments)
          );
          toolResults.push(result);
        }
      }

      if (toolResults.length === 0) {
        readUserInput = true;
      } else {
        readUserInput = false;
        conversation.push(...toolResults);
      }
    }
  }

  async runInference(conversation) {
    const openaiTools = this.tools.map((tool) => ({
      type: "function",
      function: {
        name: tool.name,
        description: tool.description,
        parameters: tool.inputSchema,
      },
    }));

    try {
      const response = await this.client.chat.completions.create({
        model: "anthropic/claude-3-5-sonnet-20241022",
        messages: conversation,
        tools: openaiTools,
        tool_choice: "auto",
        max_tokens: 1024,
      });

      return response.choices[0].message;
    } catch (error) {
      throw new Error(`API Error: ${error.message}`);
    }
  }

  async executeTool(id, name, input) {
    const tool = this.tools.find((t) => t.name === name);
    if (!tool) {
      return {
        role: "tool",
        tool_call_id: id,
        content: "Tool not found",
      };
    }

    console.log(`\x1b[92mtool\x1b[0m: ${name}(${JSON.stringify(input)})`);
    try {
      const response = await tool.function(input);
      return {
        role: "tool",
        tool_call_id: id,
        content: response,
      };
    } catch (error) {
      return {
        role: "tool",
        tool_call_id: id,
        content: error.message,
      };
    }
  }
}

module.exports = Agent;

Yes, this compiles. But what we have here is an Agent that has access to an OpenAI client (configured for OpenRouter) and that can get a user message by reading from stdin on the terminal.

Now let’s add the missing index.js:

const OpenAI = require("openai");
const readline = require("readline");
const Agent = require("./agent");
const tools = require("./tools");

if (!process.env.OPENROUTER_API_KEY) {
  console.error("Please set OPENROUTER_API_KEY environment variable");
  process.exit(1);
}

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

function getUserMessage() {
  return new Promise((resolve) => {
    rl.question("\x1b[94mYou\x1b[0m: ", (input) => {
      const trimmed = input.trim();
      if (trimmed === "") resolve(null);
      resolve(trimmed);
    });
  });
}

async function main() {
  const agent = new Agent(client, getUserMessage, []);
  try {
    await agent.run();
  } catch (error) {
    console.error("Error:", error.message);
  } finally {
    rl.close();
    process.exit(0);
  }
}

main();

And tools.js as an empty array for now:

const tools = [];

module.exports = tools;

Let’s run it:

export OPENROUTER_API_KEY="your_api_key_here"
pnpm start

Then you can just talk to Claude, like this:

$ pnpm start

Chat with Claude (use 'ctrl-c' to quit)

You: Hey! I'm [Your Name]! How are you?

Claude: Hi [Your Name]! I'm doing well, thanks for asking. It's nice to meet you. How are you doing today? Is there something I can help you with?

You:

Notice how we kept the same conversation going over multiple turns. It remembers my name from the first message. The conversation grows longer with every turn and we send the whole conversation every time.

Okay, let’s move on, because this is not an agent yet. What’s an agent? An LLM with access to tools, giving it the ability to modify something outside the context window.

A First Tool

An LLM with access to tools? You send a prompt to the model that says it should reply in a certain way if it wants to use "a tool". Then you, as the receiver, "use the tool" by executing it and replying with the result.

To make (1) easier, the big model providers have built-in APIs to send tool definitions along.

Okay, now let’s build our first tool: read_file

The read_file tool

In order to define the read_file tool, we’re going to use JSON schemas, but keep in mind: this will all end up as strings that are sent to the model.

Each tool requires:

• A name
• A description
• An input schema (JSON schema)
• A function that executes the tool

So let’s add that to our tools.js:

const fs = require("fs/promises");

const readFileSchema = {
  type: "object",
  properties: {
    path: {
      type: "string",
      description: "The path to the file to read",
    },
  },
  required: ["path"],
};

async function readFile(input) {
  const { path } = input;
  try {
    const content = await fs.readFile(path, "utf-8");
    return content;
  } catch (error) {
    throw new Error(`Failed to read file: ${error.message}`);
  }
}

const tools = [
  {
    name: "read_file",
    description: "Read the contents of a file at the given path.",
    inputSchema: readFileSchema,
    required: ["path"],
    function: readFile,
  },
];

module.exports = tools;

Nothing fancy here. It’s a single async function, readFile, and descriptions the model will see.

Now, update index.js to use the tools:

const tools = require("./tools");
const agent = new Agent(client, getUserMessage, tools);

Time to try it!

$ pnpm start

Chat with Claude (use 'ctrl-c' to quit)

You: what's in index.js?

Claude: I'll help you check what's in the index.js file. Let me read it for you.

tool: read_file({"path":"index.js"})

Claude: Based on my review, index.js implements the main entry point for a Node.js CLI application that creates an AI agent. Here's a summary: - Imports necessary modules including OpenAI client, readline for CLI input, and custom Agent and tools - Checks for the OPENROUTER_API_KEY environment variable - Configures the OpenAI client to use OpenRouter's API endpoint - Sets up a readline interface for user input with colored prompts - Defines an async function to get user input - Initializes the Agent with the client, input function, and tools - Runs the agent in a try-catch block for error handling - Closes the readline interface and exits gracefully The code essentially bootstraps a conversational AI assistant that can interact with the user via command line and potentially use tools for additional functionality.

You:

It can read files now!

The list_files tool

If you’re anything like me, the first thing you do when you log into a new computer is to get your bearings by running ls.

Let’s give Claude the same ability:

const listFilesSchema = {
  type: "object",
  properties: {
    path: {
      type: "string",
      description:
        "Optional path to list files from, defaults to current directory",
    },
  },
  required: [],
};

async function listFiles(input) {
  const dir = input.path || ".";
  try {
    const entries = await fs.readdir(dir, { withFileTypes: true });
    const files = entries.map((entry) => {
      return entry.isDirectory() ? `${entry.name}/` : entry.name;
    });
    return JSON.stringify(files);
  } catch (error) {
    throw new Error(`Failed to list files: ${error.message}`);
  }
}

Add to tools array:

{
  name: 'list_files',
  description: 'List files and directories at the given path. If no path provided, lists current directory.',
  inputSchema: listFilesSchema,
  required: [],
  function: listFiles,
},

Let’s ask Claude what it can see in this directory.

$ pnpm start

Chat with Claude (use 'ctrl-c' to quit)

You: what do you see in this directory?

Claude: I'll help you see what's in the current directory. Let me list the files and directories for you.

tool: list_files({})

Claude: I can see several files and directories in the current directory: - README.md - agent.js - how-to-build-an-agent-js.md - index.js - node_modules/ - package.json - plan.md - tools.js - .gitignore

You:

Works! It can list the directory.

Let it edit_file

The last tool is edit_file — a tool that lets Claude edit files.

const editFileSchema = {
  type: 'object',
  properties: {
    path: {
      type: 'string',
      description: 'The path to the file to edit',
    },
    old_str: {
      type: 'string',
      description: 'The string to search for and replace. If empty, creates a new file.',
    },
    new_str: {
      type: 'string',
      description: 'The replacement string',
    },
  },
  required: ['path', 'old_str', 'new_str'],
};

async function editFile(input) {
  const { path, old_str, new_str } = input;
  try {
    let content = await fs.readFile(path, 'utf-8');
    if (content.includes(old_str)) {
      content = content.replace(old_str, new_str);
      await fs.writeFile(path, content, 'utf-8');
      return 'File edited successfully';
    } else if (old_str === '') {
      await fs.writeFile(path, new_str, 'utf-8');
      return 'File created successfully';
    } else {
      throw new Error('old_str not found in file');
    }
  } catch (error) {
    throw new Error(`Failed to edit file: ${error.message}`);
  }
}

{
  name: 'edit_file',
  description: 'Edit a file by replacing old_str with new_str. If old_str is empty, creates a new file.',
  inputSchema: editFileSchema,
  required: ['path', 'old_str', 'new_str'],
  function: editFile,
},

Let’s tell Claude to create a new FizzBuzz function.

$ pnpm start

Chat with Claude (use 'ctrl-c' to quit)

You: hey claude, create fizzbuzz.js that I can run with Nodejs and that has fizzbuzz in it and executes it

Claude: I'll create a fizzbuzz.js file that you can run with Node.js. First, let me check if the file already exists:

tool: list_files({})

Claude: I don't see a fizzbuzz.js file, so I'll create one with a classic FizzBuzz implementation. This program will print numbers from 1 to 100, but for multiples of 3 it will print "Fizz", for multiples of 5 it will print "Buzz", and for numbers that are multiples of both 3 and 5 it will print "FizzBuzz".

tool: edit*file({"path":"fizzbuzz.js","old_str":"","new_str":"/\**\\n _ FizzBuzz implementation in JavaScript\\n _ Prints numbers from 1 to 100, but:\\n _ - For multiples of 3, print \\"Fizz\\" instead of the number\\n _ - For multiples of 5, print \\"Buzz\\" instead of the number\\n \_ - For multiples of both 3 and 5, print \\"FizzBuzz\\"\\n \*/\\n\\nfunction fizzBuzz(n) {\\n for (let i = 1; i <= n; i++) {\\n let output = '';\\n \\n if (i % 3 === 0) output += 'Fizz';\\n if (i % 5 === 0) output += 'Buzz';\\n \\n console.log(output || i);\\n }\\n}\\n\\n// Execute FizzBuzz for numbers 1 to 100\\nconsole.log('Running FizzBuzz:');\\nfizzBuzz(100);"})

Claude: I've created a fizzbuzz.js file that you can run with Node.js. The program: 1. Defines a function called `fizzBuzz` that takes a parameter `n` for the upper limit 2. Loops from 1 to n (set to 100 in the execution) 3. For each number: - If it's divisible by 3, it adds "Fizz" to the output - If it's divisible by 5, it adds "Buzz" to the output - If it's divisible by both, it adds both resulting in "FizzBuzz" - If it's not divisible by either 3 or 5, it outputs the number itself 4. The script automatically executes the function for numbers 1 to 100 You can run this script using Node.js with the following command in your terminal: node fizzbuzz.js This will output the FizzBuzz sequence from 1 to 100 to your console.

Right?! It’s impressive, isn’t it? And that’s the most basic implementation of an agent you can probably come up with.

Isn’t this amazing?

If you’re anything like the engineers I’ve talked to, chances are that, while reading this, you have been waiting for the rabbit to be pulled out of the hat. But it’s not.

This is essentially all there is to the inner loop of a code-editing agent. Sure, integrating it into your editor, tweaking the system prompt, giving it the right feedback at the right time, a nice UI around it, support for multiple agents, and so on — we’ve built all of that in Amp, but it didn’t require moments of genius. All that was required was practical engineering and elbow grease.

These models are incredibly powerful now. 300 lines of code and three tools and now you’re to be able to talk to an alien intelligence that edits your code.

That’s why everything’s changing.

This article, including all code generation, implementation, and debugging, was by Amp Free.

This implementation was built in this AmpCode thread.

Inspired by Thorsten Ball's original article on building agents in Golang.