Simple AI Agent

Everyone wants to "build an AI agent," and almost everyone starts by pip install-ing a framework. LangChain, CrewAI, AutoGen — thousands of lines of abstraction that promise to do the hard part for you. Then the demo breaks, the abstractions leak, and you're debugging someone else's control flow with no idea what's actually happening underneath.

I wanted to solve the opposite problem. Not "how do I orchestrate the most complex agent?" but "what is the smallest thing that is genuinely an agent, and what are its irreducible parts?" The answer turned out to be about a hundred lines of Python and exactly four building blocks. This is the full journey — how I framed the problem, did discovery, scoped the MVP, and built it — treated like a product, not a tutorial.

The Problem: Frameworks Hide the Fundamentals

Start with the discovery question every PM should ask: what are people actually trying to do, and why does the current solution fail them?

What people want is to understand and control how an agent reasons, remembers, and acts. What they reach for is a framework — and frameworks optimise for the opposite: they hide reasoning, remembering, and acting behind decorators and config so you can ship fast without understanding. That's a fine trade when you already know the primitives. It's a terrible one when you're trying to learn them, because the first time something breaks you have no mental model to debug against.

The gap: there was no minimal, runnable reference that shows the four primitives of an agent with nothing hidden. That gap is the product.

Who It's For

I wrote down three people who feel this pain differently — and one shared need.

• The Learner-Builder has used ChatGPT and wants to build with models, but every "build an agent" guide jumps straight to a framework. They need to see the loop with their own eyes before they trust an abstraction over it.
• The PM who wants to speak engineering. They don't need to ship production code, but they need an accurate mental model of how agents reason and call tools, so they can scope, estimate, and challenge their team credibly.
• The Developer evaluating frameworks. Before adopting LangChain, they want to know what it's actually doing for them — which means understanding what they'd write by hand.

The shared need: a mental model you can hold in your head. That became the design constraint — if it doesn't fit on one screen, it's too big for v1.

The Insight: An Agent Is Just Four Primitives

The unlock was realising that every LLM agent, no matter how elaborate, reduces to four parts. Strip away orchestration and you're left with a brain, a memory, some tools, and a loop that ties them together.

Takeaway: Naming the irreducible parts is the highest-leverage design decision. Once "agent = brain + memory + tools + loop" was on paper, the scope wrote itself.

Defining the MVP

I scoped v1 against measurable goals, so "done" wasn't a feeling.

And the non-goals — the "no"s that kept v1 shippable:

• No framework. The whole point is to not use one.
• No multi-agent orchestration. One agent, one loop.
• No streaming, no async. Clarity beats polish in a reference.
• No persistence or UI. Memory lives in a list for the duration of a run; the interface is the terminal.
• No tool sprawl. One tool (a calculator) is enough to demonstrate the pattern.

Takeaway: A learning product earns its value by what it leaves out. Every omission keeps the mental model small.

The Build

Block 1 — The Brain

The brain is the model plus a system prompt. No magic: instantiate the client, pick a model, set the reasoning style.

self.client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
self.model = "claude-sonnet-4-6"
self.system_message = (
    "You are a helpful assistant that breaks down "
    "problems into steps and solves them systematically."
)

Block 2 — Memory

Memory is a Python list. Every turn appends to it, and the entire list is sent on every call — that's what gives the model continuity.

self.messages = []  # grows with every turn

self.messages.append({"role": "user",      "content": message})
self.messages.append({"role": "assistant", "content": response.content})

What actually flows through messages[] over a tool-using exchange is the part most tutorials skip:

Block 3 — Tools

A tool is any object that can describe itself to the model and execute when called. Two methods do it: get_schema() tells Claude when and how to call it; execute() runs when it does.

class CalculatorTool:
    def get_schema(self):
        return {
            "name": "calculator",
            "description": "Performs mathematical calculations. Use for any arithmetic.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string",
                                   "description": "Math expression e.g. '157.09 * 493.89'"}
                },
                "required": ["expression"],
            },
        }

    def execute(self, expression):
        try:
            return {"result": eval(expression)}
        except Exception:
            return {"error": "Invalid mathematical expression"}

The schema is the contract. Claude never sees the Python — it sees this JSON, and from it decides whether the user's request needs arithmetic and what expression to pass. (And yes, eval is a deliberate v1 shortcut — flagged as a non-goal to harden, not a thing to ship to production.)

Block 4 — The Agent Loop

The loop is the agent. It calls the model, inspects stop_reason, and branches: if the model wants a tool, run it and feed the result back; if the model is done, return the answer.

for i in range(1, max_turns + 1):
    response = agent.chat(user_input)

    if response.stop_reason == "tool_use":
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                tool = agent.tool_map[block.name]
                result = tool.execute(**block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result),
                })
        user_input = tool_results          # feed back, loop again
    else:                                   # stop_reason == "end_turn"
        return final_text(response)

Visualised, the whole control flow is a single loop with one decision point:

Takeaway: The "intelligence" of an agent isn't in any one block — it's in the loop that lets the model act, observe the result, and decide again. That feedback cycle is the whole game.

Proving It Works

An MVP isn't done when it runs; it's done when it's demonstrably right across the paths that matter. Three test cases, each exercising a different route through the loop:

Running python agent.py makes the loop observable in the terminal — exactly the legibility the product is for:

=== Test 2: Math (Tool Required) ===

🔄 Iteration 1
📥 Input: What is 157.09 * 493.89?
🤖 Agent: I'll calculate that for you.
🔧 Using tool: calculator | Input: {'expression': '157.09 * 493.89'}
✅ Tool result: {'result': 77592.3801}

🔄 Iteration 2
🤖 Agent: 157.09 × 493.89 = 77,592.38

Ship & Teach

Shipping a learning product means two artefacts, not one: the code that runs, and the explanation that makes it legible.

• One-command run. pip install -r requirements.txt, drop an API key in .env, then python agent.py. No build, no services.
• A README that teaches. Each block is documented with the exact lines that implement it, plus an "extending the agent" guide (add a tool, swap the model).
• An interactive infographic. A standalone infographic.html visualises the four blocks, the loop, the message format, and the test paths — the same diagrams recreated in this article.
• Extensible by design. Adding a tool is one class and one line: Agent(tools=[CalculatorTool(), WebSearchTool()]). The loop doesn't change.

What I'd Build Next

The roadmap follows the non-goals — each one is a deliberate v2+ candidate, not an oversight:

• A safe calculator — replace eval with a sandboxed expression parser (the obvious first hardening).
• More tools — web search, file read/write — to show multi-tool dispatch and how the model chooses between them.
• Streaming output — token-by-token responses for a more agent-like feel.
• Persistent memory — save messages[] across runs to demonstrate long-term context.
• A thin UI — a minimal chat front-end over the same loop, proving the core never had to change.