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.
We are building a local personal coding agent.
It runs in the terminal and helps us understand a JavaScript project. It can:
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.
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:
These same ideas appear in larger AI-agent frameworks. This project keeps them small enough to understand.
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.
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 pointsrc/agent.js
: agent loop and tool dispatchsrc/ollama.js
: local Ollama API clientsrc/tools.js
: safe filesystem toolstest/tools.test.js
: safety and tool behavior testsThe 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:
--root
if the user provides it--model
if providedOLLAMA_MODEL
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
.
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
The system prompt tells the model how to behave.
In this project, the prompt says the model should:
propose_patch
only for suggested changesIt 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.
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.
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
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 doesparameters
: tells the model what arguments it acceptsrun
: the actual JavaScript functionExample 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. **
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.
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.
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.
The project uses Vitest.
From package.json
:
{
"scripts": {
"test": "vitest run",
"test:watch": "vitest"
}
}
The tests cover the dangerous parts:
safeResolve
allows normal pathssafeResolve
blocks ../
traversallist_files
handles missing directoriesread_file
rejects missing paths and directoriesread_file
rejects large filessearch_text
skips large filespropose_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.
If you run:
npm start -- "Explain src/tools.js"
the flow is:
src/cli.js
receives the request.runAgent
.src/agent.js
creates safe tools.src/ollama.js
sends the prompt to local Ollama.That is an AI agent in practical terms.
It is an LLM connected to a controlled loop, safe tools, and clear rules.
Requirements:
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
An AI agent is not just an LLM.
An AI agent is usually:
LLM + loop + tools + context + safety rules
In this project:
safeResolve
protects file accessThe model can request actions, but JavaScript decides what actually runs.
That is the key idea.
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:
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.