DEV Community: Rahul Choudhary

Every AI agent framework hides the same 5 ideas. Here they are in 200 lines.

Rahul Choudhary — Wed, 29 Jul 2026 16:20:45 +0000

So I rebuilt them from scratch. A tiny framework with no dependencies, small enough to read in one sitting and really understand.

The itch

I use agent frameworks like LangGraph and the OpenAI Agents SDK. They are good. But when you are learning, they can feel like magic. You wire a few things together, an agent appears, and you are not quite sure what happened in the middle.

I did not want more magic. I wanted to see the machine.

So I did the thing that worked so well for me with neural networks. If you have watched Andrej Karpathy build micrograd, you know the feeling. He rebuilt the core idea of PyTorch in about 150 lines, not to replace it, but to make it impossible to misunderstand. After that, PyTorch stops being magic.

I wanted the same thing for agents. So I built microagent.

The trick: picture a small office

The fastest way to understand an agent is to picture a small office.

A new assistant starts on their first day. They have a notebook, a few coworkers they can ask for help, and one simple habit. Keep working until the job is done.

That is the whole idea. Everything below is just that office, written in code. It comes down to five small pieces.

1. Message, a single note

The smallest thing in the office is one note. Someone asks a question. The assistant writes down a decision. A coworker hands back an answer. Each of those is one note.

@dataclass(frozen=True)
class Message:
    role: str            # "user", "assistant", or "tool"
    content: str
    name: str | None = None

In plain words, a note only needs three things. Who wrote it (role), what it says (content), and an optional label for which coworker it came from (name).

It is frozen, which is a fancy word for written in pen. Once a note exists, it never changes. That matters in a second.

2. Context, the notebook

One note is useless on its own. The assistant needs the whole running history. That history is the Context. Think of it as the office notebook.

Here is the one rule that makes everything simple. You never erase a page. You only add a new note to the end.

@dataclass(frozen=True)
class Context:
    messages: tuple = ()

    def add(self, *msgs):
        # We do not change this notebook. We hand back a new one.
        return Context(self.messages + tuple(msgs))

    def last(self):
        return self.messages[-1] if self.messages else None

Two small methods do the work. add takes your new note and hands back a brand new notebook with it added at the end, so the old one is never touched. last just peeks at the most recent note.

Because the notebook only grows, the full story of what happened is always right there. You can read it back, replay it, and debug it. Nothing is hidden. Memory is not a feature we add later. It is just the notebook we never erase.

3. Tool, a coworker you can call

The assistant cannot do everything alone. Need a number crunched? Call the person with the calculator. Need a file fetched? Call the person who knows the filing cabinet.

A Tool is exactly that. You hand it a request, it hands back a result.

@dataclass
class Tool:
    name: str
    description: str
    fn: object                 # the function to run
    terminal: bool = False     # does calling this end the job?

    def __call__(self, **kwargs):
        return str(self.fn(**kwargs))

In plain words, a tool has a name so the brain can ask for it, a description so the brain knows what it is for, the function to actually run, and a flag that says whether calling it ends the job.

One tool is special. It is the coworker whose job is to say we are done, the answer is X. We mark that one as terminal.

4. Policy, the brain

Now the interesting part. Who decides what to do next? Look at the notebook, pick the next move. That decision maker is the Policy. It is the brain.

A decision has two parts, which tool to call and the arguments to call it with.

@dataclass(frozen=True)
class Action:
    tool: str
    args: dict = field(default_factory=dict)
    reasoning: str = ""

Read that as the brain pointing at one coworker and saying call this one, with these details. The reasoning is a short note about why, so the story stays easy to follow later.

Here is the most important idea in the whole project. The brain is swappable. Today you can write it as a few lines of plain Python, no AI at all, just to watch the office run. Tomorrow you swap in a real language model, or even a small neural network you trained yourself. The office does not change. Only the brain does.

Swap the brain, keep the body.

5. Agent, the assistant who keeps working

Finally we tie it together. The Agent holds the brain, knows its coworkers, and follows one habit in a loop.

class Agent:
    def __init__(self, brain, tools, max_steps=6):
        self.brain = brain
        self.tools = {t.name: t for t in tools}
        self.max_steps = max_steps

    def run(self, user_input):
        ctx = Context().add(Message("user", user_input))
        for _ in range(self.max_steps):
            action = self.brain(ctx, self.tools)      # decide
            tool = self.tools[action.tool]
            result = tool(**action.args)              # act
            ctx = ctx.add(                            # write it down
                Message("assistant", action.reasoning),
                Message("tool", result, name=action.tool),
            )
            if tool.terminal:                         # are we done?
                break
        return ctx

Read the loop as one trip around, in four small steps.

Ask the brain what to do next. It looks at the notebook and picks a coworker.
Call that coworker and get a result back.
Write both the decision and the result into the notebook.
If that coworker was the one that ends the job, stop. If not, go around again.

That loop is the entire engine of every AI agent you have heard of. Decide, act, write it down, repeat. Big frameworks dress it up, but underneath, this is it.

Quick recap of the five pieces

Before we run it, here are all five in one place.

Message, a single note.
Context, the notebook you never erase.
Tool, a coworker you can call.
Policy, the brain that picks the next move.
Agent, the assistant that runs the loop until the job is done.

Watch it do real work

Here is a support agent handling a refund. It looks up the order, checks the policy, issues the refund after a human signs off, and replies to the customer. Same five pieces, pointed at real tools.

Read it top to bottom like a story. Each thought line is the brain deciding, and each arrow line is a coworker handing back a result.

you asked: "Can I get a refund for order A1234? It arrived broken."
  support thought: let me pull up the order first
    -> look_up_order returned: A1234, Wireless Headphones, $79, delivered, reported defective
  support thought: now check if it qualifies
    -> check_policy returned: eligible, within the 30 day window and reported defective
  support thought: it qualifies, and a refund needs a human to sign off
    -> issue_refund returned: approved by a human, $79 refunded to the original card
  support thought: all set, time to reply to the customer
    -> final_answer returned: Good news, A1234 qualifies. I refunded $79 to your card, here in 3 to 5 days.

Notice the third step. A risky action waited for a human to approve. That is not a special feature. It is a tool that wraps another tool.

The hard parts are not new pieces

This is the part I did not expect, and it is the best reason to build small.

When you try to add the hard, real world features, none of them need a new building block.

Multi-agent is just an agent used as a coworker. An agent can be handed to another agent as a tool. That is the whole of multi-agent systems.
Safety is just a coworker with a gate. Wrap a risky tool in one that asks for approval first.
Memory that does not blow up is one function. A long notebook in, a shorter summarized notebook out.
Recovering from errors is mostly free. Write the error into the notebook, and the brain sees its own mistake on the next turn and fixes it.

Every one of these is the same five pieces, arranged a little differently. When the hard problems do not demand new fundamentals, that is a strong sign the five pieces are the right ones.

The honest part

microagent is not a production framework, and it does not try to be. If you need to ship, use LangGraph or the OpenAI Agents SDK. They are excellent, and they solve the messy real world problems that a teaching project should not pretend to.

The whole point of microagent is different. Read every line, understand every piece, then go build the real thing knowing exactly what is underneath it.

Try it

The repo is here: github.com/rahul1368/microagent.

The best way in is the from-scratch notebook. It rebuilds all five pieces one at a time, with the office story, and runs at every step. After that, the code will feel like something you already know, because you will have written it yourself.

If this helped, a star on the repo means a lot, and I would love to hear which part finally made agents click for you.

A resumable, human-in-the-loop AI agent in ~200 lines with zero dependencies

Rahul Choudhary — Tue, 21 Jul 2026 18:44:31 +0000

Most "AI agent" libraries fall into one of two buckets. Either they're a big
framework you spend an afternoon configuring, or they're a tiny toy that drops
the one feature you actually need in production: the ability to stop and ask a
human before the agent does something you can't undo.

I wanted the middle. So I wrote yieldagent:
a small agent loop you can read end to end, with human-in-the-loop pause/resume
built in, and no runtime dependencies. This post walks through how it works and
why it's built the way it is.

What an agent loop actually is

Strip away the branding and an "agent" is a loop:

Send the conversation to the model, along with the tools it's allowed to call.
If the model asks to call a tool, run it and append the result.
Repeat until the model answers without asking for a tool.

That's it. The model decides the control flow at runtime; your job is to run the
tools and feed the results back. Here's the core, lightly trimmed:

for (let step = 0; step < maxSteps; step++) {
  const reply = await call(messages, toolSpecs);
  messages.push(reply);

  if (!reply.tool_calls?.length) {
    yield { type: "final", text: reply.content, messages };
    return;
  }

  for (const tc of reply.tool_calls) {
    const args = JSON.parse(tc.function.arguments);
    const result = await tools[tc.function.name].run(args);
    messages.push({ role: "tool", tool_call_id: tc.id, content: JSON.stringify(result) });
  }
}

Everything else in the library is in service of making this loop observable,
testable, and safe to run against the real world.

Why an async generator

Notice the yield. The loop is an async generator, so the caller drives it:

for await (const step of agent({ call, tools, messages })) {
  if (step.type === "tool-start") console.log("->", step.tool, step.args);
  if (step.type === "final") console.log(step.text);
}

Every step (each tool call, each result, and the final answer) is handed back to
you as a plain object. Nothing is hidden inside the framework. You can log it,
render it, or assert on it in a test. Which brings us to the nicest side effect.

Testing without an LLM

The model call is just a function: (messages, tools) => Promise<Message>. In
tests, you pass one that returns canned replies. No API key, no network, and the
result is deterministic:

const replies = [
  { role: "assistant", content: null, tool_calls: [{ id: "1", function: { name: "getWeather", arguments: '{"city":"Delhi"}' } }] },
  { role: "assistant", content: "It's 31°C.", tool_calls: [] },
];
let i = 0;
const call = async () => replies[i++];

const steps = [];
for await (const s of agent({ call, tools, messages })) steps.push(s);

expect(steps.map(s => s.type)).toEqual(["tool-start", "tool-end", "final"]);

The whole library is tested this way. Agent logic you can unit-test without an
LLM is worth a lot when you're iterating.

The feature that's actually hard to find: pause and resume

Real agents do risky things, send emails, spend money, delete files. You want a
human in the loop before that happens, and often you want to pause a run and
continue it later, in a different request or after a restart.

yieldagent does this with an approve callback. Return false for a tool and
the loop stops before running it, handing back a serializable resumeState:

const cfg = {
  call, tools,
  messages: [{ role: "user", content: "Email the Delhi weather to my boss" }],
  approve: (tool) => tool !== "sendEmail",
};

let paused;
for await (const step of agent(cfg)) {
  if (step.type === "paused") paused = step.resumeState; // a plain object
  if (step.type === "final") console.log(step.text);
}

Because resumeState is just data, you can write it to a database or a job
queue, wait for a human to click "approve" somewhere else entirely, then pick up
where you left off:

import { resume } from "yieldagent";
for await (const step of resume(cfg, paused)) {
  if (step.type === "final") console.log(step.text);
}

This is the part most minimal agents skip and most big frameworks turn into a
whole subsystem. Keeping it small and explicit was the main reason I wrote this.

Provider-agnostic by default

The core knows nothing about any specific provider. The included adapter talks
to anything that speaks the OpenAI /chat/completions shape, OpenAI, Anthropic's
compatible endpoint, Groq, Together, or a local model via Ollama or vLLM:

const call = openaiCompatible({
  baseURL: "http://localhost:11434/v1", // Ollama
  apiKey: "ollama",
  model: "llama3.1",
});

Or skip the adapter and write your own call, it's about a dozen lines.

A couple of nice extras

Streaming: pass stream instead of call and you get token steps as the model produces text. Tools and pause/resume still work.
Zod tools: the optional yieldagent/zod entry derives the JSON Schema from a Zod schema and validates the model's arguments, feeding errors back so the model can correct itself.
Cancellation: pass an AbortSignal to stop a run on a timeout or user cancel.

When not to use it

If you need streaming UI helpers, a big prebuilt tool ecosystem, or multi-agent
orchestration out of the box, reach for the Vercel AI SDK or LangGraph. yieldagent
is for when you'd rather own a loop you can read in a few minutes than adopt a
framework. If you outgrow it, you'll know exactly what you're replacing.

Try it

npm install yieldagent

There's a browser demo of the approval flow (no API key needed):
https://rahul1368.github.io/yieldagent/

Code and docs: https://github.com/rahul1368/yieldagent

If you build something with it, or the pause/resume API breaks down for your use
case, I'd like to hear about it.