Agents From First Principles on Programmer.ie

What Is an Agent, Really?

Sat, 08 Aug 2026 15:40:00 +0100

This book is about building systems around models. Before we build planners, memory, tool routing, critics, search and verifiers, we need an answer to a question that turns out to be harder than it looks:

What is an agent?

The word is currently applied to almost everything: a single LLM call, a chatbot, a fixed pipeline, a tool-using loop, and any five model calls with class names ending in Agent. Those systems may all be useful. But when one word covers all of them, it stops telling us anything about the computation, and we lose the ability to say which mechanism is doing the work.

The Action Boundary

Sat, 08 Aug 2026 15:46:00 +0100

The previous chapter ended with a division of responsibility:

The model proposes. The runtime decides what may execute. The environment provides evidence about what actually happened.

This chapter takes the first clause seriously. What does it actually mean for a model to propose an action?

Suppose the model emits the sentence “Search the documentation for the latest PyTorch optimizer API.” A human reads that and understands the intention immediately. A runtime cannot act on it at all, because it needs answers to six questions the sentence does not contain: which action, which arguments, whether those arguments are well formed, whether their values are meaningful, whether this action is permitted in this run, and whether its execution preconditions currently hold.

Candidate Generation and Selection

Sat, 08 Aug 2026 15:54:00 +0100

The previous chapter built a boundary that stops arbitrary text from becoming an action. It solved one class of failure completely, and it is silent about another.

Suppose the model is asked to solve a coding problem. One run produces the right patch. The next produces a plausible but incomplete one. A third produces something better again. Nothing is malformed, nothing violates the action schema, and every one of them would pass the boundary we just built. Validity and quality are different properties. A proposal can be completely valid and still be a poor choice, which relocates the uncertainty rather than removing it:

Critique, Revision, and Acceptance

Sat, 08 Aug 2026 16:23:00 +0100

Selection is a filter, and a filter can only return the best thing that was put into it.

That is a practical limitation rather than a pedantic one, because the candidates come from one model answering one prompt, and such samples correlate. When four candidates share a misreading of the evidence, the selector does not detect the misreading. It ranks four versions of it and reports the winner with a confident score.

Planning and Execution

Sat, 08 Aug 2026 16:35:00 +0100

The critique loop works on one thing at a time. It assumes the task already exists as a candidate we can hold, inspect and improve.

Some tasks have no draft to hold.

Inspect a project, reproduce the failing test, find the cause, patch the code, rerun the relevant tests, and report what changed.

No single narrow action responsibly completes that goal, and the actions constrain each other. Patching before diagnosis is guesswork wearing the costume of work, and reporting success before observing a passing test is a claim about the world that nothing in the run supports. Worse, if execution reveals that an assumption was wrong, the rest of the route may be wrong too. A runtime choosing each action independently can react to the new observation, but without an explicit representation of the intended route it has nothing concrete to compare the changed world against.

Runtime State, Progress, and Termination

Sat, 08 Aug 2026 16:56:00 +0100

A plan is a claim about the future. It says that reproducing the failure, then diagnosing it, then patching, then testing, is a route from here to a working system. Making that claim explicit was worth the machinery. But it is written before any of the work happens, and execution may invalidate one of its assumptions almost immediately.

Execution produces something else entirely: a trajectory. Actions went out, observations came back, and some of what came back may contradict the intended route. The patch step failed because a dependency is missing. The test step is not merely late; it is unreachable.

Capabilities and Routing

Sat, 08 Aug 2026 17:09:00 +0100

Every mechanism built so far has taken the action set as given. The action boundary validates a proposal against a fixed list of permitted action types. Candidate generation samples several proposals from the same list. The runtime-state chapter watches what happens after execution and decides whether to continue. All of them assume that somebody, somewhere, already decided which capabilities the policy could choose from.

Nobody did. That decision is the subject of this chapter, and it is a design decision with consequences as large as any of the mechanisms around it.

Memory and Selective Recall

Sat, 08 Aug 2026 17:14:00 +0100

The capability boundary gave the agent a defined action space and a rule for which capabilities are eligible at each step. Runtime state gave it an explicit working representation of what this run has established so far and how it reached that point. Both mechanisms are confined to the present run, and there is a family of failures they cannot reach.

An agent hits an error that a previous run already diagnosed, and diagnoses it again from scratch. A user stated a constraint three weeks ago that still binds. A strategy failed last month for a reason that has not gone away. A policy changed yesterday, and something the system learned in January is now confidently wrong.

Trajectory Search

Sat, 08 Aug 2026 17:26:00 +0100

An agent can make every local decision look reasonable and still lose the task.

A coding agent sees that test_checkout_redirect is failing, concludes there is an implementation bug in checkout.py, and then behaves impeccably for twenty steps: it reads the file, edits it, runs the tests, repairs the new failures its edit introduced, rewrites the patch, and runs the tests again. Every one of those steps is defensible given the step before it.

Evidence and Verification

Sat, 08 Aug 2026 17:31:00 +0100

The agent says:

Done.

That is a claim.

It is not evidence.

Every mechanism in this book so far has made the agent better at deciding what to do, and none of them establishes that the user’s goal was achieved. A planner can produce a coherent plan for the wrong problem. A tool can return exit code zero without producing the intended effect. A search can select the highest-scoring branch when every branch is wrong. A memory system can retrieve a perfectly relevant fact that stopped being true in March.

Building the Complete Agent

Wed, 26 Aug 2026 10:00:00 +0100

Every mechanism in this book was argued against a problem chosen to isolate it.

That isolation was deliberate, and it was also a form of protection. The memory chapter picked a task where recall was the bottleneck, held everything else still, and measured the one thing it came to measure. The result is a clean explanation and a weak claim. Nothing in it establishes that the same retrieval policy behaves when a search controller is expanding forty nodes, or when a verifier insists that every piece of evidence carry a state identity the search controller has never heard of.