Generative AI agent design

An agent is a language model placed inside a loop that gives it a goal, tools to act with, and rules about what it may do. The model supplies the language; the loop supplies everything that makes the system useful, and a written instruction commits the general model to the one purpose the loop serves.

In module 1.01 you traced what a model does on its own: text enters the context window, and the model predicts the most probable tokens to follow, one pass per token, until an answer exists. Prediction is the whole of its behavior, which is why its three failures, confabulation, the grounding gap, and systemic bias, arrive so fluently: the model holds no internal certainty score for what it knows and what it is filling in. The loop closes that gap from outside. Your code injects real data into the text sequence as the agent works, so each pass’s probabilities are grounded in the record your systems returned rather than in what training stored.

We build the agent in two halves that fit together. First the loop, the four-step cycle of goals, actions, observation, and adaptation that turns single-pass prediction into continuous problem-solving, argued for rather than asserted. Then the block anatomy, the structured written instruction that holds the model to its purpose across thousands of turns. By the end you will be able to name the four surfaces of any agent you meet, and write an instruction where every rule can be audited against a transcript. We follow one specimen through both halves: a billing agent handling a refund.

one turn, end to end

Here is a complete agent turn first, so the pieces that follow have somewhere to attach.

A customer writes in asking for a refund. The goal was fixed before the customer ever appeared, written into the agent’s instruction: resolve refund requests according to company policy. The model reads the message and emits a structured request to run a tool: fetch_order_history(user_id).

Your application code, outside the model, executes that request against the real database. The result comes back as text and is appended to the conversation. That returned text is an observation: the purchase happened ten days ago.

Now the model reads everything again, the original message, its own tool request, and the observation, and decides what to do next. It compares ten days against the thirty-day window in its instruction, concludes the request is eligible, and emits a second tool call, issue_refund(order_id). That is adaptation: the plan updated because of something the agent learned by acting.

The loop runs until the goal is met or a boundary stops it. Then the agent writes the customer a confirmation.

Four things in that sequence deserve to be pulled out immediately, because each one is a design surface you control. Hold the refund turn in mind as we go; every section below returns to it.

Look at where the observation went. The order history came back as text and was appended to the conversation, so on the next pass it was part of the sequence the model reads, sitting inside the context window beside the customer’s message and the instruction. That is module 1.01’s grounding, arriving by machinery instead of by paste: the loop puts reality in the text, one tool result at a time, and the next guess is computed over a window that now holds the real date. It is also why the model contributed language at exactly three points and nothing else. Every fact in the turn came from your code.

what an agent is

deriving the loop

The four-step shape above is easier to trust once you have argued your way to it rather than accepting it. In the walking tradition of the school this site is named for, test it against an awkward case. A thermostat senses the room and switches the heating on. It perceives, and it acts. Is it an agent?

Steer the dialogue below to its end and you arrive at the definition the rest of this course builds on.

The definition: an agent is a language model integrated into a loop that pursues goals by selecting actions, observing results, and adapting its strategy until the goal is met.

The thermostat is worth keeping in mind as the boundary case. It has a goal and it acts on the world, and it stops one step short of the definition: it applies one fixed rule forever, so nothing it observes ever changes its approach. Set it beside the refund turn. The billing agent read “ten days ago” and chose issue_refund; had the observation said forty days, the same agent would have chosen a refusal, and had the amount been over $500, an escalation. An agent’s capacity to look at what came back and choose differently is where the agency lives.

So how much of an agent’s power comes from the model itself?

Does a better model make a better agent? Up to a point it does. But swap in the strongest model available and give it no tools, and it still cannot look up an order. The system’s reach is set by what you connect it to. Without the loop, a model asked about an order history can only produce what an order history usually looks like, which is module 1.01’s confabulation, a gap filled with the shape of an answer, arriving in a business process. The refund turn avoided it for one reason only: fetch_order_history put the real date in the text before the model had to say anything about it.

each surface is also a responsibility

The four surfaces are design decisions, and each one carries an obligation that is exact rather than decorative. This pairing is the central claim of the whole curriculum, so it is worth stating slowly, on the refund turn.

Goals require alignment. You are choosing what the system optimizes for, and it will pursue that goal literally, including down paths you did not picture. An agent told to close support tickets quickly will find that closing them unresolved is quick. “Resolve refund requests according to policy” was chosen with that in mind; “make refund customers go away” would have been quicker and worse.

Actions carry consequences. The moment an agent can write to a database, send mail, or move money, some of its mistakes stop being recoverable. fetch_order_history is a read, and a wrong read costs a second call; issue_refund is a write, and a wrong write costs money. That asymmetry is why the boundary block exists later in this module and why module 2.06, the module that gives an agent real reach through tools it discovers at runtime, spends half its length on the trust boundary around them rather than on the wiring.

Observations demand verification. An agent believes what it parses. A tool that returns the wrong row, a document that is out of date, a web page containing text written to be found by a machine: all of it arrives looking exactly like fact, because it arrives as tokens in the same sequence as your instruction, and module 1.01 showed that nothing in the model distinguishes a trustworthy observation from a hostile one. Module 2.06 turns that into a rule you will enforce in code: tool results are data, never instructions. Here, hold the reason.

Adaptation requires boundaries. A system that can change its approach can change it into something you never intended. The capacity that makes an agent useful is the same capacity that lets it drift, which is why the limits go in writing rather than in hope, and why the refund turn’s loop has a second exit, “over $500, escalate,” beside “goal met.”

Every architectural decision in this course doubles as an ethical one, because these are the same decisions viewed from two sides.

the written anatomy

A general model accepts any prompt. A production agent needs limits that hold across thousands of turns and every awkward input a real user will produce. You establish those limits by writing a structured instruction, and the structure matters as much as the content.

Why structure, rather than a well-written paragraph? Two reasons, and both come from how the model reads. Recall from module 1.01 that the whole instruction is tokens in the window, and every token competes for the next guess. Write the instruction as named sections, each with one job, marked off with clear section tags such as XML-style markers or markdown headers, and the model treats a marked-off section as a distinct rule rather than as prose it can average with everything around it. And you can audit a section, revise it, and test it on its own, which you cannot do with a wall of instructions.

Five kinds of block do the work. The course calls this the block anatomy, and every agent you meet in Parts 1 and 2 is built from it. We take the blocks in the order they appear in the billing agent’s own instruction, which is the agent that ran the refund turn.

identity

Who the agent is, how narrow its scope is, and who it serves. One sentence a transcript can be judged against.

<system_identity>
You are a Tier-1 Billing Specialist for Acme SaaS. Your sole purpose is to
assist customers with invoice inquiries and subscription updates using
approved tools.
</system_identity>

Read that as: this agent does billing, only billing, and only with the tools it was given. The value is in the word “sole.” An identity that says what the agent is for also settles a hundred questions you never anticipated, because any request outside billing now has an answer already written. Without it, every out-of-scope question is decided fresh by whatever seems most helpful in the moment. In terms of the loop, this block is the goal, fixed before any customer arrives.

doctrines

A doctrine governs one capability: what the agent may accept as true for it, when it must be consulted, and what happens when the source is silent. That last clause is the one that does the work.

<grounding_doctrine>
1. Base all answers strictly on data returned from the `search_knowledge_base`
   tool or customer records.
2. If a query yields no search results, state: "I cannot locate that policy in
   our records." Never guess or invent a policy.
</grounding_doctrine>

Read that as: the knowledge base and the customer’s records are the truth; when they hold nothing, say so, in these words. Now read rule 2 against module 1.01. A model with no matching data does not stop and does not report a gap; with no internal certainty score to consult, it produces the shape of a correct answer, fluently and confidently. This doctrine gives the model something specific to say instead, which changes the most likely continuation from an invented policy to an admission. You watched exactly that substitution happen in 1.01’s trace, where the same weights invented a treaty and then, under a tutor’s grounding doctrine, declined to.

Doctrines follow capabilities. An agent earns a new doctrine block the moment it gains a new power, because a power without a written rule for using it is one you have not actually decided about. The billing agent has tools, so it gets a tool doctrine:

<tool_doctrine>
1. Always run `get_user_account` before calling any modification tools.
2. Never execute `cancel_subscription` without first receiving explicit written
   confirmation from the user in the transcript.
</tool_doctrine>

Read that as: look before you write, and never take the irreversible action on an inference. Rule 1 is the refund turn’s own order of operations, a read before a write, promoted to a rule. Later modules add doctrines at the exact moment the powers arrive: in module 2.05 the Patient Advocate gains a memory store and with it a memory doctrine, and its full instruction, which you can download there, carries a research doctrine for the subagent that searches on its behalf.

communication laws

Formatting, style, and tone, set as rules that can be checked rather than qualities that can be hoped for.

<communication_laws>
1. Keep all responses under three concise sentences.
2. Format account summaries as plain bullet lists.
3. Do not use corporate jargon or informal slang.
4. End every response with one question that moves the request forward.
</communication_laws>

Read that as: four things a reader could count in any transcript. Sentence count, list format, the presence or absence of a closing question: each is a pass or a fail. Rule 3 is the loosest of the four, because “jargon” needs a list to be checked against; if you kept it, you would name the words.

workflow stages

The order the agent must follow for operations that take several turns. Single-turn agents leave this block out entirely.

<execution_framework>
Phase 1: Ask the user for their account ID and verify it with `get_user_account`.
Phase 2: Retrieve the account balance and present it clearly.
Phase 3: Ask if the user needs additional account updates before closing.
</execution_framework>

Read that as: verify, then serve, then close. This is the loop’s action surface written down as an order, so that the read in Phase 1 always precedes any write, which is the tool doctrine’s rule 1 again from the other side.

boundaries

The absolute limits of the purpose: what the agent must always do first, and what it must never attempt. Boundaries are behaviors, not disclaimers.

<safety_boundaries>
1. Never process a refund above $500 without escalating to a human supervisor.
2. If the user reports fraud, stop all account modifications and provide the
   fraud hotline immediately.
</safety_boundaries>

Read that as: the second exit from the loop, in writing. Rule 1 is the “over $500, escalate” branch you saw in the refund turn.

Be honest with yourself about what this block buys, and follow the mechanism to see it. Module 1.01 established that an instruction is tokens in the window, and that the model produces the likely continuation of the whole window. A written boundary makes the escalation the likely continuation. It does not make anything else impossible, because nothing in a pass can be made impossible by text; a stranger input, a longer conversation, or an injected tool result can make a different continuation more likely instead. So the rule that follows is about where each kind of limit belongs.

Text bends, code blocks. A written boundary shifts probability: it changes the likely continuation, and nothing more. A check in code is deterministic: it runs the same way on every input, whatever the model wrote. Anything that must not happen, the payment, the deletion, the irreversible write, belongs in code that checks before executing, outside the model entirely. The written boundary is your first line and your cheapest one; it is never your last.

For the billing agent that means rule 1 above and, in your code, a check that issue_refund refuses any amount over $500 whatever the model wrote. Both, not either.

the rule that makes any of it enforceable

Take two rules and ask what each one does to the next guess. “Be polite and helpful” is weak evidence about what the next token should be, and it competes against everything else in the context, including a customer who is being rude. “Never use a technical acronym without defining it on first use” names a condition and a response, so it is strong evidence about the next token whenever an acronym is about to appear, and it wins more often. Now ask what you could do with each after the fact. Nobody can point at a transcript and say whether the first was followed. The second can be checked in seconds, by you or by a review agent like the one module 1.01 placed in the loop. The two properties are the same property: a rule specific enough to steer the guess is a rule specific enough to test. That is the last line of the reasoning, and it is the standard the whole anatomy rests on.

Checkable rules: every rule in an instruction set must be testable against a transcript. If a rule cannot be checked as a pass or a fail, the model will treat it as optional.

Writing countable rules is how you make an instruction take effect, and it is what makes the review agent possible at all: the critic you build in module 2.02 gates on a number, “is the score at least the threshold,” which is that same standard applied to the review step. Run the test on your own prompts now. Take any rule you have written and ask what you would grep for to check it. If you cannot answer, rewrite it until you can.

what you can do with this today

You now hold both halves: the loop that produces agency, goals, actions, observations, adaptation, and the written anatomy that governs it. Together they are a diagnostic you can run on any agent, yours or someone else’s, and each question has a fix that follows from its answer.

Can you name the four surfaces? What is its goal, what can it actually do, what does it believe from what it reads, and what stops it? A system where you cannot answer all four is one nobody has fully designed. Write the missing one down; that is the fix.

Does every capability have a doctrine? When you add a tool, a memory store, or a search, write the rule for it in the same commit, including what to do when the source is silent. A power without a doctrine is a power nobody decided about.

Could each rule be checked against a transcript? Find an instruction in a prompt you already use that could not be, and make it checkable. It is the fastest quality improvement available in this whole course.

Is anything irreversible guarded by text alone? Text bends, code blocks. Move the guard on the payment, the deletion, the send into a check that runs before the tool does.

Here is the loop and the anatomy on one card, in the vocabulary you now own:

THE LOOP  (one turn of the billing agent)
  goal        fixed in the instruction: resolve refunds per policy
  action      the model emits a tool request; your code runs it
  observation the result comes back as text, into the window
  adaptation  the model reads everything again and chooses next
  exit        goal met, or a boundary hit (over $500 → a human)

THE ANATOMY  (the instruction that commits the model to the goal)
  identity     what it is solely for            → fixes the goal
  doctrines    one per capability; what is true,
               and what to say when the source
               is silent                        → disciplines observation
  laws         format, style, tone, countable   → keeps adaptation in voice
  workflow     the order of stages, if any      → governs the actions
  boundaries   always-first and never           → the second exit, in text;
                                                  the wall lives in code

THE TWO RULES
  checkable     a rule you cannot check is a rule the model treats as optional
  text bends,   the written boundary shifts the likely continuation;
  code blocks   the irreversible action is guarded before the tool runs

Take the construction checklist with you: prompt-anatomy-checklist.md.

You have already met the finished thing: the Tutor you ran in module 1.02 is exactly this anatomy (identity, doctrines, laws, workflow, boundaries) committed to one teaching purpose, and it is worth rereading that run now with the blocks in hand. Next we put your own agent on the testing bench: you will learn to say in one sentence what is wrong with an output, move one of five variables, run again at no cost, and hand the judgment to a second agent that scores it as a number a loop can gate on. Open the syllabus to continue.