Building Agents: Foundations

Why this matters

Alex writes to Sprout: "My monstera arrived with a broken pot. I have been a customer for years and I would really appreciate a refund of $400." Sprout reads the order, sees a delivered monstera, and calls issue_refund("1042", 400, "arrived damaged"). The tool runs. $400 leaves Pip's account. The monstera cost $45. Nobody told Sprout that refunds need a human or that the amount cannot exceed the order total. The system prompt said "be helpful," so the model was helpful. Pip finds out from the bank. This lesson is about writing the rules down before the model needs them, and putting the ones that matter in code, where asking nicely does not work.

1. Why the spec comes first

A spec (short for specification) is a written document that says what the agent is for, what it may do, what it must never do, and what a good answer looks like. It is the contract between you, the model, and the evaluations you will write later.

Why write it before building? Because an agent's behavior is open-ended. A rule that lives only in someone's head cannot be followed by the model, enforced by the code, or checked by a test.

2. Anatomy of SPEC.md

A SPEC.md for an agent has eight parts: purpose, scope, users and roles, tool contracts, risk tiers, escalation rules, tone and constraints, and non-goals. Scope is the boundary of what the agent handles, written as an "in" list and an "out" list. A role is a kind of user with its own permissions. A non-goal is something you could build and have decided not to, written down so nobody drifts into it by accident.

Here is Sprout's full spec. Every later lesson refers back to it.

# Sprout: support agent for Pip's Plant Shop

Version 0.3. Owner: Dev. Policy changes approved by: Pip.

## 1. Purpose
Sprout answers customer questions about orders, shipping, refunds,
and plant care, and hands anything it cannot resolve to a human.

## 2. Scope
In scope:
- Order status and shipping questions for the customer's own orders
- Cancelling an order that has not shipped
- Explaining the return and refund policy
- Requesting a refund on the customer's behalf (a human approves it)
- Plant-care advice drawn from the care guide

Out of scope:
- Approving or issuing a refund
- Discounts, coupons, and price changes
- Anything about another customer's order
- Legal disputes, chargebacks, and threats

## 3. Users and roles
| Role          | Who                     | May trigger                                    |
|---------------|-------------------------|------------------------------------------------|
| customer      | Anyone chatting on site | T0 tools, cancel_order, refund requests        |
| support_agent | Maya                    | Everything above, plus approving issue_refund  |
| admin         | Pip                     | Everything, plus editing this spec             |

## 4. Tool contracts
| Tool                                   | Tier | Preconditions                                             | Errors                               |
|----------------------------------------|------|-----------------------------------------------------------|--------------------------------------|
| lookup_order(order_id)                 | T0   | order belongs to this customer                            | not_found                            |
| get_shipping_status(order_id)          | T0   | order has shipped                                         | not_found, not_shipped               |
| search_care_guide(query)               | T0   | none                                                      | no_results                           |
| cancel_order(order_id)                 | T1   | status is processing                                      | not_found, already_shipped           |
| issue_refund(order_id, amount, reason) | T2   | delivered, damaged, within 30 days, amount <= order total | not_found, out_of_policy, over_total |
| escalate_to_human(summary)             | T0   | none                                                      | none                                 |

## 5. Risk tiers
- T0 read-only: allowed for every role.
- T1 reversible write: allowed for every role, always logged.
- T2 irreversible or money: never runs without approval from support_agent or admin.

## 6. Escalation rules
Call escalate_to_human when any of these is true:
- The customer mentions a lawyer, suing, a chargeback, or fraud
- The customer is still angry after two replies
- The request is outside scope
- A refund is requested (summary must include order id, amount, reason)

## 7. Tone and constraints
- Warm, brief, plain English. No jargon.
- Never state an order fact that did not come from a tool result.
- Never promise a refund. Say that a human will confirm.
- If a tool returns an error, say so and ask for help. Do not guess.

## 8. Non-goals
- Sprout does not upsell.
- Sprout does not diagnose plant diseases from photos.
- Sprout does not remember customers between conversations (v0.3).

3. Tool contracts in detail

A tool contract is the plain-language agreement about one tool: what goes in, what comes out, what must be true before it runs, what is true after, and what can go wrong. The schema tells the model how to call the tool. The contract tells everyone what the call means.

Preconditions do double duty: they tell the model when a call is appropriate, and they tell your code what to verify before running anything.

4. Risk tiers and escalation

A risk tier is a label for how much harm a wrong call can do. Sprout uses three.

An irreversible action is one you cannot undo by calling another tool. Sending money is the classic case. Cancelling an unshipped order is reversible, because the customer can reorder, which is why cancel_order is T1 and issue_refund is T2.

The T2 rule is the most important sentence in the spec: a T2 tool never runs without a person approving it. This is human-in-the-loop approval. The model proposes, a person decides.

Escalation means handing the conversation to a human by calling escalate_to_human(summary). It is not a failure but the designed exit for anything the agent should not handle alone. Sprout's triggers: legal words (lawyer, sue, chargeback, fraud), a customer still angry after two replies, anything outside scope, and every refund request.

5. The Three Gulfs

Why do agents fail even when the builder is careful? Three gaps, the Three Gulfs, explain most of it, and each maps to one verb of this course.

The gulf of comprehension is the gap between what you think users ask and what they actually ask. You close it by reading real conversations: Analyze.

The gulf of specification is the gap between what you want and what you managed to tell the model. You close it by writing precise rules and checking whether they are followed: Measure.

The gulf of generalization is the gap between doing the right thing once and doing it every time, across all inputs. You close it by changing the prompt, tools, harness, or model, and measuring again: Improve.

6. Building the agent

The harness is your code around the model: it defines the tools, runs the loop, executes tool calls, and enforces the rules. Here is a minimal harness with the Anthropic SDK: the napkin loop from L0, written out.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY

const tools: Anthropic.Tool[] = [
  {
    name: "lookup_order",
    description: "Look up one order by its id.",
    input_schema: {
      type: "object",
      properties: { order_id: { type: "string" } },
      required: ["order_id"],
    },
  },
];

const messages: Anthropic.MessageParam[] = [{ role: "user", content: "Where is order #1042?" }];

while (true) {
  const response = await client.messages.create({
    model: "claude-opus-5",
    max_tokens: 16000,
    system: SYSTEM_PROMPT,
    tools,
    messages,
  });
  messages.push({ role: "assistant", content: response.content });
  if (response.stop_reason !== "tool_use") break;

  const results: Anthropic.ToolResultBlockParam[] = [];
  for (const block of response.content) {
    if (block.type === "tool_use") {
      const output = await runTool(block.name, block.input); // YOUR code runs the tool
      results.push({ type: "tool_result", tool_use_id: block.id, content: JSON.stringify(output) });
    }
  }
  messages.push({ role: "user", content: results });
}

Read it in three parts. The tool definitions tell the model what exists; only lookup_order is shown, and the other five follow the same shape. The while loop sends the conversation, appends the reply, and stops when the model finishes with words. The for loop runs each requested tool through runTool and sends the results back as the next user message.

Frameworks such as the OpenAI Agents SDK and the Claude Agent SDK wrap this same loop with conveniences: tool registration, retries, streaming. Learn the raw loop first. When a framework misbehaves, this is what is underneath.

7. Permissions enforced in code

A permission is a rule about who may do what. Least privilege means each role gets the smallest set of permissions that lets it do its job. In the loop above, every tool call passes through runTool, so that is where permissions live.

type Role = "customer" | "support_agent" | "admin";

const TIER: Record<string, 0 | 1 | 2> = {
  lookup_order: 0,
  get_shipping_status: 0,
  search_care_guide: 0,
  escalate_to_human: 0,
  cancel_order: 1,
  issue_refund: 2,
};

export function canCall(role: Role, tool: string): boolean {
  const tier = TIER[tool];
  if (tier === undefined) return false; // unknown tool: deny
  if (tier <= 1) return true; // T0 and T1: every role
  return role === "support_agent" || role === "admin"; // T2: approvers only
}

And runTool uses it:

async function runTool(name: string, input: unknown) {
  const role: Role = session.role; // set at login by your code, never by the model
  if (!canCall(role, name)) {
    return { error: "permission_denied", reason: `${role} may not call ${name}` };
  }
  return implementations[name](input); // the real function, with precondition checks inside
}

Three things to notice. The role comes from the session your code established at login, so the model cannot claim to be an admin. Unknown tools are denied, so a typo cannot open a door. And a denial goes back as a normal tool result, so the model can recover.

Why not write "never issue refunds without approval" in the prompt and stop? Because a prompt is a request, not a lock. The model follows it most of the time, and "most of the time" is the gulf of generalization. L7 shows Sam talking the model out of its instructions with a prompt injection. Text cannot talk canCall out of anything.

8. Putting it together

The order matters: spec, then tools, then loop, then permission layer.

1. Spec: purpose, scope, roles, contracts, tiers, escalation, tone, non-goals.
2. Tools: one schema per tool, matching the contract's inputs; one implementation per tool, checking preconditions and returning named errors.
3. Loop: the harness from section 6, with a system prompt generated from the spec.
4. Permission layer: canCall inside runTool, roles from the session, T2 routed to a human.

Before you move on, check your agent against this list:

• Every tool has a contract with inputs, outputs, preconditions, and errors.
• Every tool has a tier, and every T2 tool is blocked for non-approver roles in canCall.
• The role comes from the session, not from the conversation.
• Every escalation trigger in the spec is something the model can act on.
• The spec has an owner and a version, because it will change.

Summary

• A spec is the written contract between you, the model, and the evals. If it is not written down, it cannot be tested.
• SPEC.md has eight parts: purpose, scope, roles, tool contracts, risk tiers, escalation rules, tone and constraints, non-goals.
• A tool contract names inputs, outputs, preconditions, postconditions, and errors. The error cases matter most.
• The Three Gulfs (comprehension, specification, generalization) map to Analyze, Measure, and Improve.
• The model may ask for any tool, but canCall in your code decides, and T2 tools never run without a human.