The tool loop in a route

This is the same pattern as the Tool Calling lab. inputSchema uses Zod directly — the SDK validates arguments before execute runs. If the model invents a field, you never hit your function with garbage (or you fail closed — better than a wrong city in production).

stopWhen: stepCountIs(5) allows up to five model steps (tool rounds plus the final answer). Tune n to the task: weather-and-compare might need three; a research agent might need more, with a higher bill.

toUIMessageStreamResponse() is the same last line as streaming chat. Tool calls show up as parts on the assistant message. The client does not need a second API.

The model, in a datacenter, emits a tool name and JSON arguments. Your Route Handler, on Vercel, runs execute. The browser never runs the tool. That split is the same as the chat key: side effects belong on the server.

Weather in this snippet is fake data so the lesson does not need a third-party key. In a product, execute hits your API, your database, or a vendor. Same shape. Real consequences.

Too few steps and the task stops mid-way (one city, no comparison). Too many and a stuck model burns tokens. Start small, log steps, raise n when you see real multi-call tasks.

Use generateText with tools when you are debugging — you get the full step list in one object. Use streamText for the chat UI.

When the same agent must run from a route, a cron, and a job, look at ToolLoopAgent in the official agents docs. For this lesson, one Route Handler is the right size.

The official Building Agents guide covers ToolLoopAgent when you want a shared agent object across routes and jobs. The catalog Tool Calling lab is this route with a UI.