github.com\/juustesout\/javascript-agents-example<\/a><\/p>\n\n\n\n
\n\n\n\n1. Installation \u2014 Zero Dependencies<\/h2>\n\n\n\n
You only need Node.js 18+<\/strong> (for the global fetch<\/code>) and an OpenAI API key. No npm install<\/code>, no packages:<\/p>\n\n\n\ngit clone https:\/\/github.com\/juustesout\/javascript-agents-example.git\ncd javascript-agents-example\ncp .env.example .env\n<\/code><\/pre>\n\n\n\nOpen .env<\/code> and add your OpenAI key:<\/p>\n\n\n\nOPENAI_API_KEY=sk-proj-your-key-here\nOPENAI_MODEL=gpt-4o-mini # optional, default\nAGENT_VERBOSE=1 # set to 0 to silence trace\n<\/code><\/pre>\n\n\n\nThe .gitignore<\/code> already has **\/.env<\/code> \u2014 your key stays local. The agent loads .env<\/code> automatically via its own built-in loadEnv()<\/code> function, so you never have to export<\/code> anything.<\/p>\n\n\n\nAnd that is it. Run the demo immediately:<\/p>\n\n\n\n
node 01_mini_agent\/demo.js\n<\/code><\/pre>\n\n\n\n
\n\n\n\n2. Project Structure<\/h2>\n\n\n\njavascript-agents-example\/\n\u251c\u2500\u2500 01_mini_agent\/\n\u2502 \u251c\u2500\u2500 agent.js # The core loop + 3 hand-written tools\n\u2502 \u251c\u2500\u2500 demo.js # Entry point with example prompts\n\u2502 \u2514\u2500\u2500 sample.txt # A test file for the file reader tool\n\u251c\u2500\u2500 02_agent_vs_agent\/\n\u2502 \u2514\u2500\u2500 game.js # Two agents negotiate a $100 split\n\u251c\u2500\u2500 package.json # ESM, zero dependencies\n\u2514\u2500\u2500 .env.example\n<\/code><\/pre>\n\n\n\n01_mini_agent<\/strong> is a complete agent in two files. 02_agent_vs_agent<\/strong> proves multi-agent is just two copies of the same loop with different system prompts.<\/p>\n\n\n\n
\n\n\n\n3. The Core Loop \u2014 How Every Agent Works<\/h2>\n\n\n\n
Here is the whole trick in four steps:<\/p>\n\n\n\n
\n- The model receives the full conversation history<\/strong> plus a list of tool schemas<\/strong> (name, description, expected JSON arguments).<\/li>\n\n\n\n
- The model replies with either plain text<\/strong> (it is ready to answer) or one or more tool calls<\/strong> (JSON like
{\"name\": \"calculator\", \"arguments\": {\"expression\": \"2+2\"}}<\/code>).<\/li>\n\n\n\n- If it is a tool call, you<\/strong> run the matching JavaScript function and append the result as a
role=\"tool\"<\/code> message. Not a framework, not the model \u2014 your code.<\/li>\n\n\n\n- Repeat from step 1 until the model returns plain text. That text is the final answer.<\/li>\n<\/ol>\n\n\n\n
The whole loop: model \u2192 tool \u2192 result \u2192 model \u2192 \u2026 \u2192 answer<\/strong>.<\/p>\n\n\n\nThe MiniAgent class<\/h3>\n\n\n\nexport class MiniAgent {\n constructor(systemPrompt, { model, temperature, maxToolIters, verbose } = {}) {\n this.messages = []; \/\/ the only \"memory\" \u2014 an array of plain objects\n this.tools = {}; \/\/ name -> { schema, fn } registry\n this.systemPrompt = systemPrompt;\n this.model = model || DEFAULT_MODEL;\n this.temperature = temperature ?? 0.7;\n this.maxToolIters = maxToolIters ?? DEFAULT_MAX_TOOL_ITERS;\n this.verbose = verbose ?? DEFAULT_VERBOSE;\n }\n}\n<\/code><\/pre>\n\n\n\nThe agent has three things: a message list, a tool registry and configuration. That is all the state there is.<\/p>\n\n\n\n
The run()<\/code> method \u2014 the heart of every agent<\/h3>\n\n\n\nThis is where the magic (or rather: the lack of magic) lives:<\/p>\n\n\n\n
async run(userPrompt, { reset = true } = {}) {\n if (reset || this.messages.length === 0) {\n this.messages = [\n { role: \"system\", content: this.systemPrompt },\n { role: \"user\", content: userPrompt },\n ];\n } else {\n this.messages.push({ role: \"user\", content: userPrompt });\n }\n\n for (let iteration = 1; iteration <= this.maxToolIters; iteration++) {\n this._log(`iteration ${iteration}: calling the model...`, _DIM);\n const reply = await this._callModel();\n\n if (reply.tool_calls && reply.tool_calls.length > 0) {\n await this._handleToolCalls(reply.tool_calls);\n continue; \/\/ loop back to the model\n }\n\n \/\/ No tool calls \u2192 final answer\n const answer = reply.content || \"\";\n this.messages.push({ role: \"assistant\", content: answer });\n this._log(\"final answer received.\", _DIM);\n return answer;\n }\n\n throw new Error(`No answer after ${this.maxToolIters} iterations.`);\n}\n<\/code><\/pre>\n\n\n\nEvery iteration prints a color trace so you can watch the agent think, call a tool, read the result, and decide what to do next \u2014 in real time.<\/p>\n\n\n\n
How _callModel()<\/code> works<\/h3>\n\n\n\nThis is the only network call in the whole project. It converts the tool registry into OpenAI’s JSON schema format and sends the entire conversation alongside it:<\/p>\n\n\n\n
async _callModel() {\n const toolSpecs = Object.values(this.tools).map(t => ({\n type: \"function\",\n function: t.schema,\n }));\n\n const body = {\n model: this.model,\n messages: this.messages,\n temperature: this.temperature,\n tools: toolSpecs.length > 0 ? toolSpecs : undefined,\n tool_choice: toolSpecs.length > 0 ? \"auto\" : undefined,\n };\n\n const res = await fetch(`${this.baseUrl}\/chat\/completions`, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application\/json\",\n Authorization: `Bearer ${this.apiKey}`,\n },\n body: JSON.stringify(body),\n });\n\n if (!res.ok) {\n const err = await res.text();\n throw new Error(`OpenAI API error ${res.status}: ${err}`);\n }\n\n const data = await res.json();\n return data.choices[0].message;\n}\n<\/code><\/pre>\n\n\n\nKey insight:<\/strong> The tools<\/code> array is just JSON describing your functions. The model does not<\/em> run anything \u2014 it only requests<\/em> a call. You<\/strong> execute the function. That is the line between a “chatbot” and an “agent”.<\/p>\n\n\n\nHow tool results get back into context<\/h3>\n\n\n\n
The OpenAI API has a strict protocol: the tool call must be recorded as an assistant message before<\/em> the results, and each result must be tagged with the matching tool_call_id<\/code>:<\/p>\n\n\n\nasync _handleToolCalls(toolCalls) {\n \/\/ 1. Record the assistant message with the tool call requests\n this.messages.push({\n role: \"assistant\",\n content: null,\n tool_calls: toolCalls.map(call => ({\n id: call.id,\n type: \"function\",\n function: {\n name: call.function.name,\n arguments: call.function.arguments,\n },\n })),\n });\n\n \/\/ 2. Execute each tool and append its result\n for (const call of toolCalls) {\n const result = await this._executeTool(\n call.function.name,\n call.function.arguments\n );\n this.messages.push({\n role: \"tool\",\n tool_call_id: call.id,\n content: result,\n });\n }\n}\n<\/code><\/pre>\n\n\n\nThis is where most home-grown agents fail: the API will reject your next request unless role=\"tool\"<\/code> messages are correctly paired with the tool_call_id<\/code> from the assistant message. If you ever get a 400 error when building your own agent, this is the first place to look.<\/p>\n\n\n\nExecuting a tool<\/h3>\n\n\n\nasync _executeTool(name, argumentsJson) {\n const tool = this.tools[name];\n if (!tool) return `Error: unknown tool '${name}'.`;\n\n try {\n const args = JSON.parse(argumentsJson || \"{}\");\n this._log(` -> ${name}(${JSON.stringify(args)})`, _YELLOW);\n const result = await tool.fn(...Object.values(args));\n this._log(` <- result: ${String(result).slice(0, 120)}`, _MAGENTA);\n return String(result);\n } catch (exc) {\n return `Error calling '${name}': ${exc.message}`;\n }\n}\n<\/code><\/pre>\n\n\n\nYes, that is the entire tool execution engine. A function lookup, a JSON parse and a function call. All the complexity of frameworks lives in 15 lines of real code.<\/p>\n\n\n\n
\n\n\n\n4. Tools \u2014 Just Plain Functions<\/h2>\n\n\n\n
A tool in this system has three parts: a name<\/strong>, a JSON schema<\/strong> (telling the model what it does and what arguments it expects) and a JavaScript function<\/strong> that does the work. Tools are registered like this:<\/p>\n\n\n\naddTool(name, description, parameters, fn) {\n this.tools[name] = {\n schema: { name, description, parameters },\n fn,\n };\n return this; \/\/ allows chaining\n}\n<\/code><\/pre>\n\n\n\nThat is it. Three lines. Let us look at the three tools that ship with the agent.<\/p>\n\n\n\n
Tool 1: Calculator \u2014 hand-written recursive descent parser<\/h3>\n\n\n\n
The Python version uses ast.parse()<\/code> for safety. JavaScript does not have that, so we write a recursive descent parser<\/strong> by hand \u2014 which is actually a better demonstration: you can see the exact grammar the model is allowed to use.<\/p>\n\n\n\nThe grammar (bottom to top, increasing precedence):<\/p>\n\n\n\n
additive \u2192 multiplicative ((\"+\" | \"-\") multiplicative)*\nmultiplicative \u2192 unary ((\"*\" | \"\/\" | \"\/\/\" | \"%\") unary)*\nunary \u2192 (\"+\" | \"-\")* power\npower \u2192 primary (\"**\" unary)?\nprimary \u2192 number | constant | \"(\" additive \")\"\n<\/code><\/pre>\n\n\n\nEach grammar rule becomes a function that parses from the current position, consuming characters and returning a number. The beauty of this approach:<\/p>\n\n\n\n
function parseAdditive() {\n let value = parseMultiplicative();\n while (true) {\n skipWs();\n if (src[pos] === \"+\") {\n pos++;\n value += parseMultiplicative();\n } else if (src[pos] === \"-\") {\n pos++;\n value -= parseMultiplicative();\n } else { break; }\n }\n return value;\n}\n<\/code><\/pre>\n\n\n\nThe parser accepts + - * \/ \/\/ % **<\/code>, parentheses, decimal numbers and the constants pi<\/code> and e<\/code>. Anything else \u2014 function calls, object access, JavaScript keywords \u2014 causes a SyntaxError<\/code>. The model can only<\/em> do arithmetic, no matter how creative it tries to be.<\/p>\n\n\n\nDivision by zero is caught at runtime, and \/\/<\/code> implements Python-style floor division with Math.floor()<\/code>:<\/p>\n\n\n\n} else if (src[pos] === \"\/\" && src[pos + 1] === \"\/\") {\n pos += 2;\n const divisor = parseUnary();\n if (divisor === 0) throw new SyntaxError(\"division by zero\");\n value = Math.floor(value \/ divisor);\n}\n<\/code><\/pre>\n\n\n\nexport function calculator(expression) {\n try {\n return String(_parseExpression(expression));\n } catch (exc) {\n return `Error: ${exc.message ?? exc}`;\n }\n}\n<\/code><\/pre>\n\n\n\nTool 2: Safe file reader (path traversal defence)<\/h3>\n\n\n\n
Reading a file seems trivial until the model says \"Read me ..\/..\/etc\/passwd\"<\/code>. The defence is path.relative()<\/code> \u2014 if the resolved path walks “up” past the allowed base directory, we refuse:<\/p>\n\n\n\nexport function read_local_file(filepath) {\n try {\n const base = resolve(_DEFAULT_BASE_DIR);\n const target = resolve(base, String(filepath));\n\n const rel = relative(base, target);\n if (rel.startsWith(\"..\") || isAbsolute(rel)) {\n return `Error: '${filepath}' escapes the allowed directory. Path traversal blocked.`;\n }\n if (!existsSync(target)) {\n return `Error: file not found.`;\n }\n const stat = statSync(target);\n if (stat.size > _MAX_FILE_BYTES) {\n return `Error: file too large (limit ${_MAX_FILE_BYTES} bytes).`;\n }\n return readFileSync(target, \"utf8\").replace(\/\\s+$\/, \"\");\n } catch (exc) {\n return `Error reading file: ${exc.message ?? exc}`;\n }\n}\n<\/code><\/pre>\n\n\n\nEven a path like ..\/..\/..\/..\/etc\/passwd<\/code> ends up as an absolute path outside<\/em> the base after resolve()<\/code>, and relative()<\/code> returns \"..\/..\/etc\/passwd\"<\/code> which starts with \"..\"<\/code> \u2014 blocked.<\/p>\n\n\n\nTool 3: Web search (zero API key, scrapes DuckDuckGo)<\/h3>\n\n\n\n
The Python version uses the ddgs<\/code> package. The JavaScript version does the same with zero new dependencies<\/strong> \u2014 it fetches the public DuckDuckGo HTML endpoint and uses two regexes to extract titles, URLs and snippets:<\/p>\n\n\n\nexport async function web_search(query, max_results = 5) {\n const url = `https:\/\/html.duckduckgo.com\/html\/?q=${encodeURIComponent(query)}`;\n try {\n const res = await fetch(url, {\n headers: {\n \"User-Agent\": \"Mozilla\/5.0 (compatible; node-agents-example\/1.0)\",\n },\n signal: AbortSignal.timeout(15_000),\n });\n\n const html = await res.text();\n const titleRe = \/class=\"result__a\"[^>]*href=\"([^\"]+)\"[^>]*>(.*?)<\\\/a>\/gs;\n const snippetRe = \/class=\"result__snippet\"[^>]*>(.*?)<\\\/a>\/gs;\n\n const anchors = [...html.matchAll(titleRe)];\n const snippets = [...html.matchAll(snippetRe)];\n\n \/\/ Unwrap DuckDuckGo's redirect URL\n const uddg = href.match(\/uddg=([^&]+)\/);\n if (uddg) href = decodeURIComponent(uddg[1]);\n\n return lines.join(\"\\n\\n\");\n } catch (exc) {\n return `Error: web search failed: ${exc.message ?? exc}`;\n }\n}\n<\/code><\/pre>\n\n\n\nThe fetch<\/code> API is native in Node 18+. The regex-based scraping is a bit more fragile than the Python ddgs<\/code> library, but it keeps the zero-dependency promise. Swap this for a real search API (Tavily, SerpAPI, Google Custom Search) in minutes \u2014 the tool interface never changes.<\/p>\n\n\n\nRegistering tools on the agent<\/h3>\n\n\n\n
The convenience function registerBuiltinTools()<\/code> wires all three tools to a MiniAgent instance:<\/p>\n\n\n\nexport function registerBuiltinTools(agent) {\n agent\n .addTool(\"calculator\",\n \"Evaluate a mathematical expression...\",\n {\n type: \"object\",\n properties: {\n expression: { type: \"string\", description: \"The expression to evaluate.\" },\n },\n required: [\"expression\"],\n },\n calculator\n )\n .addTool(\"read_local_file\",\n \"Read the contents of a text file...\",\n {\n type: \"object\",\n properties: {\n filepath: { type: \"string\", description: \"Relative path of the file.\" },\n },\n required: [\"filepath\"],\n },\n read_local_file\n )\n .addTool(\"web_search\",\n \"Search the web using DuckDuckGo...\",\n {\n type: \"object\",\n properties: {\n query: { type: \"string\", description: \"The search query.\" },\n max_results: { type: \"integer\", description: \"Max results (default 5).\" },\n },\n required: [\"query\"],\n },\n web_search\n );\n return agent;\n}\n<\/code><\/pre>\n\n\n\nAdding your own tool is always three things: a function<\/strong>, a schema<\/strong>, and a call to addTool()<\/code><\/strong>. That is the entire API.<\/p>\n\n\n\n
\n\n\n\n