Part 1 · Agent architectures — a map of the terrain

Level: ⭐⭐ · Time: ~5 h · Requires: course 1, part 6 (the agent loop) Produces: a diagnosis of your loop from course 1, an architectural decision in writing, the $OSA/ directory

---

0. What changes between course 1 and course 2

In course 1 you built a loop. It reads a file, writes a file, runs a command, remembers a dozen or so turns, and runs inside bwrap. That is a real agent and it is not a toy.

But try to make it do what you announced: several agents that work for weeks, wake up on their own and cooperate. It will break in five places, and not because it is badly written:

Course 2 does not teach a better loop. It teaches a system in which the loop is one of eight elements — and not the hardest one.

⭐ One sentence that sums up the whole course. The loop is 10% of the work. Sessions, memory, scheduling, the sandbox, observability and evaluation are the other 90% — and they decide whether an agent is a tool or a curiosity.

---

1. Before you build an agent — four questions that save a month

In Building Effective AI Agents Anthropic gives four criteria. I am rewriting them, because three of the four answers sound different for you than for a company with a cloud.

1 · Complexity. Is the task multi-step and hard to describe fully up front?

• "Extract the title from this PDF" → this is not a task for an agent. It is a single call with a grammar. An agent will add 30× the cost and introduce uncertainty where there was none.
• "Go through my documents from the last quarter and tell me what I forgot about" → this is a task for an agent. You do not know up front how many files need to be read or what to look for.

2 · Value. Does the result justify the cost and the latency?

For you, "cost" means something different than for others. You do not pay per token. You pay in card time and electricity — and that is a real budget, but a completely differently shaped one. An agent that grinds for 40 minutes at night costs you pennies. The same agent in the cloud would cost a dozen or so dollars. This moves the profitability line very strongly in your favour and is the main reason it is worth building locally.

3 · Feasibility. Can the model do it at all?

Here you have a harder constraint than someone on a frontier model. gpt-oss-20b will call a tool correctly in over 90% of simple cases, but end-to-end on a multi-step task the published numbers drop to 80–90% (LLM Configurator), because tool-selection errors and argument errors multiply across the number of steps.

Work it out on a napkin. At 92% success per step:

 3 steps  →  0.92³  =  78 %
 8 steps  →  0.92⁸  =  51 %
15 steps  →  0.92¹⁵ =  29 %

⭐ This is the most important arithmetic in the whole course. You will not fix it with a better prompt. You fix it by shortening the chain (part 8, code-mode), verifying along the way (part 14) and recovering from errors (part 3). All three are work on the system, not on the model.

4 · Cost of error. Can an error be detected and undone?

This question decides what the agent is allowed to do, and it returns in parts 10, 12 and 16. Remember the rule: if you cannot detect that the agent made a mistake, do not give it that tool.

---

2. The spectrum: from workflow to agent

The market calls everything an "agent". The distinction that matters from an engineering standpoint is one: who decides the next step — your code or the model?

  YOUR CODE DECIDES                              THE MODEL DECIDES
  ├───────────────┼──────────────┼──────────────┼───────────────┤
  1 call          chain          router         loop            fleet
                  (chain)        (routing)      (agent)         (multi-agent)

  predictable     predictable    semi-pred.     unpredictable   unpredictable²
  1 call          N calls        1-2 calls      ? calls         ?? calls
  known cost      known cost     known cost     unknown cost    unknown cost
  easy tests      easy tests     easy tests     hard tests      very hard

The rule I keep throughout the course: move right only when the left side has proven it is not enough. Every step to the right buys flexibility at the price of predictability — and predictability is what lets you sleep.

💡 In practice. In the system you will build, most of the work will be done by workflows, not agents. A Steward checking the calendar is a workflow. A Steward that noticed a conflict and is looking for how to resolve it is an agent. The same "agentic application" contains both layers and that is healthy — not a shortcoming.

---

3. Four ways to build an agent

It is worth knowing all four, because they get confused with one another even by the people who build them. One question separates them: who supplies the harness, and who supplies the deployment?

For you 3 and 4 are out, and not for ideological reasons:

• 3 is out by definition — a managed agent means someone else's process, someone else's state and someone else's availability. The whole thesis of your project is the opposite.
• 4 is out as a goal, but not as a point of reference. The Claude Agent SDK is superbly designed and in parts 3, 7 and 13 I compare your solutions with it.

What remains is 1 with elements of 2: you write the loop yourself, but you do not reject libraries where they hide nothing. That is exactly what we established as the course's rule.

---

4. Topologies — how agents arrange themselves relative to one another

Four layouts. Each has a place where it dies.

4.1 · Hub-and-spoke (star) — one gateway, many channels and tools

        channels                GATEWAY                tools
    CLI  ─────┐            ┌──────────────┐        ┌──── files
    HTTP ─────┼───────────►│   sessions   │◄───────┼──── shell
    Signal ───┤            │   routing    │        ├──── network
    cron ─────┘            │   policies   │        └──── memory
                           └──────┬───────┘
                                  │
                           ┌──────▼───────┐
                           │  RUNTIME     │  ← the agent loop
                           └──────────────┘

This is how OpenClaw is built and this is how you will build your system. Advantages: one place for the security policy, one for session state, one to observe. Drawback: the gateway is a single point of failure — which is why in part 18 you learn to restart it without losing state.

4.2 · A graph with typed state

The nodes are functions or agents, the edges are transitions, and the state is explicit and typed. This is how LangGraph works. Great when the flow is known up front and must be auditable. Weak when you do not know the shape of the task — and in a personal agent you usually do not.

4.3 · Hierarchy (supervisor and executors)

The supervisor breaks the task down, the executors carry it out in a clean context and return a summary of 1–2k tokens. This is the subagent pattern from Anthropic. It works great for parallel searching. It costs a fixed delegation fee (pitfall P41 from course 1) and therefore loses on short tasks.

4.4 · Swarm / bulletin board

Agents write to and read from a shared board, with no central supervisor. Elegant and almost always a bad choice to start with: unpredictable, hard to debug, and maximally prone to cascading failure.

⚠️ A number that should intimidate you. According to OWASP, one compromised server in 72.4% of cases dragged further ones into acting (Teleport). A topology in which everyone talks to everyone is a topology in which a single mistake becomes everyone's mistake. We return to this in parts 13 and 16.

---

5. OpenClaw taken apart

You asked me to check it — and rightly so, because it is the best-documented working system of its class. We are not copying it. We take it apart to see which decisions have to be made, and some of them we will make differently.

5.1 · Four blocks

5.2 · Six phases of handling a message

This is the skeleton you will implement in part 2. It is worth knowing the times, because they show where the time really goes (figures from the OpenClaw description, to be verified on your own):

1. Intake                 the channel adapter receives the message
2. Access control         allowlist, pairing, session type           < 10 ms
3. Context assembly       working files + history + memory           < 100 ms
4. Model call             streaming from the provider           200–500 ms to the 1st token
5. Tool execution         shell, files, browser                 100 ms – 3 s
6. Delivery               formatting, splitting, saving state

⭐ Note the proportions. Security costs under 10 ms. Context assembly under 100 ms. Everything else is the model and the tools. This means that you have no excuse to economise on access control — it is free compared with what you are doing anyway.

5.3 · Session resolution — an idea I am stealing whole

OpenClaw maps a message to a session with an explicitly named trust level:

message from the console       →  main                          (host, full permissions)
private from a channel         →  agent:main:<channel>:dm:<id>     (sandbox)
from a group                   →  agent:main:<channel>:group:<id>  (sandbox, narrower)

This is the best single decision in this architecture. The trust level is not a flag stuck onto a tool — it is a property of the session, following from where the message came from. You cannot forget about it, because without a session there is no call. You implement this in part 2, you enforce it in part 10.

5.4 · Working files as the program

AGENTS.md     core instructions         ← what the agent is to do
SOUL.md       personality and tone      ← how it is to do it, grows over time
MEMORY.md     what it knows about you   ← auditable, you open it and read it
HEARTBEAT.md  a list of things to watch ← cron expressed in plain language
SKILL.md      a single capability       ← loaded on demand when needed

⭐ Why this is brilliant, not primitive. The agent's behaviour is a text file that you open, read, version in git and roll back. The alternative — fine-tuning the model — gives the same behaviour in a form that cannot be read, shown to anyone or rolled back. For an agent touching your affairs this is not an aesthetic choice.

5.5 · What OpenClaw teaches by counterexample

I am not idealising it. Three documented problems (plus a fourth incident), each of which is material for part 16:

---

6. Loop engineering — a counterpoint you have to know

Peter Steinberger, the author of OpenClaw, wrote in June 2026:

"Here's your monthly reminder that you shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents."

This is the most important sentence about agents that I found in the whole research, and it is worth unpacking, because it sounds like a slogan and is not one.

Prompting = you optimise a single input to the model. You improve the wording, add examples, ask it to "take your time". Loop engineering = you optimise the machine that generates the inputs. What the agent gets at the start of every turn. When it stops. What it sees after an error. How it hands the work to the next session. Who checks the result.

The difference is like that between writing one good SQL query and designing a database schema. The first scales linearly with your time. The second scales by itself.

6.1 · The rest of Steinberger's theses — and where I disagree with him

🎯 How to use this. Steinberger is right in his context: an experienced engineer, a frontier model, programming tasks, full trust in the machine. Three of those four conditions do not hold for you. That is why throughout the course I put his theses next to a measurement and make you settle it yourself. The ability to settle it is worth more than choosing a side.

---

7. A finding that changes priorities

From research on agent benchmarks (Prefactor):

An agent's result changes more with the harness than with the model. The same model under two different scaffolds gives significantly different numbers. The harness decides how tools are exposed, how errors are shown and how many attempts the agent gets.

Read that again, because it has a financial consequence. The variable over which you have full control — the harness — is more important than the variable over which you have zero control — the model weights. The time spent choosing a model is largely wasted as long as the harness is weak.

⭐ This is the justification for this course existing and the reason it has no part on fine-tuning models.

---

8. FROM SCRATCH — an architectural decision in writing

Before you write a line of code, write an ADR (Architecture Decision Record). It is one page that in six months will answer the question "why is this done this way".

mkdir -p $OSA/decyzje
cd $OSA

cat > $OSA/decyzje/0001-topologia.md <<'EOF'
# ADR 0001 · System topology

- **Date:** <today>
- **Status:** accepted
- **Context:** I am building a system for 3+ personal agents working for weeks
  on my own hardware, some of which reach out to the network.

## Decision

Hub-and-spoke with a single gateway on the loopback.

## Why not otherwise

- **A graph with typed state** — rejected, because I do not know the shape of the tasks up front.
- **Swarm / bulletin board** — rejected, because of cascading failure (72.4% per OWASP) and no
  single place for policy.
- **Hierarchy** — not as the system's topology, only as a pattern inside
  a single task (subagents, part 13).

## Consequences

- (+) one place for the security policy, sessions and observability
- (+) every conversation can be replayed from a single log
- (−) the gateway is a single point of failure → needs a restart without losing state (part 18)
- (−) everything passes through a single process → a throughput limit (I measure it in part 13)

## How I will know this was a bad decision

When the gateway becomes a bottleneck with >3 parallel sessions — then the
runtime moves out into a separate process and the gateway stays.
EOF

💡 The last section is the most important and almost nobody writes it. "How I will know this was a bad decision" turns an opinion into a hypothesis with a falsification condition. Without it an ADR is just a nicely formatted prejudice.

---

9. IN PRODUCTION — what the frameworks do that you do not

To know what you are rejecting, you have to know what you are getting.

The two starred rows are the reason you build it yourself. No framework treats scheduling as a first-class layer, and all of them treat a local model as an adapter bolted on from the side. For you it is the core, not a plugin.

⚠️ Honestly: when a framework beats you. When you need a flow that is to be auditable and approved by someone from outside — a graph with typed state is better than your loop, because it can be drawn and shown. Remember this for the moment when your product meets a compliance requirement.

---

10. EXPERIMENT 1 — where your loop from course 1 breaks

Hypothesis: the loop from $AGENT/agent.py copes with tasks of up to ~5 steps, and above ~10 steps it fails not because of model quality, but because of the lack of system layers.

Procedure. Prepare five tasks of increasing chain length and run each three times (because what interests you is repeatability, not a one-off success):

cd ~/Desktop/github_repos/llm-education   # the repository directory (yours may differ)
source rig-env.sh
mkdir -p $OSA/pomiary

For every run, note:

task    | attempt | success | steps | tokens | time | failure mode
--------|---------|---------|-------|--------|------|-------------
Z1      | 1       | yes     | 2     |  1,840 | 4 s  | —
...

Name the failure modes from this list — it will be your map for the rest of the course:

What I expect (⚠️ to be checked on your own, this is a prediction, not a measurement):

Z1  ███████████████████████  100 %
Z2  ████████████████████     ~90 %
Z3  ██████████████           ~65 %     ← NARZĘDZIE starts here
Z4  ███████                  ~35 %     ← CICHY and BŁĄD come in here
Z5  ██                       ~10 %     ← KONTEKST and STAN dominate here

Keep this file. In part 19 you will repeat exactly the same experiment on the finished system and this comparison is the grade for the whole course.

---

11. EXERCISE — setting up the system

mkdir -p $OSA/{decyzje,pomiary,dziennik,konfiguracja,agenci,narzedzia,pamiec,testy}
cd $OSA && git init && git add -A && git commit -m "part 1: directory skeleton"

$OSA/
├── decyzje/        ADRs — why it is this way and not another
├── pomiary/        experiment results, one file per part
├── dziennik/       session logs (part 2)
├── konfiguracja/   configuration as data (part 2)
├── agenci/         Archivist, Researcher, Steward — working files (part 6)
├── narzedzia/      tool registry (part 7)
├── pamiec/         bi-temporal store (part 5)
└── testy/          golden set and the evaluation harness (part 14)

⭐ git init is not decoration. In part 3 git becomes the agent's memory mechanism — the way a new session learns what the previous one did. Start committing from today.

Homework: write decyzje/0002-modele.md. Which model will be the default for the loop, which for hard tasks, and how you will know you chose wrong. Without this you will not build the router in part 17, because you will have no criterion.

---

12. Pitfalls of this part

---

13. Checkpoint — what you have after this part

# Should pass in full:
test -d $OSA/decyzje            && echo "✓ directories"
test -f $OSA/decyzje/0001-topologia.md && echo "✓ ADR 0001"
test -f $OSA/decyzje/0002-modele.md    && echo "✓ ADR 0002"
test -f $OSA/pomiary/01-gdzie-peka.md  && echo "✓ baseline measurement"
git -C $OSA log --oneline | head -3

• You know when not to build an agent
• You can calculate why a 15-step chain at 92%/step gives 29%
• You know the four topologies and which one dies and how
• You have taken OpenClaw apart into Gateway / Runtime / Tools / Memory
• You understand the difference between prompting and designing a loop
• You have measured where your current loop breaks — that is the map for the rest of the course

---

Next: 02-SKELETON-SESSIONS-CONFIG.md — you build the gateway, configuration as data and an event log from which you will replay any conversation down to the bit.