VereskLearn

Module 6 · Tools and agents

Lesson 6.2

The tool-calling loop

The loop sends the messages, runs each tool the model asks for, and stops at a text answer.

Lesson 39 of 622 min read

The problem

Why it matters

Without it

One request gives one reply. The model cannot ask for data and then use the data it gets back.

With it

Each tool result is added to the messages and sent again. The loop ends at a text reply or at a turn cap.

How it works

  • The model returns one of two replies

    A reply is either a tool request or final text. The Reply type holds both shapes, and its type field says which one arrived. The loop reads that field first.

    typeFieldsWhat the loop does
    tool_callname, orderIdRuns the tool, then sends the result back
    texttextReturns the answer and stops
    The two reply shapes the loop handles.

  • The loop looks up the tool by name

    The tools map links each name to a function. The loop picks the function with the name from the reply, then passes the inputs. Here get_order runs with orderId A-1042.

    1. Reply
    2. Find by name
    3. Run with inputs
    4. Result text
    One tool call, from the reply to the result text.
    const tools: Record<string, (id: string) => string> = {  get_order: (id) => "Order " + id + " shipped.",};const reply = { name: "get_order", orderId: "A-1042" };console.log(tools[reply.name](reply.orderId));

    Output

    Order A-1042 shipped.

  • The result joins the messages

    The messages list is what the model reads on each turn. The tool result is added to that list, so the next request contains it. Without this step, the model cannot use the data.

    • User: Where is order A-1042?
    • Tool: Order A-1042 shipped.
    The message list after the tool runs.
    const messages: string[] = ["User: Where is order A-1042?"];const result = "Order A-1042 shipped.";messages.push("Tool: " + result);console.log("Messages now: " + messages.length);

    Output

    Messages now: 2

  • The turn cap stops a loop that never ends

    A turn is one request to the model and its reply. The maxTurns value of five stops a model that keeps asking for tools. This sample ends on turn 2, well under the cap.

    Turns used against the cap of five.

Full code

Read the program

See the full code

Common mistakes

What goes wrong

  • No turn cap. A model that keeps asking for tools would run forever.
  • Dropping tool results from the messages. The model then cannot use them on the next turn.
  • Trusting a tool name without a lookup. An unknown name must return an error message.

Use it when and skip it when

Is it the right tool?

Use it when

  • The answer needs live data, such as a status or a record.
  • The model must chain steps, such as find an id and then look it up.

Skip it when

  • The task is one fixed step that your code can do without a model.
  • The answer is already in the sources sent with the question.

Words to know

Terms in this lesson

Loop
Code that repeats steps until a stop condition is met.
Turn
One request to the model and its reply.
Turn cap
The maximum number of turns, which stops a loop that never ends.
Message
One entry in the list sent to the model, such as a question or a tool result.
Full code