Disclaimer

• For learning & research only.
• Not investment or legal advice.
• Code is simplified — use at your own risk.

Kha Do · FIT-HCMUS · [email protected] — inspired by Stanford CS146S "The Modern Software Developer".

What we'll cover

What is an LLM?

Tokens — how a model reads text

Models read tokens: chunks of text, not whole words.

One word can split into several tokens; leading spaces count too.

Why the same prompt gives different answers

The model returns a distribution, not one fixed answer. Sampling picks; temperature controls variety.

Same prompt, different reply? That's sampling. For coding agents, keep temperature low.

How an LLM works — step by step

One token at a time:

How does it "learn"? Three stages

A text-predictor becomes an assistant in stages:

Key concepts to know

Honest limits

Language matters less than you'd think

To an LLM, language is mostly tokens + examples. If it has seen enough, it can help.

LLMs lower the language barrier, not the need for engineering judgment.

From LLM → Coding Agent

Coding agent = LLM + tools + a loop + a goal. That's the whole trick.

Anatomy of a coding agent

Think: a fast junior dev with tools and feedback. Five parts:

No tools → chatbot. No loop → one-shot script. Together → agent.

The agent loop

Tools = functions you expose. The model asks; your code executes.

The agent loop — visualized

The orange arrow is the loop: tool result → history → next model call.

How a "tool call" actually works

Key point: the model never runs code. It asks in structured text.

Tool call = structured request. Your code decides what runs.

The flow, step by step 🎬

Task: "Add subtract() to math.js and prove it works."

Each tool result is appended, so the model sees what happened.

Why the loop is powerful: self-correction

The power is not one perfect answer. It is observe → retry.

Feed the error back → the model can debug itself.

Terminology — the conversation

Every message has a role. History is the agent's memory.

Loop = append input → ask model → run tool → append result → repeat.

What we're about to build

In ~80 lines of Node.js: read, edit, run, then reply.

Step 0 — Project setup

mkdir mini-agent && cd mini-agent
npm init -y
npm pkg set type=module          # enable ES modules (import/export)

# install ONE provider SDK (they're interchangeable — pick yours):
npm install openai               # OpenAI GPT  (also talks to Ollama!)
npm install @anthropic-ai/sdk    # Anthropic Claude
npm install @google/genai        # Google Gemini

Requires Node 18+. Put keys in env vars, never code: export OPENAI_API_KEY=sk-...

Step 1 — Say hello to a model

Same pattern in every SDK: messages in, text out.

import OpenAI from "openai";
const openai = new OpenAI();

const r = await openai.chat.completions
  .create({
    model: "gpt-5.5",
    messages: [{ role: "user",
      content: "Hi in 3 words" }],
  });
console.log(
  r.choices[0].message.content);

import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();

const r = await anthropic.messages
  .create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user",
      content: "Hi in 3 words" }],
  });
console.log(r.content[0].text);

import { GoogleGenAI }
  from "@google/genai";
const ai = new GoogleGenAI({});

const r = await ai.models
  .generateContent({
    model: "gemini-2.5-flash",
    contents: "Hi in 3 words",
  });
console.log(r.text);

Keys come from env vars. We'll use the OpenAI SDK; the same code drives Ollama / Qwen3 later.

OpenAI-compatible endpoints are common. Change baseURL, keep the agent loop. Advanced features can still differ.

Step 2 — Describe the tools

A tool = name + description + parameters. The model reads this.

const tools = [
  {
    name: "read_file",
    description: "Read a file",
    parameters: { path: "string" },
  },
  {
    name: "write_file",
    description: "Write text to a file",
    parameters: { path: "string", content: "string" },
  },
  {
    name: "run_command",
    description: "Run a shell command",
    parameters: { cmd: "string" },
  },
];

Simplified; real SDKs use JSON Schema.

Step 2b — Implement the tools

Plain Node functions: the agent's hands.

import fs from "node:fs/promises";
import { execSync } from "node:child_process";

const handlers = {
  read_file:   ({ path })          => fs.readFile(path, "utf8"),
  write_file:  ({ path, content }) => fs.writeFile(path, content),
  run_command: ({ cmd })           => execSync(cmd).toString(),
};

run_command is real shell access. Sandbox or require approval.

Step 2c — Call the model with tools 🎬

Before the loop: one model call with tools.

const messages = [
  { role: "user", content: "Create hello.js that prints 'hi'." },
];

// Hand the model the tool schemas from Step 2:
const reply = await callModel(messages, tools);

console.log(reply.tool_calls);
// → [{ name: "write_file",
//      args: { path: "hello.js", content: "console.log('hi')" } }]

The model did not create the file; it requested write_file(). Loop this → agent. ↓

Step 3 — The agent loop

The whole flow, top to bottom.

const messages = [
  { role: "system", content: "You are a coding agent. Use tools to finish the task." },
  { role: "user",   content: "Create hello.js that prints 1 to 10, then run it." },
];

while (true) {
  // 1. Ask the model what to do next
  const reply = await callModel(messages, tools);
  messages.push(reply);

  // 2. No tool requested -> the model is done
  if (!reply.tool_calls) {
    console.log(reply.content);
    break;
  }

  // 3. Run each requested tool, add the result back to the history
  for (const call of reply.tool_calls) {
    const result = await handlers[call.name](call.args);
    messages.push({ role: "tool", content: String(result) });
  }
  // 4. Loop again -> the model now sees the result
}

Step 4 — What happens when it runs

user:  Create hello.js that prints 1 to 10, then run it.

model: (tool) write_file  path=hello.js
model: (tool) run_command cmd=node hello.js
tool:  1 2 3 4 5 6 7 8 9 10
model: Done. Created hello.js and ran it.

That is a working coding agent — one loop, a few tools.

Step 5 — Put it all together

agent.js wires together four pieces:

import OpenAI from "openai";

const openai = new OpenAI();                       // 1 · the model client

const tools = [ /* read_file, write_file, run_command — Step 2 */ ];

const handlers = { /* read_file, write_file, run_command — Step 2b */ };  // 2 · the tool functions

const messages = [                                 // 3 · the conversation
  { role: "system", content: "You are a coding agent. Use tools to finish the task." },
  { role: "user",   content: process.argv[2] },    // task from the command line
];

while (true) {                                     // 4 · the loop
  const res   = await openai.chat.completions.create({ model: "gpt-5.5", messages, tools });
  const reply = res.choices[0].message;
  messages.push(reply);

  if (!reply.tool_calls) { console.log(reply.content); break; }   // done

  for (const call of reply.tool_calls) {           // run tools, feed results back
    const args   = JSON.parse(call.function.arguments);
    const result = await handlers[call.function.name](args);
    messages.push({ role: "tool", tool_call_id: call.id, content: String(result) });
  }
}

Run it: node agent.js "Create hello.js that prints 1 to 10, then run it". It works; now make it reliable ↓

Step 6 — Add rules + stop condition

A bare prompt drifts. Add constraints and a stop condition.

const SYSTEM = `You are a coding agent. Use tools to finish the task.

Rules:                     // ← guide the model
- Work only inside ./workspace.
- Read before editing.
- Ask approval before destructive commands.

Done:                      // ← when to stop calling tools
- Verify after changes.
- Final answer only after verification.
- If stuck, explain why and stop.`;

Also cap the loop: while (n++ < 20) { … }. Rules guide; caps protect.

⚠️ It's a demo — real agents need a sandbox

run_command runs model-chosen commands on your machine: fine for learning, risky for real work.

Course demo: use a throwaway folder. Real use: sandbox the tools.

Choosing a model — cloud or local

Same loop: swap SDK / baseURL, keep the agent logic.

Note: chat-only models without tool calling are poor agent choices. Price table next is reference only.

Price reference — paid models (reference · skim)

Approx. list prices / 1M tokens — verify on provider docs before class.

Why run a model locally?

Why developers keep a local model around:

Ollama runs open models locally. Qwen3 is strong at tool calling, which agents need.

Local trade-offs — be realistic

Free and private, with trade-offs:

For learning and everyday coding tasks, a small local Qwen3 is enough. Use cloud APIs or coder models for harder jobs.

Free local models — what to demo

Use qwen3.5:4b live. Keep qwen3:4b ready as backup.

What hardware do you actually need?

Rule of thumb at Q4: RAM ≈ model size (B) × ~0.7 GB. GPU helps speed, not correctness.

Step 1 — Install Ollama

# download the app from ollama.com
# ...or with Homebrew:
brew install ollama

curl -fsSL https://ollama.com/install.sh | sh

# download & run the installer
# from ollama.com/download

ollama --version
# prints installed Ollama version

# Ollama runs a local server at:
#   http://localhost:11434
# (the desktop app starts it automatically;
#  otherwise run:  ollama serve )

Step 2 — Download & run Qwen3.5

# M4 / 16 GB demo pick
ollama pull qwen3.5:4b

# chat with it right in your terminal
ollama run qwen3.5:4b
>>> Write a Python function that reverses a string.

# keep a lighter backup ready:
ollama pull qwen3:4b

# strong coding model, but not for 16 GB demo:
ollama pull qwen3-coder:30b   # needs 32 GB+ / GPU

Step 3 — Ollama speaks "OpenAI"

Ollama exposes an OpenAI-compatible API. Change baseURL; keep the loop.

# quick test with plain curl:
curl http://localhost:11434/v1/chat/completions -d '{
  "model": "qwen3.5:4b",
  "messages": [{ "role": "user", "content": "Say hi in 3 words" }]
}'

Same request shape → same SDK → same agent loop.

Step 4 — Point your agent at Qwen3.5

Change two lines and the Part 2 agent runs locally:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:11434/v1",  // ← point at Ollama
  apiKey: "ollama",                      // ← required by SDK, but ignored
});

// ...the ENTIRE agent loop is unchanged — just switch the model:
const res = await openai.chat.completions.create({
  model: "qwen3.5:4b",                   // ← M4 / 16 GB demo pick
  messages,
  tools,                                 // Qwen3.5 supports tool calling
});

Same 80-line agent. Local, free per token, private.

What agents are great at

A fast junior dev — best on well-scoped, verifiable tasks.

Not a replacement for a senior engineer — a very fast junior dev.

A workflow that actually works

Short leash: small steps, verify every turn.

Handy prompt: Read first, don't edit yet. Make the smallest change. Run tests after.

Guardrails you'll see in industry

The riskier the action, the more of these you add.

More risk → more sandbox, approval, and review. Never let an agent touch prod unwatched.

Recap — the mental model

• 🧠LLM = next-token predictor at scale.
• 🤖Agent = LLM + tools + a loop + a goal.
• 🔁Loop: think → tool → act → observe → repeat → answer.
• 💻Node.js MVP: tools + loop + tool results.
• 🔀Cloud ↔ local: change baseURL and model.
• 🖥️Ollama + Qwen3.5 = the same agent, free, private, offline.

The "secret sauce" of great agents

Our loop works. Production agents add reliability layers:

Inspired by Stanford CS146S — The Modern Software Developer · themodernsoftware.dev

Roadmap — from mini-agent to "Claude Code"

Level up the same loop, one layer at a time:

Layers are additive; the core loop stays the same. Study: Claude Code, Aider, Cline.

Where to go next

You have the mental model. Try three things tonight:

📝 Homework — what to build

{
  "provider": "ollama",
  "baseURL":  "http://localhost:11434/v1",
  "model":    "qwen3:4b",
  "apiKey":   "ollama"
}

📝 Homework — submit & grading

References & resources

Model names & prices change — verify on official docs before class.