How an Agent Actually Runs

The agent loop — the thing to see through

One line: An agent isn't a mysterious system — it's the cycle of LLM decision + tool execution + result feedback, running until the goal is met.

Imagine giving a smart assistant a task and a keyboard. It receives the task, the model proposes the next action (e.g. a command to run), that action is executed (via bash / a subprocess / a tool), and the observation (what came back) is pasted back into the conversation so the model can decide the next step. That's the whole engine. The five things worth tracing in any codebase: how the task comes in, how the model picks the next action, how the action executes, how the observation re-enters context, and how the loop knows when to stop.

The five questions to answer in any agent's code

• How does the agent receive the task? (the initial prompt + system prompt)
• How does the model generate the next action? (free-text command, JSON tool call, or Python code)
• How does the action execute? (bash / subprocess / a registered tool function)
• How does the observation get fed back? (appended to the message history)
• Why is a linear history easier to debug? (every step just appends — you can replay exactly what the model saw)

mini-swe-agent — the minimal runnable skeleton

One line: ~100 lines of Python that solve real GitHub issues — the cleanest way to see an agent loop with zero scaffolding.

It's the "hello world" of coding agents. Built by the Princeton/Stanford team behind SWE-bench and SWE-agent, it deliberately strips everything away: no custom tools, no plugins, no vector DB — the agent's only action is to run a bash command, and each command runs independently via subprocess.run. Despite that, it scores >74% on SWE-bench Verified. The lesson: as models got better at agentic coding, most of the old scaffolding became unnecessary — so this is the perfect baseline to study because the model, not the framework, is doing the work.

What to trace here

• The bare loop — prompt in, model emits a bash command, it runs, output appends to history, repeat.
• Linear history — every step just appends to the message list; nothing hidden, trivially replayable (why it's easy to debug).
• Stateless execution — subprocess.run per action, no persistent shell session to reason about.
• The 3-way decoupling — model (which LLM), environment (where commands run: local / Docker), and agent (the loop) are cleanly separated.
• No tool-calling interface needed — works with any model because actions are just text commands, not a special API.

smolagents — ReAct, tools & CodeAgent

One line: HuggingFace's ~1,000-line framework — more reusable than mini-swe-agent, and the best place to internalize ReAct and tool design.

If mini-swe-agent shows the skeleton, smolagents shows the reusable body. Every agent here is a MultiStepAgent — an implementation of ReAct, the loop of Think → Act → Observe. Its signature idea: the default CodeAgent writes its actions as Python code (run in a sandbox) instead of emitting JSON — which lets one step combine tools, loop, and use conditionals naturally, and research suggests models act more effectively in code than in JSON. The alternative ToolCallingAgent writes actions as JSON tool calls, the classic style.

What to focus on

• The ReAct cycle in code — how Think / Act / Observe actually map to functions and the message log.
• Defining a Tool — how a tool is declared and how the model is told it can call it.
• Why CodeAgent writes Python — composability (nesting, loops, conditionals) and fewer round-trips than JSON calls.
• Built-in & custom tools — e.g. a web-search tool; how to write your own and adapt different models.
• CodeAgent vs ToolCallingAgent — code-as-action vs JSON-as-action (see the table below).

Mini-Agent — the full engineering structure

One line: The first two teach principles; this one shows the engineering — what a real agent needs to run long tasks reliably.

A toy loop works for one quick task; a real agent has to survive a long one. That means solving the engineering problems around the loop: what to do when context gets too long (summarize/compact it), how to remember things across runs (a persistent "Session Note"), how to plug in reusable workflows (Skills) and external tools (MCP), and how to organize logs, config, and the CLI so it's debuggable and operable. The thing to truly internalize: a long-running agent isn't just "calls tools" — it must also handle context, memory, observability, and extensibility.

What to study

• The complete agent execution loop — the full version, with all the production concerns wired in.
• Filesystem & Shell tools — how real file/command tools are exposed safely.
• Context compaction — when the conversation gets too long, how it summarizes/compresses to stay under the window.
• Session Note (persistent memory) — how learnings survive across sessions, distinct from the in-context history.
• Skills — how reusable workflows are plugged in.
• MCP — how external tools are extended in via a standard protocol.
• Logs / config / CLI — how the project is organized for operability.

The learning method — one mainline per project

One line: Don't read the whole codebase. Per project, follow a single thread — and finish by changing something small yourself.

The reading thread

• Run the demo first — get it working before reading anything.
• Find the entry file — where execution starts.
• Read down the agent loop — follow the loop, ignore the rest at first.
• Draw the flow — sketch "model input → tool execution → result returned."
• Then change one small thing — this is what turns reading into understanding.

Suggested small modifications (to prove you get it)

• Add a simple constraint to mini-swe-agent (e.g. limit which commands it may run).
• Write a custom Tool for smolagents.
• Run a task on Mini-Agent with memory / context-compaction turned on.

The framework landscape — and why to delay it

One line: The big orchestration frameworks are powerful but heavy — learn the loop first so they're not a black box.

These are the "batteries-included" toolkits everyone reaches for. They're useful, but starting here hides the loop you actually need to understand. The advice: get a minimal agent running, learn tools and ReAct, then study memory/skills/MCP — then a framework is just a convenience layer you can reason about.