Skip to main content
>_ supraj.dev

Module 2: Core Agent Loop · 4.25h

01 · UNDERSTAND

Day 10 Theory — Build the Agent Loop from Scratch

What makes an agent different from one tool call

Yesterday the model could request a tool. Today we allow the system to repeat that process until the task is complete.

That repeated decision-execution-observation cycle is the core of an agent.

A minimal loop looks like:

context
  ↓
model decides
  ├─ final answer -> stop
  └─ tool call
        ↓
      execute
        ↓
   append result
        └────────> model decides again

Frameworks can hide this loop. We build it ourselves first so later abstractions are understandable rather than magical.

The agent state

The model must see enough history to understand what has happened.

That state commonly contains:

  • original user request,
  • assistant/model messages,
  • tool requests,
  • tool results,
  • control metadata such as step count.

Do not confuse this application state with the model's internal hidden state. The model API receives context we explicitly send on each turn.

A single iteration

One agent iteration has a small number of responsibilities:

  1. Construct the model input from current state.
  2. Call the model.
  3. Inspect whether it returned a final response or tool request.
  4. Validate a requested tool.
  5. Execute it through the runtime.
  6. Append the result to state.
  7. Repeat if needed.

Keeping these stages explicit makes the loop testable.

Termination is a product requirement

An agent must have clear stopping conditions.

Possible termination conditions include:

  • model returns a final response,
  • step budget reached,
  • deadline exceeded,
  • unrecoverable tool error,
  • policy denies further action,
  • human input is required.

Never rely only on “the model will know when to stop.”

Step budgets protect the system

A model can repeatedly call the same tool, alternate between tools, or keep requesting actions that do not make progress.

A maximum turn or step budget bounds:

  • latency,
  • provider cost,
  • tool side effects,
  • runaway loops.

The correct limit is application-specific. The important part is that the limit exists and the exhausted state is handled intentionally.

Progress versus repetition

A sophisticated loop can track whether new information is being produced.

For example, repeated identical tool calls with identical arguments and results may indicate the agent is stuck.

A deterministic runtime can detect this pattern even if the model cannot.

Why tool results go back into context

The model requested a tool because it needed information or an action result. After execution, the result becomes an observation that should inform the next model decision.

If the runtime executes a tool but fails to append the result correctly, the model may request the same action again because from its point of view nothing changed.

Side effects require extra care

A read-only loop is easier to retry than a loop that performs writes.

If an agent creates a ticket and the following model call fails, restarting the whole loop may create a duplicate unless the side effect is idempotent or recorded in durable state.

This is why agent engineering quickly becomes distributed-systems engineering.

Testing an agent loop

Do not test the loop only with a real model.

A fake model can deterministically return:

turn 1 -> call search_kb
turn 2 -> call get_ticket
turn 3 -> final answer

Then the test can assert exact runtime behavior: which tool was called, with what arguments, how state was updated, and when the loop stopped.

Service Desk connection

Today the Service Desk becomes an actual agent runtime. It can reason over observations and choose multiple controlled steps.

The core principle is:

An agent is not “an LLM with autonomy.” It is a software-controlled loop that repeatedly gives a model context, executes validated actions, records observations, and enforces termination.

02 · APPLY

Lesson Overview

This is the applied companion for Day 10. Read DAY_10_THEORY.md first for the beginner-first teaching of Build the Agent Loop from Scratch. Then use the real service-desk-day-10/ project to trace, run, debug, and explain the concept.

Service Desk Alignment

Day 10 adds Build the Agent Loop from Scratch to the running Service Desk. Start with agent.py, registry.py, mock_model.py, models.py, then follow imports and tests to identify the actual runtime path.

Why This Topic Matters

The theory chapter explains why Build the Agent Loop from Scratch 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

This is a repository surface map, not a claim that modules call each other in the displayed order. The modules are ranked by relevance to today's theory.

graph LR
    T[Day 10: Build the Agent Loop from Scratch]
    T --> M1[agent.py]
    T --> M2[registry.py]
    T --> M3[mock_model.py]
    T --> M4[models.py]

Follow imports and tests to discover the actual runtime flow.

Repository Implementation Map

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

Theory concepts to locate:

  • What makes an agent different from one tool call
  • The agent state
  • A single iteration
  • Termination is a product requirement

Most relevant implementation modules first:

  • service_desk/agent.py
  • service_desk/registry.py
  • service_desk/mock_model.py
  • service_desk/models.py

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

Code Walkthrough & Mechanics

Read agent.py, registry.py, mock_model.py, models.py with these theory sections beside you:

  • What makes an agent different from one tool call — locate its implementation and evidence.
  • The agent state — locate its implementation and evidence.
  • A single iteration — locate its implementation and evidence.
  • Termination is a product requirement — locate its implementation and evidence.
  • Step budgets protect the system — 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_agent_loop.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 Termination is a product requirement, Step budgets protect the system.

  • Reproduce the smallest case that violates one of those expectations.
  • Trace the real Day 10 modules until you find the first incorrect state/output/decision.
  • Use tests/test_agent_loop.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:
    • What makes an agent different from one tool call
    • The agent state
    • A single iteration
    • Termination is a product requirement
  2. Inspect the most relevant real Day 10 modules first:
    • service_desk/agent.py
    • service_desk/registry.py
    • service_desk/mock_model.py
    • service_desk/models.py
  3. Inspect the automated evidence:
    • tests/test_agent_loop.py
  4. Establish the baseline:
    cd service-desk-day-10
PYTHONPATH=. pytest tests/test_agent_loop.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 What makes an agent different from one tool call and point to its implementation/evidence in Day 10.
  2. Be able to explain The agent state and point to its implementation/evidence in Day 10.
  3. Be able to explain A single iteration and point to its implementation/evidence in Day 10.

Knowledge Check & Scenario Questions

  1. Concept: Using What makes an agent different from one tool call, explain the engineering problem Day 10 is solving without naming a framework as the answer.
  2. Mechanism: How does The agent state appear in the real project? Start from service_desk/agent.py and name the observable state/output/event that changes.
  3. Failure: For A single iteration, describe one incorrect implementation or boundary condition and the evidence you would expect in tests/test_agent_loop.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.