VereskLearn

Module 6 · Tools and agents

Lesson 6.6

Frameworks or a hand-written loop

A framework runs the tool loop for you, and a hand-written loop shows every step and default.

Lesson 43 of 622 min read

The problem

Why it matters

Without it

A framework hides the loop. Defaults such as the turn cap are set for you, and you may never see them.

With it

A hand-written loop is short and visible. Each stop condition is in your code, so you can test it.

How it works

  • The loop has a turn cap

    A fake model asks for a tool on every turn before turn 10, and it answers on turn 10. The loop must stop somewhere, so it checks a cap first. The first five turns all ask for a tool.

    function fakeModelTurn(turn: number): "tool" | "text" {  return turn < 10 ? "tool" : "text";}for (let turn = 1; turn <= 5; turn++) {  console.log(turn + ": " + fakeModelTurn(turn));}

    Output

    1: tool
2: tool
3: tool
4: tool
5: tool

  • A cap of five stops early

    With a cap of five, the loop stops after turn 5, before the model answers. It returns no answer, so the caller must treat the run as a failure. The model needed 10 turns in total.

    Turns used before the loop stops, for each cap.

  • The result records the stop reason

    LoopResult holds the answer, the turn count, and the stop reason. The caller reads the reason instead of guessing why the loop ended. A cap of twelve lets the model answer on turn 10.

    CapAnswerTurnsStop reason
    5null5turn cap reached
    12done10answer
    Both runs, as the loop reports them.

  • A framework runs this loop for you

    A framework runs the same loop with its own defaults, such as the turn cap. Read those defaults before you rely on them in production. A hand-written loop shows every default in one file.

    Hand-written loop

    • Every stop condition is in your code
    • Easy to test each rule

    Framework

    • Less code to write
    • Defaults set for you, so read them first
    The trade-off between a framework and a hand-written loop.

Full code

Read the program

See the full code

Common mistakes

What goes wrong

  • Trusting a framework default. Read the defaults for turn caps and parallel calls before production use.
  • Reporting a capped run as a normal answer. A capped run is a failure, not a reply.
  • Starting with a framework. Without the loop in view, debugging takes longer.

Use it when and skip it when

Is it the right tool?

Use it when

  • You want full control of each step and each stop condition.
  • The same loop serves more than one feature.

Skip it when

  • The task is one request and one reply, so no loop is needed.

Words to know

Terms in this lesson

Framework
A library that runs common parts of a system for you.
Default
The value used when you do not set one.
Stop reason
The recorded cause of a loop ending, such as answered or turn cap reached.
Parallel tool call
Two or more tools run at the same time for one reply.
Full code