Lesson 2: How Tool Calling Turns a Chat Model into an Agent

Summary

This Buttercup lesson explains the basic protocol that turns a chat model into an agent: the model requests a permitted tool using a structured block, the host program runs the ordinary function, returns a matching tool result, and asks the model to continue. The lesson presents this as a four-station loop consisting of the conversation and tool definitions, the model response, the host-side function call, and the returned result. It emphasizes that the model itself never executes code, and that the conversation array is the state; no separate memory or planning module is required for the basic pattern. Examples in JavaScript and Python use Anthropic's SDK to define a `get_weather` function, describe it with JSON Schema, preserve the complete assistant response, execute every requested tool, and stop when the model no longer requests a tool. The lesson explains that arguments should be parsed as JSON, descriptions act as prompts, and every `tool_use` must receive a result with the exact matching ID. It also covers multiple calls in one assistant turn, returning failures as `is_error` results, and capping the number of turns. Because the full conversation is resent on every request, long tool outputs can dominate input-token costs; the lesson recommends returning only needed data and using prompt caching where appropriate. It then compares a hand-written loop with Anthropic's tool runners and other SDK abstractions, noting that runners reduce boilerplate but make custom approval gates, logging, retries, and turn counters dependent on hooks. A browser exercise lets learners observe file-writing and file-reading calls in a virtual filesystem, deliberately disable tools, and trigger protocol errors safely.