DEV Community: Zahid Hasan Tonmoy

AI Agent Autonomy Levels: A Small TypeScript Approval Gate

Zahid Hasan Tonmoy — Sat, 17 Oct 2026 15:55:00 +0000

An agent with a delete tool and a loose prompt can read “clean up my old entries” as permission. Nothing malfunctions. The message allows that reading and the tool allows the action. What's missing is a rule about when the tool may run.

This post continues my series on building agents. The previous one covered MCP.

What autonomy is

An agent's autonomy is how much it may do on its own before a human has to approve, review or step in. It is a policy your code enforces, not a trait of the model.

A scale from Level 0 to Level 4

No standard defines these levels. This is my own working scale.

Level	Meaning
0	No tools. A plain chatbot
1	Read-only tools
2	Writes, each approved by a human
3	Routine writes run alone inside limits, irreversible actions still ask
4	Full autonomy, rarely justified

A level belongs to a tool, not to the whole agent. The same agent can run reads at Level 4 and deletes at Level 2.

Sort tools by what a mistake costs

A read tool changes nothing. A write tool changes something you can undo. An irreversible tool can't be taken back: deleting data, sending a message, moving money. The class comes from the cost of a wrong call, not the tool's name.

flowchart TD
    A[Model requests a tool] --> B{Tool risk class}
    B -->|read| C[Run it]
    B -->|write| D{Autonomy level}
    B -->|irreversible| E{Autonomy level}
    D -->|1| F[Refuse]
    D -->|2| G[Ask a human]
    D -->|3 or 4| C
    E -->|1| F
    E -->|2 or 3| G
    E -->|4| C
    G -->|approved| C
    G -->|declined| I[Send an error result to the model]
    F --> I
    C --> H[Send the result to the model]

The policy in code

Run it with AUTONOMY=2 npx tsx agent/autonomy.ts and change the value to compare levels.

// agent/autonomy.ts
import Anthropic from '@anthropic-ai/sdk';
import { createInterface } from 'node:readline/promises';

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

type Risk = 'read' | 'write' | 'irreversible';
type Decision = 'allow' | 'ask' | 'deny';

const LEVEL = Number(process.env.AUTONOMY ?? 2);

const expenses = [{ id: 1, item: 'tea', amount: 40 }];
let nextId = 2;

const risks: Record<string, Risk> = {
  get_total: 'read',
  add_expense: 'write',
  delete_expense: 'irreversible',
};

function decide(level: number, risk: Risk): Decision {
  if (risk === 'read') return 'allow';
  if (level <= 1) return 'deny';
  if (level >= 4) return 'allow';
  if (risk === 'write' && level === 3) return 'allow';
  return 'ask';
}

const tools: Anthropic.Tool[] = [
  {
    name: 'get_total',
    description: 'Return the exact sum of every expense recorded so far. Use this whenever the user asks for a total.',
    input_schema: { type: 'object', properties: {} },
  },
  {
    name: 'add_expense',
    description: 'Record one expense. Use it whenever the user says they spent money.',
    input_schema: {
      type: 'object',
      properties: { item: { type: 'string' }, amount: { type: 'number' } },
      required: ['item', 'amount'],
    },
  },
  {
    name: 'delete_expense',
    description: 'Permanently delete one expense by its id. Use it only when the user names the expense to remove.',
    input_schema: {
      type: 'object',
      properties: { id: { type: 'number' } },
      required: ['id'],
    },
  },
];

function execute(name: string, input: Record<string, unknown>): unknown {
  if (name === 'get_total') return { total: expenses.reduce((sum, e) => sum + e.amount, 0) };
  if (name === 'add_expense') {
    const expense = { id: nextId++, item: String(input.item), amount: Number(input.amount) };
    expenses.push(expense);
    return expense;
  }
  if (name === 'delete_expense') {
    const index = expenses.findIndex((e) => e.id === Number(input.id));
    if (index === -1) return { error: 'no such expense' };
    expenses.splice(index, 1);
    return { ok: true };
  }
  return { error: 'unknown tool' };
}

async function approve(name: string, input: Record<string, unknown>): Promise<boolean> {
  const answer = await rl.question(`Allow ${name} ${JSON.stringify(input)}? (y/n) `);
  return answer.trim().toLowerCase() === 'y';
}

async function guarded(name: string, input: Record<string, unknown>): Promise<unknown> {
  const decision = decide(LEVEL, risks[name] ?? 'irreversible');
  console.log(`[${decision}] ${name}`);
  if (decision === 'deny') return { error: 'not permitted at this autonomy level' };
  if (decision === 'ask' && !(await approve(name, input))) return { error: 'the user declined this action' };
  return execute(name, input);
}

async function runAgent(userText: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: userText }];

  for (let step = 0; step < 6; step++) {
    const response = await client.messages.create({
      model: 'claude-sonnet-5',
      max_tokens: 500,
      tools,
      messages,
    });

    messages.push({ role: 'assistant', content: response.content });

    if (response.stop_reason !== 'tool_use') {
      return response.content.flatMap((b) => (b.type === 'text' ? [b.text] : [])).join('');
    }

    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const block of response.content) {
      if (block.type === 'tool_use') {
        const output = await guarded(block.name, block.input as Record<string, unknown>);
        results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(output) });
      }
    }
    messages.push({ role: 'user', content: results });
  }

  return 'Stopped: step limit reached';
}

runAgent('Add 300 for groceries, then delete expense 1.')
  .then(console.log)
  .finally(() => rl.close());

A tool missing from risks falls back to irreversible, so anything you forget to classify gets the strictest treatment. Denials and declined approvals go back as error results, not exceptions, so the model can explain what happened.

What I noticed rereading my own series code

The system prompt template in my prompt-engineering post says “Never delete or change a past expense unless the user explicitly asks to.” The agent in that post has no delete tool. The line guards an action the agent can't take. The tracker from the components post writes with no approval and only a six-step cap, which was a Level 3 decision I never named. That is why the gate here lives in code next to execute, with the prompt line as a second layer.

Common mistakes

Keeping the rule only in the prompt.
Classifying tools by name instead of by what a wrong call costs.
No default for unclassified tools. Fail closed.
Raising the level for the whole agent instead of one tool at a time.
Running approvals in parallel. Keep anything that waits on a person sequential.
Treating a decline as a crash instead of returning it as a tool result.

Read the full version

I write each post in English and Bangla. The full version is on my blog: How Autonomous Should an AI Agent Be?

Which of your agent's tools would you never let run without asking?

What Is MCP, Really? A Real Server, Tested Against the Actual Protocol

Zahid Hasan Tonmoy — Fri, 16 Oct 2026 14:54:00 +0000

MCP got one sentence in the first post of this series, as one reason agents got practical, with no real explanation. This post is that explanation, plus a server I actually ran the protocol against.

This post continues my series on building agents. The previous one covered AI agent vs Zapier/Make.

The problem MCP solves

Every tool in this series so far was wired directly into one project. Fine once — until a second project wants the same tool, and you're copying the function, schema, and description, keeping both in sync by hand. MCP's fix: expose a tool once, as a server, and any MCP-compatible client can use it without new integration code for that pairing.

flowchart TB
    subgraph "Without MCP: custom glue per pair"
        App1[App 1] -->|custom code| ToolA[Tool A]
        App1 -->|custom code| ToolB[Tool B]
        App2[App 2] -->|custom code| ToolA
        App2 -->|custom code| ToolB
    end
    subgraph "With MCP: one server, any client"
        AppX[App 1] -->|MCP| ServerA[Tool A as an MCP server]
        AppY[App 2] -->|MCP| ServerA
        AppX -->|MCP| ServerB[Tool B as an MCP server]
        AppY -->|MCP| ServerB
    end

Why now

Anthropic introduced MCP in November 2024. OpenAI and Google both adopted it within months. In December 2025, Anthropic donated the protocol to the Agentic AI Foundation, a vendor-neutral Linux Foundation project co-founded with Block and OpenAI. A single company's protocol became shared industry infrastructure.

A real server

// mcp/weather-server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const weatherData: Record<string, { condition: string; temp_c: number }> = {
  Dhaka: { condition: 'humid and cloudy', temp_c: 31 },
  Chittagong: { condition: 'light rain', temp_c: 29 },
};

const server = new McpServer({ name: 'weather-server', version: '1.0.0' });

server.registerTool(
  'get_weather',
  {
    title: 'Get Weather',
    description: 'Get the current weather condition and temperature in Celsius for a named city.',
    inputSchema: { city: z.string() },
  },
  async ({ city }) => {
    const data = weatherData[city];
    const result = data ? { city, ...data } : { error: `no weather data for ${city}` };
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  },
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main();

Same name, same description, same one field as the get_weather tool from the tool-calling post — inputSchema just takes Zod validators instead of hand-written JSON Schema, and the SDK converts it.

Testing it against the real protocol

// mcp/test-client.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

async function main() {
  const transport = new StdioClientTransport({ command: 'npx', args: ['tsx', 'mcp/weather-server.ts'] });
  const client = new Client({ name: 'test-client', version: '1.0.0' });
  await client.connect(transport);

  const tools = await client.listTools();
  console.log(tools);

  const result = await client.callTool({ name: 'get_weather', arguments: { city: 'Dhaka' } });
  console.log(result);

  await client.close();
}

main();

This spawns the server as a real subprocess and does the actual MCP handshake — not a mock.

The bug that took a rewrite

The first version ended with a bare top-level await server.connect(transport). Type-checked fine. The client connection closed immediately on run. The cause: this file's execution transforms it to a module format that doesn't support top-level await, crashing the process before the server could listen — nothing to do with MCP itself, but exactly where an MCP server's entrypoint sits. Wrapping it in an async main() fixed it completely.

Common mistakes

Top-level await at the entrypoint — wrap it in an async function.
Treating a vague MCP tool description as lower-stakes than an inline one — it's the same field, now shared across every project that connects.
Connecting to a third-party server without reviewing what it exposes — a tool description is server-controlled text the model reads as an instruction.
Building a server for a tool that already has one in a public registry.

Read the full version

I write each post in English and Bangla. The full version is on my blog: What Is MCP?

Have you built or connected to an MCP server yet?

AI Agent vs Zapier/Make in 2026: The Comparison That's Actually Still True

Zahid Hasan Tonmoy — Thu, 15 Oct 2026 05:47:43 +0000

"I already built this in Zapier, why would I need an agent?" A year ago the answer was easy. Not anymore — Zapier shipped AI Orchestration in July 2026, Make shipped AI Agents in its canvas earlier the same year. "Does a model decide something" stopped being the dividing line.

This post continues my series on building agents. The previous one covered writing a good agent prompt.

What's actually still different

A trigger-action platform's workflow shape — which apps, roughly what order — is drawn by a human ahead of time in the builder, even when one step now delegates to a model. An agent you build yourself, the way this series has, decides that whole shape at runtime: which tools apply, in what order, for this specific message.

flowchart TD
    subgraph Fixed automation
        F0[Any trigger] --> F1[Step A, always] --> F2[Step B, always]
    end
    subgraph Agent
        A0[Any message] --> AD{Model reads it}
        AD -->|only A applies| A1[Step A]
        AD -->|only B applies| A2[Step B]
        AD -->|both apply| A3[Step A and Step B]
        AD -->|neither applies| A4[No tool, just reply]
    end

Proving it in code

// agent/fixed-vs-agent.ts
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const expenses: { item: string; amount: number }[] = [];
const log: string[] = [];

function addExpense(item: string, amount: number) {
  expenses.push({ item, amount });
  return { ok: true, recorded: expenses.length };
}

function getTotal() {
  return { total: expenses.reduce((sum, e) => sum + e.amount, 0) };
}

function notify(message: string) {
  log.push(message);
  return { sent: true };
}

function runFixedAutomation(item: string, amount: number) {
  const step1 = addExpense(item, amount);
  const step2 = notify(`Recorded: ${item} (${amount})`);
  return { step1, step2 };
}

const tools: Anthropic.Tool[] = [
  {
    name: 'add_expense',
    description: 'Record one expense. Use it whenever the user says they spent money.',
    input_schema: {
      type: 'object',
      properties: { item: { type: 'string' }, amount: { type: 'number' } },
      required: ['item', 'amount'],
    },
  },
  {
    name: 'get_total',
    description:
      "Return the exact sum of every expense recorded so far. Use this whenever the user asks for a total, a sum, or how much they've spent overall.",
    input_schema: { type: 'object', properties: {} },
  },
  {
    name: 'notify',
    description: 'Send the user a short notification. Use this only when the user explicitly asks to be notified or reminded.',
    input_schema: {
      type: 'object',
      properties: { message: { type: 'string' } },
      required: ['message'],
    },
  },
];

function execute(name: string, input: Record<string, unknown>): unknown {
  if (name === 'add_expense') return addExpense(String(input.item), Number(input.amount));
  if (name === 'get_total') return getTotal();
  if (name === 'notify') return notify(String(input.message));
  return { error: 'unknown tool' };
}

async function runAgent(userText: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: userText }];

  for (let step = 0; step < 4; step++) {
    const response = await client.messages.create({
      model: 'claude-sonnet-5',
      max_tokens: 300,
      tools,
      messages,
    });

    messages.push({ role: 'assistant', content: response.content });

    if (response.stop_reason !== 'tool_use') {
      const block = response.content.find((b): b is Anthropic.TextBlock => b.type === 'text');
      return block?.text ?? '';
    }

    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const block of response.content) {
      if (block.type === 'tool_use') {
        results.push({
          type: 'tool_result',
          tool_use_id: block.id,
          content: JSON.stringify(execute(block.name, block.input as Record<string, unknown>)),
        });
      }
    }
    messages.push({ role: 'user', content: results });
  }

  return 'Stopped: step limit reached';
}

runAgent('I spent 500 on lunch.').then(console.log);

runFixedAutomation always runs both steps, regardless of content. runAgent, same three tools, picks a different path for "I spent 500 on lunch" (just add_expense), "what's my total" (just get_total), and "I spent 200 on tea, notify me" (both) — decided by the model each time, not written into the function.

The near-miss writing this

The first draft argued no-code tools can't reason, full stop. Checking current reality before publishing caught that it was already wrong — both platforms shipped real agent features this year. The fix was rebuilding the comparison around what's still true, not whether a model is involved at all.

Common mistakes

Assuming "no-code" still means "no reasoning."
Treating a platform's AI Agent feature as equivalent to building your own.
Writing custom code for a job the platform's library already covers.
Forcing a complex, stateful job into a platform's bounded actions.

Read the full version

I write each post in English and Bangla. The full version is on my blog: AI Agent vs Zapier/Make

Where's your line between "use the platform" and "build it yourself"?

The Five Things a Good AI Agent System Prompt Needs (With a Checker)

Zahid Hasan Tonmoy — Wed, 14 Oct 2026 06:42:28 +0000

A perfect memory system can't save an agent that doesn't know when to reach for the tool sitting right in front of it. Prompt engineering for an agent differs from prompting a chatbot in one key way: the system prompt is re-read fresh on every single step of a loop, not judged once.

This post continues my series on building agents. The previous one covered short-term vs long-term memory.

Why vagueness compounds in an agent prompt

A vague instruction in a one-shot prompt costs one bad answer. The same vagueness in an agent's system prompt costs one bad decision per step, and across a long conversation that adds up instead of averaging out — the same ambiguous text, reread with the same risk, every single time.

The five sections

Role — one or two sentences, not a biography.
Tools, and exactly when to use each — "use this whenever X," not just a capability list.
Boundaries — what it must never do: invent data, act irreversibly without confirmation, go outside its given tools.
Handling uncertainty — ask, guess, or escalate, picked explicitly.
What "done" looks like — an explicit stopping condition.

Tool descriptions are prompts too

Going back through this series' actual code: add_expense has "Use it whenever the user says they spent money" — real trigger phrase, doing real work. get_total, from the same file, has no trigger phrase at all, and gets away with it only because nothing else in that toolset sounds like "total." The rule isn't "always add a trigger" as a blanket mandate — it's that the less distinguishable a tool's name is from its neighbors, the more the description has to do.

A structured prompt, and a way to check it

// agent/prompt-template.ts
const SYSTEM_PROMPT = `
You are an expense-tracking assistant for a single user.

## Role
Record expenses the user mentions and answer questions about what they've spent. You do not give financial advice.

## Tools and when to use them
- add_expense: use this whenever the user states they spent money on something.
- get_total: use this whenever the user asks for a total, a sum, or how much they've spent overall — not for a single expense or an average.
- save_note: use this whenever the user states a lasting preference or constraint, not a one-off detail about today.

## Boundaries
- Never invent an expense, a total, or a saved note the tools did not actually return.
- Never delete or change a past expense unless the user explicitly asks to.

## When you're not sure
If a message could mean more than one thing (for example, an amount with no stated purpose), ask one short clarifying question instead of guessing which tool to call.

## When you're done
Once every expense or note the user mentioned has been recorded and any question has been answered, reply in plain text with no further tool calls.
`.trim();

function hasTriggerPhrase(description: string): boolean {
  return /\buse (this|it) whenever\b/i.test(description);
}

const toolDescriptions: Record<string, string> = {
  add_expense: 'Record one expense. Use it whenever the user says they spent money.',
  get_total_before: 'Return the exact total of all recorded expenses in BDT.',
  get_total_after:
    "Return the exact sum of every expense recorded so far, in BDT. Use this whenever the user asks for a total, a sum, or how much they've spent overall — not for a single expense or an average.",
};

for (const [name, description] of Object.entries(toolDescriptions)) {
  console.log(name, '->', hasTriggerPhrase(description) ? 'has trigger phrase' : 'MISSING trigger phrase');
}

console.log('\n--- system prompt preview ---');
console.log(SYSTEM_PROMPT);

Running the checker against the real get_total description and its rewrite shows the gap directly: the original fails, the rewrite passes, with no need to guess how a real model would respond to either one.

Common mistakes

Treating the system prompt as one block of advice instead of distinct sections.
Writing tool descriptions in isolation instead of reviewing them together.
No explicit stopping condition.
Padding the prompt with generic advice that doesn't change behavior.

Read the full version

I write each post in English and Bangla. The full version is on my blog: How to Write a Good Prompt for an AI Agent

Has a vague tool description ever made your agent guess wrong?

What Is RAG? A Working Retrieval Example You Can Run With Just an Anthropic Key

Zahid Hasan Tonmoy — Tue, 13 Oct 2026 08:55:18 +0000

An agent can have every tool it needs and still answer wrong — because it doesn't know something. Not incapable of knowing it; the fact just wasn't in its training data, or it changed afterward, or it lives in a document only your team has.

This post continues my series on building agents. The previous one covered tool calling.

What RAG actually is

Retrieval Augmented Generation pulls relevant text from a knowledge source at the moment a question is asked and inserts it into the model's prompt before it answers, instead of relying only on what the model learned during training. Update the documents and the next answer reflects the change immediately — no retraining involved.

Three jobs, not one

Embedding — turn text into a vector, positioned so similar meanings land near each other.
Retrieval — compare the question's vector against every stored document vector (commonly with cosine similarity) and keep only the closest matches.
Augmentation — insert those matches into the prompt as context before the model answers.

flowchart LR
    Q[User question] --> E[Turn the question into a vector]
    E --> S[Compare against every stored document vector]
    S --> K[Keep only the closest matches above a threshold]
    K --> P[Add those chunks to the prompt as context]
    P --> M[Model generates the answer]

A working example

Anthropic doesn't ship its own embedding model — its docs point to Voyage AI instead. So this demo swaps a real embedding model for a hand-written one (word counts as vectors, cosine similarity for matching) to keep the whole thing runnable with just ANTHROPIC_API_KEY.

// agent/simple-rag.ts
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const knowledgeBase: string[] = [
  'This blog is a Next.js app deployed on Vercel. Pushing to the main branch triggers a new production deployment automatically.',
  'Blog posts are stored as JSON files under content/posts and read at build time, so adding a new post requires a redeploy before it appears live.',
  'The blog index page uses Incremental Static Regeneration with a 60 second revalidate window.',
  'Environment variables such as API keys are set in the Vercel dashboard under Project Settings, Environment Variables, never committed to git.',
  'Every pull request gets its own preview deployment with a unique URL, separate from the production domain.',
];

function tokenize(text: string): string[] {
  return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
}

function vectorize(text: string, vocabulary: string[]): number[] {
  const counts = new Map<string, number>();
  for (const token of tokenize(text)) counts.set(token, (counts.get(token) ?? 0) + 1);
  return vocabulary.map((word) => counts.get(word) ?? 0);
}

function cosineSimilarity(a: number[], b: number[]): number {
  let dot = 0;
  let normA = 0;
  let normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  if (normA === 0 || normB === 0) return 0;
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

function retrieve(query: string, topK = 2, minScore = 0.22): string[] {
  const vocabulary = Array.from(new Set([query, ...knowledgeBase].flatMap(tokenize)));
  const queryVector = vectorize(query, vocabulary);
  return knowledgeBase
    .map((doc) => ({ doc, score: cosineSimilarity(queryVector, vectorize(doc, vocabulary)) }))
    .sort((a, b) => b.score - a.score)
    .filter((s) => s.score >= minScore)
    .slice(0, topK)
    .map((s) => s.doc);
}

async function askWithContext(question: string): Promise<string> {
  const context = retrieve(question);

  if (context.length === 0) {
    return "I don't have anything in the knowledge base about that.";
  }

  const response = await client.messages.create({
    model: 'claude-sonnet-5',
    max_tokens: 512,
    system:
      'Answer only using the context below. If the context does not contain the answer, say you do not know.\n\nContext:\n' +
      context.map((c, i) => `${i + 1}. ${c}`).join('\n'),
    messages: [{ role: 'user', content: question }],
  });

  const text = response.content.find((b): b is Anthropic.TextBlock => b.type === 'text');
  return text?.text ?? '';
}

askWithContext('How do new blog posts actually go live on the site?').then(console.log);

The mistake that took tuning to find

My first retrieve had no minScore — it just returned the top two matches, whatever their score. An unrelated cooking question still returned two chunks, because a few common words overlapped with the documents and cosine similarity can't tell those words carry no meaning. The model then answered confidently using the wrong context. I fixed it by printing the actual scores for questions I cared about and finding where "genuinely related" stopped and "just sharing a few words" began — 0.22, for this data.

Common mistakes

No score floor on top-k. Threshold on the score, not just the rank.
Chunking too large or too small. Start at paragraph or section level.
Never checking what got retrieved. Log it alongside the answer during development.
Skipping a real embedding model in production. Word-overlap vectors miss synonyms entirely.

Read the full version

I write each post in English and Bangla. The full version is on my blog: What Is RAG?

Where does your RAG pipeline draw the line between relevant and irrelevant?

The Four Components of an AI Agent, in One Small TypeScript File

Zahid Hasan Tonmoy — Mon, 05 Oct 2026 04:25:20 +0000

Most explanations of AI agents stop at “a model with tools”. That is true, but it doesn't help when your agent forgets a preference, calls the wrong function or loops forever. To debug any of those, you need to know which part is misbehaving.

This post continues my series on building agents. The previous one covered LLMs versus agents.

The four components of an AI agent

An AI agent has four components: a brain (the language model that decides what to do next), memory (the conversation history and stored facts the model can read), tools (functions that let it act outside the model) and an action loop (the code that calls the model, runs the tools it asks for and feeds the results back). The brain is the only part that is a model. The other three are code and data that you write and control.

Part	What it does	Without it
Brain	Reads everything and decides the next step	Nothing decides, so you have a fixed script
Memory	Holds the conversation and stored facts	The agent forgets between steps or sessions
Tools	Let it read or change things outside the model	It can only talk
Action loop	Runs the model, executes tools, returns results	One answer, then it stops

Each part in a few lines

Brain. The language model. Each turn it gets the system prompt, the conversation, the tool list and any tool results, and it returns either text or a request to call a tool. It never runs anything itself.

Memory. Two layers. Short-term memory is the message history you send with every call. Long-term memory is anything written to storage and read back in a later run: a notes file, a database row, a vector store. The model remembers nothing between calls, so both layers are your code's job.

Tools. An ordinary function plus a description: a name, when to use it, and a JSON Schema for the inputs. The model never sees your code, only the description, so write it like API docs for a reader who can't ask questions.

Action loop. Send memory to the brain. Plain text means done. A tool request means run the tool, append the result to memory and go around again. Give the loop exits: a final answer, a step cap, unrecoverable failures, human approval.

All four in one file

This is an expense tracker with a notes file. Install the SDK with npm install @anthropic-ai/sdk, set ANTHROPIC_API_KEY and run npx tsx agent/four-parts.ts.

// agent/four-parts.ts
import Anthropic from '@anthropic-ai/sdk';
import { existsSync, readFileSync, writeFileSync } from 'node:fs';

const client = new Anthropic();
const NOTES_FILE = 'notes.json';

const messages: Anthropic.MessageParam[] = [];
const expenses: { item: string; amount: number }[] = [];

function loadNotes(): string[] {
  return existsSync(NOTES_FILE) ? JSON.parse(readFileSync(NOTES_FILE, 'utf8')) : [];
}

const tools: Anthropic.Tool[] = [
  {
    name: 'add_expense',
    description: 'Record one expense. Use it whenever the user says they spent money.',
    input_schema: {
      type: 'object',
      properties: {
        item: { type: 'string' },
        amount: { type: 'number', description: 'Amount in BDT' },
      },
      required: ['item', 'amount'],
    },
  },
  {
    name: 'get_total',
    description: 'Return the exact total of all recorded expenses in BDT.',
    input_schema: { type: 'object', properties: {} },
  },
  {
    name: 'save_note',
    description: 'Save a lasting fact about the user, such as a preference, for future sessions.',
    input_schema: {
      type: 'object',
      properties: { note: { type: 'string' } },
      required: ['note'],
    },
  },
];

const handlers: Record<string, (input: Record<string, unknown>) => unknown> = {
  add_expense: (input) => {
    expenses.push({ item: String(input.item), amount: Number(input.amount) });
    return { ok: true, recorded: expenses.length };
  },
  get_total: () => ({ total: expenses.reduce((sum, e) => sum + e.amount, 0) }),
  save_note: (input) => {
    writeFileSync(NOTES_FILE, JSON.stringify([...loadNotes(), String(input.note)]));
    return { ok: true };
  },
};

function execute(name: string, input: Record<string, unknown>): unknown {
  try {
    const handler = handlers[name];
    return handler ? handler(input) : { error: 'unknown tool' };
  } catch (err) {
    return { error: String(err) };
  }
}

async function runAgent(userText: string): Promise<string> {
  messages.push({ role: 'user', content: userText });

  for (let step = 0; step < 6; step++) {
    const response = await client.messages.create({
      model: 'claude-sonnet-5',
      max_tokens: 1024,
      system: `You track expenses. Known about the user: ${loadNotes().join('; ') || 'nothing yet'}`,
      tools,
      messages,
    });

    messages.push({ role: 'assistant', content: response.content });

    if (response.stop_reason !== 'tool_use') {
      return response.content.flatMap((b) => (b.type === 'text' ? [b.text] : [])).join('');
    }

    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const block of response.content) {
      if (block.type === 'tool_use') {
        const output = execute(block.name, block.input as Record<string, unknown>);
        results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(output) });
      }
    }
    messages.push({ role: 'user', content: results });
  }

  return 'Stopped: step limit reached';
}

async function main() {
  console.log(await runAgent('I spent 250 on lunch and 80 on a rickshaw. I prefer short answers.'));
  console.log(await runAgent('What is my total so far?'));
}

main();

The brain is client.messages.create. Memory is messages plus notes.json. The tools are tools, handlers and execute. The action loop is the for block in runAgent.

The mistake that cost me an afternoon

The first version of this tracker forgot everything between messages. I had written const messages = [] inside the function that handled each user message, so every call started with a blank history. I blamed the system prompt and kept rewriting it until I noticed the array was being recreated on every call. Moving one line out of the function fixed it.

Common mistakes

Vague tool descriptions. The brain picks tools by reading them, so say what the tool does, what it needs and when to use it.
Sending the whole history forever. Cost and latency climb. Trim or summarize old turns and keep lasting facts in a separate store.
Swallowing tool errors. Return the error text as the result, as execute does, so the model can try again.
Making the brain do work that code can do. Summing amounts inside the prompt invites slips. That is why get_total is a tool.

Read the full version

I write each post in English and Bangla. The full version, with a diagram, is on my blog: What's Inside an AI Agent?

Which of the four parts is hardest for you to debug?

What an AI Agent Actually Is, With a Working TypeScript Loop

Zahid Hasan Tonmoy — Tue, 29 Sep 2026 09:25:53 +0000

When people say “AI agent”, they usually mean one specific thing: a language model that can act, look at what happened, and decide what to do next. Everything else is packaging.

This post is the short version, plus a loop you can run in a few minutes.

The definition I actually use

An AI agent is a software system that uses a language model to work toward a goal on its own. It decides the next step, uses tools such as APIs, databases or a code runner, checks the result, and repeats until the job is done or it needs a human.

A chatbot answers once. An agent keeps going.

The loop

The user gives a goal.
The model reads the goal and the history so far, then picks the next step.
If it needs a tool, your code runs it.
The result goes back to the model as new information.
Back to step 2, until the model returns a final answer.

A runnable version

The example below uses the Anthropic SDK and a fake in-memory order lookup, so an API key is all you need.

// agent/loop.ts
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const orders: Record<string, { status: string; eta: string }> = {
  'BD-1042': { status: 'out for delivery', eta: 'today' },
  'BD-1043': { status: 'processing', eta: '5 days' },
};

const tools: Anthropic.Tool[] = [
  {
    name: 'get_order_status',
    description: 'Look up the status and delivery estimate of an order by its ID',
    input_schema: {
      type: 'object',
      properties: { order_id: { type: 'string' } },
      required: ['order_id'],
    },
  },
];

function runTool(name: string, input: { order_id: string }) {
  if (name === 'get_order_status') {
    return orders[input.order_id] ?? { error: 'order not found' };
  }
  return { error: 'unknown tool' };
}

async function runAgent(goal: string) {
  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: goal }];

  for (let step = 0; step < 5; step++) {
    const response = await client.messages.create({
      model: 'claude-sonnet-5',
      max_tokens: 1024,
      tools,
      messages,
    });

    messages.push({ role: 'assistant', content: response.content });

    if (response.stop_reason !== 'tool_use') {
      const block = response.content.find((b): b is Anthropic.TextBlock => b.type === 'text');
      return block?.text ?? '';
    }

    const results: Anthropic.ToolResultBlockParam[] = response.content
      .filter((b): b is Anthropic.ToolUseBlock => b.type === 'tool_use')
      .map((b) => ({
        type: 'tool_result',
        tool_use_id: b.id,
        content: JSON.stringify(runTool(b.name, b.input as { order_id: string })),
      }));

    messages.push({ role: 'user', content: results });
  }

  return 'Stopped: step limit reached';
}

runAgent('Where is my order BD-1042?').then(console.log);

Install the SDK with npm install @anthropic-ai/sdk, set ANTHROPIC_API_KEY and run npx tsx agent/loop.ts. Three parts carry the idea: the tools array (what the model may do), the loop (how real results flow back), and the step cap (so a confused model cannot circle forever).

Why people are suddenly talking about agents

The idea is decades old. What changed is that the pieces became dependable:

Tool calls got reliable. Models now produce structured calls that code can execute, and they read error messages to try again.
Loops became affordable. A job can take ten model calls, and lower prices plus faster models made that practical.
Shared plumbing. Function calling is everywhere, and open protocols like MCP (introduced by Anthropic in late 2024) let one agent talk to many tools.
Visible results. Coding agents that edit files, run tests and fix their own failures showed developers finished work instead of suggestions.

Agents still fail: the wrong tool, repeated steps, a confident answer to the wrong task. That is why limits, logging and human approval are part of the job.

The mistake I made first

My first support-style assistant kept inventing delivery dates when I tested it. I blamed the system prompt and kept rewriting it. The real problem was that the model had no way to look anything up. One lookup tool fixed what no amount of prompt rewriting had.

Three things I watch for now:

Calling every fixed script an agent. A fixed sequence of model and function calls is a workflow. It is often the better design, but it debugs differently.
No step limit. A stuck model can loop and spend your API budget while you sleep.
Write access too early. Start read-only and add human approval before anything irreversible.

What's next

This is the first post in a series where I build agents step by step, from how they are put together to running one in production. I write each post in English and Bangla, and the original lives on my blog: What Is an AI Agent, Really?

What was the first thing you tried to make an agent do?

Building a Laravel Marketplace with PostgreSQL While Debugging React State

Zahid Hasan Tonmoy — Mon, 21 Sep 2026 05:21:29 +0000

I spent the last few days building instead of just watching — a small Laravel marketplace project backed by PostgreSQL, plus some hands-on React work. I also got stuck a couple of times, and writing down where I got stuck turned out to be the most useful part of the process.

On the Laravel side, I went back to fundamentals first: routes, controllers, views, and Blade. I practiced the full request cycle — a route hitting a controller, the controller passing data to a view, and Blade handling variables, loops, and conditionals. I also worked through basic form validation, mostly to get the muscle memory right before moving on to anything more complex.

The more interesting part was designing the database for a marketplace-style project with PostgreSQL. The plan is four roles — Admin, Moderator, Seller, and Buyer — with two business rules that shaped most of the schema decisions: a seller can't buy their own product (though buying from other sellers is fine), and a seller's product doesn't go live the moment it's created. It has to be approved by an Admin or Moderator first.

Translating those two rules into actual migrations is where the real learning happened. I added a role field to the users table, defaulting to buyer. Then I built a products table with seller_id, title, description, price, stock, status, approved_by, and approved_at. New products start with a pending status so the approval workflow has something to act on.

Working through this made migration concepts click in a way tutorials hadn't — up() and down(), foreign keys, nullable columns, defaults, and relationships. The seller relationship uses cascading deletes (delete a seller, their products go too), but the approver relationship just sets approved_by to null if that admin or moderator is removed — the product itself stays. Seeing why those two behaviors need to be different made foreign key constraints feel a lot less abstract.

I also hit a real environment issue: running Laravel's db:table command failed because of a missing PHP intl extension. It took a minute to realize the error wasn't in my code at all — it was a missing PHP extension. Small as it was, debugging it felt like as much a part of "learning Laravel" as writing the migrations themselves.

On the React side, I worked with useState and useEffect, fetching show data from the TVMaze API. The main lesson here was that fetch only rejects on a network failure — not on an HTTP error like a 404 or 500. So I started checking response.ok explicitly and throwing an error when it fails, then wrapped the whole request in try/catch/finally to keep loading, data, and error states cleanly separated:

useEffect(() => {
  const fetchShows = async () => {
    setLoading(true);
    try {
      const res = await fetch("https://api.tvmaze.com/search/shows?q=all");
      if (!res.ok) throw new Error("Failed to fetch shows");
      const data = await res.json();
      setShows(data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };
  fetchShows();
}, []);

I also ran into a small but genuinely confusing bug: logging state right after calling setShows still showed the old value. It wasn't that the update failed — it was that the log was reading a stale value from that render's closure, before React had re-rendered with the new state. Chasing that down taught me more about how React's state updates and re-renders actually work than any explanation had.

The biggest takeaway from this stretch is that learning a framework isn't about memorizing syntax — it's routes, controllers, migrations, relationships, API calls, and state management all working together inside one real application. Next up: building out the approval flow and seller dashboard on top of this schema, and getting more reps in with React's data-fetching patterns.

This article was originally published on Zahid Hasan Tonmoy's Portfolio.
Connect with Zahid on GitHub & LinkedIn.

Laravel Blade: Passing Data from Controller to View and Rendering It Dynamically

Zahid Hasan Tonmoy — Wed, 16 Sep 2026 12:04:53 +0000

Laravel applications often need to pass data from a Controller to a View and then turn that data into HTML. I recently practiced this flow using Blade templating.

The Practice

I worked with a simple student data structure containing values such as name, department, university, CGPA, and skills.

The goal was to understand how this data can move from the Controller into a Blade View and then be rendered dynamically.

Dynamic Values in Blade

Blade uses double curly braces to display values safely in a template. For example:

The same pattern can be used for other fields:

This is more flexible than writing the actual values directly into the HTML.

Rendering an Array with @foreach

The student data also contained multiple skills. Instead of creating a separate HTML element manually for every skill, I used @foreach:

@foreach($student['skills'] as $skill)

Skill: {{ $skill }}

@endforeach

The loop goes through the array and creates the required output for each item.

Conditional Content with @if

Blade also provides directives for conditional rendering. I practiced @if to display content when a condition is satisfied.

This becomes useful when a View needs to present different information depending on the data it receives.

Why This Practice Matters

This exercise helped connect a few Laravel concepts together instead of learning Blade syntax in isolation.

The basic flow is:

Controller → data → View → Blade rendering

Understanding this flow makes it easier to move toward database-backed Laravel applications, where Controllers receive or prepare real application data and Blade presents it to users.

Final Takeaway

The practice was simple, but it clarified how Blade works with dynamic data. {{ }} handles values, @foreach handles repeated data, and @if handles basic conditional rendering.

These are small building blocks, but they are useful when creating Laravel Views that depend on real application data.

From MERN to Laravel: Why I'm Learning PHP and PostgreSQL as a MERN Developer published: false tags: laravel, php, postgresql, webdev

Zahid Hasan Tonmoy — Mon, 14 Sep 2026 06:33:14 +0000

If you'd told me a couple of years ago that I'd spend my evenings writing PHP, I would've laughed it off. I built my whole identity as a developer around MERN — MongoDB, Express, React, Node. It was fast, it was JavaScript top to bottom, and it felt like the "modern" stack compared to what a lot of local agencies were still running.

So it's a little funny to be sitting here now, a few months into learning Laravel and PostgreSQL, actually enjoying it. This isn't a "PHP was secretly amazing the whole time" post. It's more of an honest breakdown of why I started, what's been genuinely harder than I expected, and what's actually made me a better developer in the process.

Why bother, if MERN already works

Two things pushed me here.

First, the job and freelance market. I'm based in Dhaka, and if you look at what local agencies, small businesses, and even a lot of remote clients are actually running, PHP is everywhere. Laravel specifically shows up constantly in job posts and freelance briefs here — way more than I expected when I was deep in my MERN bubble. Sticking to one stack was quietly shrinking the pool of work I could take on.

Second, and this one surprised me more — I wanted to actually understand a relational database properly. I'd built a handful of projects on MongoDB, and I realized I'd never really had to think hard about schema design, foreign keys, or joins. MongoDB lets you get away with a lot of "figure it out later" thinking. I wanted to know what I was missing.

The parts that messed with my head

Coming from Mongoose, Eloquent felt oddly strict at first. In Mongoose, your schema is basically a suggestion:

// Mongoose — schema is more of a guideline
const productSchema = new mongoose.Schema({
  name: String,
  price: Number,
  tags: [String], // add whatever, whenever
});

In Laravel, the database is the source of truth, and migrations force you to commit to a structure before you write a line of app logic:

// Laravel migration — schema is law
Schema::create('products', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->decimal('price', 8, 2);
    $table->foreignId('category_id')->constrained();
    $table->timestamps();
});

That foreignId()->constrained() line is such a small thing, but it represents a mindset shift I didn't expect. In MongoDB, "relationships" are usually just an ID you remember to populate correctly in your app code. In PostgreSQL, the database itself refuses to let you insert a product with a category that doesn't exist. The first time a constraint error caught a bug I would've silently shipped in MERN, I actually said "huh" out loud at my desk.

Artisan took some getting used to too. php artisan make:model Product -m scaffolds a model and migration in one command, and there's a generator for basically everything — controllers, requests, seeders, jobs. Coming from hand-rolling most of my Express boilerplate, it felt like cheating at first. Now I just think of it as Laravel handling the parts of backend dev that were never interesting anyway.

Blade was the smallest adjustment, honestly, mostly because I'd already done enough server-rendered work to not be precious about JSX. It's just PHP mixed into HTML with some sugar on top — @if, @foreach, component includes. Nothing revolutionary, but nothing to fight either.

What I'm not giving up

I want to be clear this isn't a "MERN was a phase" post. I'm still building with React and Node, and most of what I've shipped so far leans on that stack — a machine-learning-backed gold price predictor, a peer-to-peer file sharing tool built on WebRTC, an IoT drainage monitoring setup running on an ESP32 feeding into Firebase. None of that goes away.

What's changed is that I stopped treating "the stack" as a personality trait. Laravel and PostgreSQL are just more tools now, and honestly, having both a document-store mental model and a relational one makes me design better MERN apps too. I catch myself asking "should this actually be normalized?" in Mongoose schemas now, which never used to occur to me.

If you're a MERN dev thinking about doing the same

A few things that would've saved me time:

Don't fight Eloquent relationships — learn hasMany, belongsTo, and belongsToMany properly before building anything. Half of Laravel's "magic" is just these three.
Migrations are version control for your schema. Treat them like git commits — small, descriptive, one change at a time.
php artisan tinker is basically a Node REPL for your Laravel app. Use it constantly to test queries before wiring them into controllers.
PostgreSQL's EXPLAIN ANALYZE is worth learning early. Coming from Mongo, I never had to think about query performance this explicitly.

Where this is heading

I'm still early — a few real projects deep, not an expert by any stretch. But I'm at the point where I'd genuinely take on Laravel or PostgreSQL work alongside MERN projects, and I'm actively looking for freelance and full-time opportunities where I can keep building across both.

If you're working on something and think there's a fit, or you just want to see what I've built so far, my projects and contact info are here:

🔗 Portfolio: https://zahidhasantonmoy.vercel.app
🔗 GitHub: https://github.com/zahidhasantonmoy

From Web Apps to Blinking LEDs: Why Every Software Developer Should Try Hardware 🛠️

Zahid Hasan Tonmoy — Mon, 24 Aug 2026 08:55:30 +0000

Hey everyone! 👋 Zahid here.

Let us be honest—staring at code all day can become a little tiring. Most of my time is spent in the software world: writing Python tweaking a Flutter UI deploying databases on Supabase or making sure my cloud hosting on Render runs smoothly. It is fun. It is all... Virtual.

Recently I decided to step from purely software projects and started tinkering with hardware. I grabbed an ESP32, some sensors and just began playing around.. Honestly? It completely changed my view on programming.

Here’s why I think every software developer should try messing around with hardware at once:

The "Physical" Reward 💡

When you build a web app a successful compilation means a tick on your terminal or a webpage loading correctly.. When you write a few lines of code and a physical LED lights up or a robotic arm moves on your desk? That dopamine hit is just built different! It makes your code feel alive.

It Makes You Appreciate the Cloud More ☁️

Working with microcontrollers that have limited memory makes you realize how spoiled we are with cloud infrastructure. Suddenly every byte of data matters. It teaches you to write more efficient code—which ultimately makes you a better software developer.

The Ultimate Playground for AI 🤖

This is the part I'm most excited about. I have been exploring No‑Code AI agents and machine learning lately. Imagine combining an AI model with a sensor—like a smart camera that actually reacts to its environment in real time. Hardware is the bridge that brings AI out of the browser and into the world.

The Takeaway

You do not need to be an engineer to start. If you know a bit of Python you are already 90%. Grab a microcontroller a few jumper wires and build something useless but fun.

Have any of you made the jump, from software to hardware?. Have you built any cool IoT projects lately? Let us chat in the comments! 👇

Let us Connect! 🚀 If you want to talk about tech, AI or see what I am building feel free to reach out. I would love to connect!

🌐 Portfolio: zahidhasantonmoy.vercel.app

💼 LinkedIn: linkedin.com/in/zahidhasantonmoy

🐦 X (Twitter): @zahidhasan_bd

📘 Facebook: zahidhasantonmoybd