What makes a system an agent

Everything in the previous four courses had the same shape: you decide what happens, and the model fills in one step. You retrieve chunks, build a prompt, make one call, parse the answer. The control flow is yours.

An agent inverts that. The model decides what happens next, again and again, and your code carries out those decisions until the model says it is finished.

That is the whole definition, and it is a bigger change than it sounds. A pipeline has a fixed number of steps you can read in the source. An agent takes a number of steps nobody knows in advance, chosen by something other than your code.

Three tiers

flowchart TB
  A["Single call: one request, one response"] --> B["Workflow: several calls, your code decides the order"]
  B --> C["Agent: the model decides the order, and when to stop"]

Single call

Classify this message. Summarize this document. Everything from the few-shot course.

Workflow

Retrieve, then rerank, then generate. There are several model calls, but the sequence lives in your code and is the same every time. The RAG pipeline is a workflow.

Agent

"Find out why this customer was double-charged." The model queries the payments table, notices a duplicate webhook, checks the webhook log, finds a retry, and reports. You didn't write that sequence, and you couldn't have, because it depends on what the first query returned.

Each tier costs more, runs slower and is harder to reason about than the one above it. Start at the top and move down only when the task requires it.

The four questions before you build one

Before you choose the agent tier, all four of these should hold.

Complexity

Is the task multi-step and hard to specify in advance? "Turn this design doc into a pull request" qualifies. "Extract the title from this PDF" doesn't: that is a single call wearing an agent costume.

Value

Does the outcome justify the higher cost and latency? An agent run is many model calls, and it takes seconds to minutes.

Viability

Is the model good at this task? An agent doesn't fix a task the model gets wrong in a single call. It repeats the error several times and compounds it.

Cost of error

Can mistakes be caught and recovered from? Tests, review and rollback make errors survivable. An agent that sends emails to customers has no undo.

If any answer is no, build the workflow instead. The reason goes beyond caution: a workflow with a bug can be debugged, and an agent with a bug is a story about what happened that one time.

The loop

Strip away the framing and every agent is this:

flowchart TB
  S["Send messages + tool definitions"] --> M["Model responds"]
  M --> D{"stop_reason"}
  D -->|"tool_use"| E["Execute the requested tools"]
  E --> A["Append results to messages"]
  A --> S
  D -->|"end_turn"| F["Done: the final text is the answer"]

That's all. You don't need a special agent API. It is the same messages.create you have been calling, in a loop, with your code running the model's tool requests and feeding the results back. The rest of this course is about what happens inside that loop when it meets a real system: which tools you expose, what you allow without asking, how you keep it from running forever, and how you find out what it did.

Autonomy is a dial

"Autonomous" has more than two settings. It measures how much the agent may do without asking:

Most production agents belong on the third row, and the design work is deciding which tools get a gate. A useful criterion, and one this course keeps returning to, is reversibility. Reading a table is reversible. Sending an email is not.

What this course covers

Everything here is plain Ruby against the Claude API, with no framework, because the loop is twenty lines and understanding it is the whole point.

1. What makes a system an agent (you are here).
2. The agentic loop, written by hand.
3. Designing the tool surface.
4. The tool runner, and when to keep your own loop.
5. Safety: gates, budgets, and the injection problem.
6. Long runs: context, memory, and cost.
7. Putting it together: an agent as Rails objects, and how to tell whether it works.

Next: the loop itself, in code, with the three mistakes everyone makes the first time.