DEV Community: Zahid Hasan Tonmoy

Turning Your Python AI Agent Into an Asynchronous FastAPI Backend with Server-Sent Events (SSE)

Zahid Hasan Tonmoy — Sun, 15 Nov 2026 04:03:00 +0000

After building our standalone Python agent in Post #27, Post #28 wraps our reasoning loop inside an asynchronous FastAPI microservice with Server-Sent Events (SSE) streaming.

Why FastAPI for AI Agents?

FastAPI leverages native ASGI async/await to prevent thread blocking during slow I/O waits (such as GitHub REST API calls or vector database queries). Because FastAPI is built natively around Pydantic, your agent tool input schemas double as FastAPI request validation bodies.

Streaming SSE via `StreamingResponse`

Using Python generator functions (async def agent_event_stream()), you can yield custom W3C-compliant SSE frames (event: tool-start, event: text-delta, event: done) directly through FastAPI's StreamingResponse with media_type='text/event-stream' and anti-buffering headers.

Read the full tutorial with complete Python source code on my blog: https://zahidhasantonmoy.vercel.app/blog/fastapi-ai-agent-backend-streaming-python

Beyond Next.js: How to Build a Clean, Production-Grade AI Agent in Python from Scratch

Zahid Hasan Tonmoy — Fri, 13 Nov 2026 21:20:00 +0000

After completing our 14-part Next.js implementation module, Post #27 kicks off Section C by translating our production agent guardrails into Python using Pydantic v2 and httpx.

Translating Zod to Pydantic v2

Instead of hand-writing brittle JSON Schema dictionaries in Python, define your tool inputs using Pydantic v2 BaseModel classes and generate the LLM schema automatically via .model_json_schema(). When the model emits a tool_use block, validate the arguments with .model_validate() and wrap any ValidationError inside a structured ToolResultEnvelope so the LLM can self-correct on the next iteration.

The Bounded Native Loop

Writing a 60-line bounded loop (max_steps = 5) with the official SDK gives you full visibility over stop_reason == 'tool_use', parallel tool_use_id matching, and token telemetry before we wrap this engine inside a FastAPI server in Post #28.

Read the full tutorial with complete Python source code on my blog: https://zahidhasantonmoy.vercel.app/blog/build-simple-ai-agent-python-guide

Client vs. Server Components in Next.js: Where Each Belongs in an AI Agent Architecture

Zahid Hasan Tonmoy — Fri, 13 Nov 2026 02:19:00 +0000

In a Next.js App Router AI agent, one misplaced 'use client' directive silently converts every child into client JavaScript, breaks server-only imports, and turns fast server-side Supabase hydration into a slow useEffect waterfall. This post maps the exact architectural boundary for a streaming agent workspace: parallel Promise.all queries in an async page.tsx, a zero-JavaScript SessionSidebar Server Component, serializable DTO contracts, and the ReactNode slot pattern for passing server-rendered UI into client shells.

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

Putting It All Together: A Complete Next.js Mini-Agent Project Recap and Full Integration Guide

Zahid Hasan Tonmoy — Thu, 12 Nov 2026 09:02:00 +0000

Following our guide on Client Components vs. Server Components in a Next.js AI agent, this post completes our 14-part Next.js implementation module by assembling DevPulse into a single cohesive application.

Closing the Loop on Level 2 Ticket Approvals

When an agent proposes a state-changing action (such as drafting a bug ticket via draftIssueTicket), clicking the confirmation button in React must trigger an idempotent server mutation rather than only toggling local UI state.

By using upsert with onConflict: 'tool_call_id' in our approveAndPersistTicket Server Action, double-clicks never create duplicate tickets in Supabase.

Resetting Client State on Session Switch

When navigating between sessions via query params, always key the client chat component with key={activeSessionKey} in page.tsx so React cleanly resets local hooks (useSmartAutoScroll, approvedTickets, and useChat) for the new session.

Read the full integration walkthrough on my blog: https://zahidhasantonmoy.vercel.app/blog/complete-nextjs-ai-agent-project-recap

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.

DEV Community: Zahid Hasan Tonmoy

Turning Your Python AI Agent Into an Asynchronous FastAPI Backend with Server-Sent Events (SSE)

Why FastAPI for AI Agents?

Streaming SSE via StreamingResponse

Beyond Next.js: How to Build a Clean, Production-Grade AI Agent in Python from Scratch

Translating Zod to Pydantic v2

The Bounded Native Loop

Client vs. Server Components in Next.js: Where Each Belongs in an AI Agent Architecture

Putting It All Together: A Complete Next.js Mini-Agent Project Recap and Full Integration Guide

Closing the Loop on Level 2 Ticket Approvals

Resetting Client State on Session Switch

AI Agent Autonomy Levels: A Small TypeScript Approval Gate

What autonomy is

A scale from Level 0 to Level 4

Sort tools by what a mistake costs

The policy in code

What I noticed rereading my own series code

Common mistakes

Read the full version

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

The problem MCP solves

Why now

A real server

Testing it against the real protocol

The bug that took a rewrite

Common mistakes

Read the full version

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

What's actually still different

Proving it in code

The near-miss writing this

Common mistakes

Read the full version

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

Why vagueness compounds in an agent prompt

The five sections

Tool descriptions are prompts too

A structured prompt, and a way to check it

Common mistakes

Read the full version

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

What RAG actually is

Three jobs, not one

A working example

The mistake that took tuning to find

Common mistakes

Read the full version

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

The four components of an AI agent

Each part in a few lines

All four in one file

The mistake that cost me an afternoon

Common mistakes

Read the full version

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

The definition I actually use

The loop

A runnable version

Why people are suddenly talking about agents

The mistake I made first

What's next

Building a Laravel Marketplace with PostgreSQL While Debugging React State

Streaming SSE via `StreamingResponse`