The Tool Loop That Turns a Chatbot Into an Agent

A tool loop is the difference between a demo chatbot and an agent that can read files, run commands, or modify a codebase. Getting the control flow right — serial execution, parameter validation on untrusted model input, and safe cancellation — prevents the agent from executing garbage arguments or leaving the conversation in an unrecoverable state.

An LLM cannot execute tools itself; it only returns a structured intent. The agent must find the local function, validate the model's untrusted parameters, run it, and construct a tool_result message for the next model request. This creates a loop where the model proposes an action, the agent executes it, and the model observes the outcome before responding.

The implementation separates concerns cleanly: a ToolDefinition (name, description, parameters) is sent to the provider, while the AgentTool adds a local execute() function the provider never sees. Every tool call goes through a strict sequence: emit a start event, check for cancellation, look up the tool by name, validate arguments against the schema, catch execution errors, and unify everything into a ToolResultMessage.

Cancellation is handled at multiple checkpoints. An AbortSignal is checked before execution, after execution, and between serial tool calls in a batch. If cancelled mid-loop, the agent appends a locally-constructed aborted assistant message so the prompt settles cleanly rather than leaving the conversation in a broken state.