The Vercel AI SDK · Chapter 4 of 21

Multi-step tool calls

By the end of this chapter Mali answers from real data: it calls a tool, reads the result, and writes the answer, in one call of yours. You will let a run take several steps with stopWhen, read each step, watch the model call two tools at once and chain one tool after another, put a limit on the steps, change what a step may do with prepareStep, and wrap it all in a ToolLoopAgent. You will build Mali's multi-step answer, print a trail of its steps, make a step limit safe for customers, and count what two kinds of message cost. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The SDK on the server
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.

Why you need this

Chapter 3 ended with a cliffhanger. Mali called the right tool, the tool returned the right data, and the text was empty:

"" tool-calls

Deepa cannot send an empty bubble to a customer, and Farhan does not want to write the loop that sends the result back by hand for every question. Some questions need more than one tool, too. "Add the cheapest pet-safe plant for low light to my cart" needs a search first, then the cart, using what the search found. One request cannot do that: the model cannot pick the cheapest plant until it has seen the search results.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    steps.ts: as many steps as an answer needs

    Export an async function askMali(question) from steps.ts. It calls generateText with lab('lab-chat'), instructions MALI_INSTRUCTIONS, tools: maliTools() (all from ../../shared/mali.ts), the question as the prompt and stopWhen: isStepCount(5), and returns { answer: result.text, steps: the number of steps, tools: the toolName of every tool call of every step, in order }.

    Under if (import.meta.main), ask Is the Calathea in stock? and print the answer, then N steps: TOOL, TOOL. The Check asks questions of its own that take a tool and an answer, two tools at once, and a chain, and compares with its own run.

  2. Task 2

    trail.ts: a trail of the steps

    Call generateText with lab('lab-chat'), instructions MALI_INSTRUCTIONS, tools: maliTools(), stopWhen: isStepCount(5) and the given question (Where is my order HB-1044 and when can you deliver to my pincode?), with an onStepEnd(step) callback. For each step it prints step N: NAME INPUT_JSON for the step's tool calls (several joined with " + "), or step N: answer for a step with no tool calls; N counts from 1 (step.stepNumber counts from 0). After the run print answer: and result.text.

  3. Task 3

    limit.ts: a step limit, and no empty answers

    Export const FALLBACK (the line a customer sees when Mali could not finish) and an async function ask(question, maxSteps) from limit.ts. It calls generateText with lab('lab-chat'), instructions MALI_INSTRUCTIONS, tools: maliTools(), the question as the prompt and stopWhen: isStepCount(maxSteps), and returns { text: result.text, or FALLBACK when that is empty; steps: the number of steps; finishReason: result.finishReason }.

    Under if (import.meta.main), ask the given question with a limit of 2, then 5, and print limit N: STEPS steps, FINISH: TEXT. The Check cuts a chain short with a limit of 2 and wants FALLBACK, then lets it finish with 5 and wants Mali's answer.

  4. Task 4 · interview question

    Interview: agent.ts, Mali as an agent

    Export const mali = new ToolLoopAgent({ model: lab('lab-chat'), instructions: MALI_INSTRUCTIONS, tools: maliTools() }) from agent.ts, with no stopWhen (the default loops up to 20 steps).

    Under if (import.meta.main), run the two given messages with await mali.generate({ prompt }), in order, and print for each:

    MESSAGE: N steps, IN in, OUT out

    with N from result.steps and the tokens from result.usage (all steps together).

    Vikram will ask: the first message asks for two things and the second for one, so why does the second take more steps?

What you will learn

  • Steps: what a step is, and why the default is one.
  • stopWhen: isStepCount(n): let the SDK keep going until Mali answers.
  • result.steps and onStepEnd: what each step asked for and returned.
  • Parallel calls and chains: two tools in one step, or one after another.
  • Stop conditions: a step limit, hasToolCall, and what a cut-off run returns.
  • prepareStep: change the tools for a step with activeTools.
  • ToolLoopAgent: the model, the instructions and the tools, kept together.

More in The SDK on the server

Build "Multi-step tool calls" yourself

HariBhari, a Bengaluru plant shop, wants Mali, a plant helper on its website. You build it end to end, from the first call to a chat that streams cards, asks before it adds to the cart and stays within budget. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.