Welcome to the 4th article of the MCP and RAG with JS series.

In this article, we will learn what AI agents are by building a practical, beginner-friendly coding agent in JavaScript. We will use a locally running LLM, Mistral on Ollama.

You do not need any paid subscription or API key. Everything runs locally on your machine, so this is accessible for learning, testing, and experimenting.

What We Are Building

We are building a local personal coding agent.

It runs in the terminal and helps us understand a JavaScript project. It can:

• list project files
• read project files
• search text
• explain code
• find possible bugs
• propose code changes

The important safety rule is this:

The agent can inspect files, but it does not directly edit them. If it wants to change something, it only returns a patch proposal for a human developer to review.

So in simple words, we are building a small local coding assistant.

Why This Helps Us Learn

AI agents can sound complicated, but most agent systems use a few common patterns.

In this project, we will learn those patterns with plain JavaScript:

• Agent loop: repeat until the model gives a final answer.
• Tool calling: let the model request specific JavaScript functions.
• Tool allowlist: only allow approved tools to run.
• System prompt: tell the model how it should behave.
• JSON action protocol: make the model respond with structured JSON.
• Model adapter: keep the Ollama HTTP code in one small file.
• Safety boundary: keep file access inside the project root.
• Human-in-the-loop changes: propose patches instead of applying them.
• Tests for safety: verify path traversal, large file, and missing file behavior.

These same ideas appear in larger AI-agent frameworks. This project keeps them small enough to understand.

The Big Idea

A normal chatbot usually works like this:

User asks question -> Model answers

An agent works more like this:

User asks question
  -> Model decides what to do
  -> JavaScript runs a safe tool
  -> Model sees the tool result
  -> Model answers

The model does not directly read your files or run commands. It asks for a tool, and your JavaScript code decides whether that tool is allowed.

That is the main idea behind this project.

Project Structure

You can explore and clone the complete codebase in the coding-agents GitHub repository.
The important files are:

.
|-- package.json
|-- src
|   |-- cli.js
|   |-- agent.js
|   |-- ollama.js
|   `-- tools.js
`-- test
    `-- tools.test.js

Each file has a clear job:

• src/cli.js: terminal entry point
• src/agent.js: agent loop and tool dispatch
• src/ollama.js: local Ollama API client
• src/tools.js: safe filesystem tools
• test/tools.test.js: safety and tool behavior tests

1: CLI Entry Point

The app starts in src/cli.js.

It imports the agent:

import { runAgent } from "./agent.js";

Then it chooses the project root and model:

const root = options.root || process.cwd();
const model = options.model || process.env.OLLAMA_MODEL || "mistral";

This means:

• use --root if the user provides it
• otherwise use the current folder
• use --model if provided
• otherwise use OLLAMA_MODEL
• otherwise use mistral

The CLI supports two modes.

One-shot mode:

npm start -- "Explain src/tools.js"

Interactive mode:

npm start

In both cases, the CLI eventually calls:

const answer = await runAgent({ goal, root, model, verbose });

So the CLI is only responsible for input and output. The real agent behavior lives in runAgent.

2: Agent Loop

The main function is in src/agent.js:

export async function runAgent({ goal, root, model, verbose = false }) {

At the start, it creates the available tools:

const { createTools } = await import("./tools.js");
const tools = createTools({ root });

Passing root is important. It tells the tools which folder they are allowed to inspect.

Then the agent creates a message history:

const messages = [
  {
    role: "system",
    content: buildSystemPrompt(tools)
  },
  {
    role: "user",
    content: goal
  }
];

The system message contains rules for the model. The user message contains the developer's request.

Then the agent runs a loop:

for (let step = 1; step <= MAX_STEPS; step += 1) {
  const prompt = renderPrompt(messages);
  const raw = await generateWithOllama({ prompt, model });
  const action = parseAction(raw);

  // final answer or tool call
}

MAX_STEPS is set to 8, so the agent cannot loop forever.

This loop is the heart of the agent:

messages -> prompt -> model -> action -> tool or final answer

3: System Prompt

The system prompt tells the model how to behave.

In this project, the prompt says the model should:

• inspect files before making project-specific claims
• never claim a patch was applied
• use propose_patch only for suggested changes
• return exactly one JSON object

It also describes the available tools:

const toolDescriptions = Object.entries(tools)
  .map(([name, tool]) => `- ${name}: ${tool.description} Parameters: ${JSON.stringify(tool.parameters)}`)
  .join("\n");

This lets the model know what it can ask for.

The model must respond in one of two shapes.

To call a tool:

{"type":"tool","name":"read_file","arguments":{"path":"src/example.js"}}

To finish:

{"type":"final","answer":"Your answer here."}

This is a simple JSON action protocol. It is easy to understand because there is no hidden framework magic.

4: Local Model Adapter

The file src/ollama.js keeps the Ollama API call separate from the rest of the app.

The default local URL is:

const DEFAULT_OLLAMA_URL = "http://127.0.0.1:11434";

The function sends the prompt to Ollama:

const response = await fetch(`${baseUrl}/api/generate`, {
  method: "POST",
  headers: {
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model,
    prompt,
    stream: false,
    options: {
      temperature
    }
  })
});

Then it returns the model text:

const data = await response.json();
return data.response || "";

This file has one job:

prompt in -> Ollama HTTP request -> model response out

Keeping this in one file makes it easier to swap models later.

5: Tool Calling

After Ollama responds, the agent parses the response:

const action = parseAction(raw);

If the model gives a final answer, the agent returns it:

if (action.type === "final") {
  return action.answer;
}

If the model asks for a tool, the agent checks whether that tool exists:

const tool = tools[action.name];
if (!tool) {
  messages.push({
    role: "tool",
    content: JSON.stringify({
      error: `Unknown tool: ${action.name}`,
      allowedTools: Object.keys(tools)
    })
  });
  continue;
}

This is very important.

The model cannot invent tools. It can only use tools that exist in the local JavaScript object.

Then the agent runs the tool:

const result = await tool.run(action.arguments || {});

And sends the result back into the message history:

messages.push({
  role: "tool",
  content: JSON.stringify({
    tool: action.name,
    result
  })
});

Now the model can use real project information instead of guessing.

Example flow:

User: Explain src/tools.js
Model: calls read_file
JavaScript: reads the file safely
Model: sees the file content
Model: gives final explanation

6: Safe Tools

The tools live in src/tools.js.

The project has four tools:

list_files
read_file
search_text
propose_patch

Each tool has:

• description: tells the model what it does
• parameters: tells the model what arguments it accepts
• run: the actual JavaScript function

Example shape:

read_file: {
  description: "Read a UTF-8 text file from inside the project root.",
  parameters: {
    path: "File path relative to project root."
  },
  run: async ({ path: filePath } = {}) => {
    // safe implementation
  }
}

The tools are intentionally narrow.

list_files lists files under the project root.

read_file reads one text file if it is safe and not too large.

search_text searches project files for a string or regex.

propose_patch returns a patch proposal, but does not apply it.

That last point matters. The model can suggest changes, but a human still reviews them.
** use a safe regex engine if you are planning to expose the agent to external user inputs. **

7: Path Safety With safeResolve

The most important safety function is:

export function safeResolve(root, requestedPath) {
  const absolute = path.resolve(root, requestedPath);
  const relative = path.relative(root, absolute);

  if (relative.startsWith("..") || path.isAbsolute(relative)) {
    throw new Error(`Path escapes project root: ${requestedPath}`);
  }

  return absolute;
}

This blocks path traversal.

For example, this should be allowed:

src/tools.js

But this should be blocked:

../outside.txt

Why?

Because the agent should only inspect the selected project folder. Model output is not trusted input, so every requested path goes through safeResolve.

This is one of the most important lessons in agent development:

Give the model useful tools, but put real safety checks in code.

8: Size Limits

The tool layer also avoids reading huge files:

const MAX_READ_BYTES = 80_000;
const MAX_SEARCH_FILE_BYTES = 250_000;

read_file throws an error if a file is too large.

search_text skips files that are too large.

This protects the model context and keeps the agent responsive.

9: Patch Proposals, Not Auto-Edits

The propose_patch tool returns:

{
  summary,
  patch,
  applied: false,
  note: "Patch proposal only. Review before applying."
}

This is a human-in-the-loop design.

The agent can help you think and propose changes, but it does not silently modify your files.

For a beginner agent, this is a good safety tradeoff.

10: Tests for Safety

The project uses Vitest.

From package.json:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

The tests cover the dangerous parts:

• safeResolve allows normal paths
• safeResolve blocks ../ traversal
• list_files handles missing directories
• read_file rejects missing paths and directories
• read_file rejects large files
• search_text skips large files
• propose_patch returns applied: false

Example traversal test:

expect(() => safeResolve(fixtureProjectRoot, "../outside.txt")).toThrow(/escapes project root/);

Example large-file test:

await expect(tools.read_file.run({ path: "large-read.txt" })).rejects.toThrow(/too large to read safely/);

Tests are not just for correctness here. They protect the safety boundary of the agent.

Complete Request Flow

If you run:

npm start -- "Explain src/tools.js"

the flow is:

1. src/cli.js receives the request.
2. It calls runAgent.
3. src/agent.js creates safe tools.
4. The system prompt describes the rules and tools.
5. src/ollama.js sends the prompt to local Ollama.
6. The model returns a JSON action.
7. If it asks for a tool, the agent checks the allowlist.
8. The tool runs with safety checks.
9. The tool result goes back to the model.
10. The model returns a final answer.

That is an AI agent in practical terms.

It is an LLM connected to a controlled loop, safe tools, and clear rules.

How to Run It

Requirements:

• Node.js 18 or newer
• Ollama installed
• Mistral pulled locally

Pull the model:

ollama pull mistral

Start Ollama:

ollama serve

Run the agent:

npm start

Ask one question:

npm start -- "Explain src/agent.js"

Inspect another project:

npm start -- --root /path/to/project "Find bugs in the main CLI file"

Run tests:

npm test

Run syntax checks:

npm run check

What to Remember

An AI agent is not just an LLM.

An AI agent is usually:

LLM + loop + tools + context + safety rules

In this project:

• the CLI gets the user request
• the agent loop manages steps
• Ollama provides the local model
• tools provide controlled abilities
• safeResolve protects file access
• tests protect the safety behavior

The model can request actions, but JavaScript decides what actually runs.

That is the key idea.

Final Thoughts

This project is intentionally small, but it teaches the foundation behind many larger agent systems.

Once you understand this version, you can explore more advanced ideas like:

• memory across chat turns
• streaming model output
• richer tool schemas
• patch validation
• confirmation-based patch applying
• MCP tools
• RAG over larger codebases

But the core idea stays the same:

Mistral is a good simple default for learning, but when you are building stronger coding agents, coding-focused models usually give better results. Good options to try are qwen2.5-coder, deepseek-coder, and Gemma.

Build useful tools, keep them narrow, and let your application code enforce the safety boundaries.