Skip to main content
>_ supraj.dev

Module 2: Core Agent Loop · 3.5h

01 · UNDERSTAND

Day 12 Theory — Unassisted Gate 1: Agent Loop from a Blank File

Why this day is intentionally different

Today is not about adding another framework or feature. It tests whether the mental model from Days 01–11 is actually yours.

Following a tutorial can create the feeling of understanding. Building from a blank file reveals whether you can reconstruct the architecture without copying its shape.

What you should be able to reconstruct

A working agent loop requires several ideas to come together:

validated input
   ↓
controlled state
   ↓
model decision
   ↓
final? ── yes -> response
   │
   no
   ↓
validate tool request
   ↓
authorize + execute
   ↓
append observation
   ↓
termination check
   └──────────────> next model turn

If you forget one boundary, ask what failure it was protecting against.

The architecture reasoning we are assessing

You should be able to explain:

  • why model output is validated,
  • why the runtime executes tools rather than the model,
  • why tool results are appended to state,
  • why a step budget exists,
  • why timeouts and retries are not the same thing,
  • why side effects need idempotency thinking,
  • how fake providers make the loop deterministic in tests.

The goal is not memorizing function names.

Debugging from first principles

When your implementation fails, identify which contract is broken.

Ask:

  1. Did the model receive the expected state?
  2. Did it return a final answer or tool request?
  3. Did the tool arguments pass validation?
  4. Did the runtime dispatch the correct tool?
  5. Did the tool result get appended with the correct role/type?
  6. Did the loop terminate for the intended reason?

This is much more effective than randomly editing code until tests become green.

What passing means

Passing the gate means you can produce a small, understandable implementation whose behavior is supported by tests.

It does not mean using the most abstraction, shortest code, or most clever Python.

A simpler implementation you can explain is stronger evidence than framework code you cannot reason about.

Service Desk connection

The Service Desk has reached its first architecture checkpoint. Before we add retrieval and more advanced state, we prove that the underlying agent runtime is understood.

The principle is:

You do not truly own an abstraction until you can rebuild the essential mechanism, explain its boundaries, and debug it when the happy path is removed.

02 · APPLY

Lesson Overview

This is the applied companion for Day 12. Read DAY_12_THEORY.md first for the beginner-first teaching of UNASSISTED GATE 1: Agent Loop from a Blank File. Then use the real service-desk-day-12/ project to trace, run, debug, and explain the concept.

Service Desk Alignment

Day 12 adds UNASSISTED GATE 1: Agent Loop from a Blank File to the running Service Desk. Start with the day project, then follow imports and tests to identify the actual runtime path.

Why This Topic Matters

The theory chapter explains why UNASSISTED GATE 1: Agent Loop from a Blank File is needed. Here the goal is evidence: identify where the capability is implemented, what observable behavior changes, and how the repository proves both success and failure behavior.

System Architecture

The implementation boundary for UNASSISTED GATE 1: Agent Loop from a Blank File is the service-desk-day-12/ project. Use its README and tests as the executable architecture map.

Repository Implementation Map

Use the real Day 12 repository, not a fabricated sample, to connect theory to implementation.

Theory concepts to locate:

  • Why this day is intentionally different
  • What you should be able to reconstruct
  • The architecture reasoning we are assessing
  • Debugging from first principles

Most relevant implementation modules first:

  • Follow the project README.

Follow imports/calls from the relevant module and confirm behavior in tests. Record input → mechanism → observable output/state → failure evidence.

Code Walkthrough & Mechanics

Read the project README with these theory sections beside you:

  • Why this day is intentionally different — locate its implementation and evidence.
  • What you should be able to reconstruct — locate its implementation and evidence.
  • The architecture reasoning we are assessing — locate its implementation and evidence.
  • Debugging from first principles — locate its implementation and evidence.
  • What passing means — locate its implementation and evidence.

For each concept identify the real function/class/protocol boundary, its input/state, its observable result, and the assertion in tests/test_gate_1_grading.py that proves the behavior. If a concept has no implementation or evidence, record that as a gap rather than inventing one.

Common Mistakes & Debugging Guidance

Use the theory—not generic timeout or .env advice—to decide what can fail today.

Failure lens: revisit Debugging from first principles, What passing means.

  • Reproduce the smallest case that violates one of those expectations.
  • Trace the real Day 12 modules until you find the first incorrect state/output/decision.
  • Use tests/test_gate_1_grading.py as executable evidence.
  • Add a regression test if the failure is not already represented.
  • Fix the smallest responsible boundary and rerun the relevant test before the full suite.

Your debugging explanation must name the topic-specific invariant that failed, not merely say “an exception occurred.”

Practical Lab Instructions

  1. Summarize these theory ideas before opening the implementation:
    • Why this day is intentionally different
    • What you should be able to reconstruct
    • The architecture reasoning we are assessing
    • Debugging from first principles
  2. Inspect the most relevant real Day 12 modules first:
    • Follow README.md.
  3. Inspect the automated evidence:
    • tests/test_gate_1_grading.py
  4. Establish the baseline:
    cd service-desk-day-12
PYTHONPATH=. pytest tests/test_gate_1_grading.py -q
  5. Trace one theory concept through the actual nested modules and tests.
  6. Run one success case and record input → mechanism → observable result.
  7. Exercise one topic-specific failure/boundary case and name the invariant that protects the system.
  8. Re-run the relevant tests and explain theory → implementation → evidence.

Done when: another student can reproduce your trace without relying on an invented sample.

Key Takeaways

  1. Be able to explain Why this day is intentionally different and point to its implementation/evidence in Day 12.
  2. Be able to explain What you should be able to reconstruct and point to its implementation/evidence in Day 12.
  3. Be able to explain The architecture reasoning we are assessing and point to its implementation/evidence in Day 12.

Knowledge Check & Scenario Questions

  1. Concept: Using Why this day is intentionally different, explain the engineering problem Day 12 is solving without naming a framework as the answer.
  2. Mechanism: How does What you should be able to reconstruct appear in the real project? Start from the project entry point and name the observable state/output/event that changes.
  3. Failure: For The architecture reasoning we are assessing, describe one incorrect implementation or boundary condition and the evidence you would expect in tests/test_gate_1_grading.py.
  4. Design review: Which assumption in today's design would you verify before reusing this implementation in a different production system?

Official References

03 · EXPLAIN

Interview checkpoint

Explain one design decision from this lesson, the alternative you rejected, and the failure mode or evidence that justified your choice.