Agents and Tool Use
How a model calls functions through a loop of think, act, observe: tool schemas, argument validation, step limits and other guardrails, built offline with a fake llm and two tools.
advanced50 min#agents#tool-use#function-calling#guardrails#agent-loop
Prerequisites: Prompting and Structured Output, How LLMs Work: Tokens, Context, and Sampling
Why it matters
A language model on its own can only produce text. It cannot check today's weather, query your database, do exact arithmetic, or send an email. Tool use (also called function calling) closes that gap: you describe functions the model may request, your code runs them, and the results go back into the conversation. Chain several such steps with a loop and you get an agent: a system where the model decides what to do next until the task is finished. This is powerful and risky in equal measure, because the model's choices now have side effects.
Intuition
Picture a smart assistant locked in a room with a phone that only connects to you. They cannot do anything themselves; they write notes: "please look up the weather in Paris". You do it, slide the answer back under the door, and they write the next note: "now multiply that by 9". Eventually they hand you a final answer. You are the executor, and you decide which requests you will honour. That division of labour is the key safety property: the model proposes, your code disposes.
How it works
Tool definition. Each tool has a name, a description the model reads to decide when to use it, and a schema for its arguments (usually JSON Schema: parameter names, types, which are required, allowed values). Good descriptions matter as much as good code, because the description is the only documentation the model sees.
The loop.
- Send the conversation plus tool definitions to the model.
- The model replies with either a final answer or a tool call (a name and arguments).
- If it is a tool call, your code validates and executes it, producing an observation (a result or an error).
- Append the call and the observation to the conversation and go to step 1.
- Stop on a final answer, on a step limit, or on any guardrail trigger.
One pass through the loop, as messages between the parties:
user task
|
v
+--------> [ model ] --final--> answer
| | tool call(name, args)
| v
| [ validate + allowlist ] --reject--> error observation --+
| | ok |
| v |
| [ run tool ] -----------> observation ------------------+
+-----------------------------------------------------------------+
Guardrails. An agent that can act needs limits that do not depend on the model behaving:
- Allowlist: only registered tools can run; unknown names are rejected.
- Argument validation: check required fields, types, ranges, and allowed values before executing. Never pass model text into a shell or SQL string.
- Step and cost limits: a hard cap on iterations, tokens, and wall-clock time prevents infinite loops.
- Least privilege: give the tool credentials with the minimum permissions; prefer read-only tools; scope to the current user.
- Human approval for irreversible or costly actions such as payments, deletions, and external emails.
- Errors as observations: when a tool fails, return the error text to the model so it can adapt, but do not leak secrets in error messages.
- Treat tool output as untrusted input: a web page or email the tool returns may contain instructions aimed at the model (prompt injection). See the production lesson.
- Logging: record every call, argument, and result so you can audit and debug.
Every tool call has to pass through the same gates before anything runs.
Agent or plain workflow? If the steps are known in advance, write ordinary code (a fixed pipeline, possibly with model calls inside); it is cheaper, faster, and testable. Let the model choose the path only when the path really depends on intermediate results. Each loop iteration costs a model call and can compound errors.
| Operation | Time | Notes |
|---|---|---|
| Agent run with s steps | s model calls + s tool calls | Latency and cost scale with steps |
| Prompt size at step i | Grows with i | History accumulates; long runs need trimming or summaries |
| Argument validation | O(size of arguments) | Negligible; always do it |
| Step limit | Constant cap | Turns an infinite loop into a bounded failure |
Code: an agent loop with two tools
The function llm is a fake model that follows a script for four scenarios, so the program is deterministic and offline. In a real system you would replace llm with a model API call that receives the messages and the tool definitions and returns either text or a structured tool-call request; the registry, validation, guardrails, and loop below stay the same. Tool definitions here are simplified schemas.
import json
def fmt(x):
return str(int(x)) if isinstance(x, (int, float)) and x == int(x) else str(x)
def show(obj):
if isinstance(obj, dict):
return ",".join(f"{k}={show(v)}" for k, v in obj.items())
return fmt(obj)
def get_weather(city):
temps = {"Paris": 20, "Oslo": 3}
if city not in temps:
return {"error": "unknown city: " + city}
return {"celsius": temps[city]}
def calculator(op, a, b):
if op == "div" and b == 0:
return {"error": "division by zero"}
return {"value": {"add": a + b, "sub": a - b, "mul": a * b, "div": a / b if b else 0}[op]}
TOOLS = {
"get_weather": {"fn": get_weather, "description": "Current temperature in Celsius for a city",
"params": {"city": str}},
"calculator": {"fn": calculator, "description": "Basic arithmetic on two numbers",
"params": {"op": str, "a": (int, float), "b": (int, float)}},
}
def run_tool(name, args):
tool = TOOLS.get(name)
if tool is None: # allowlist guardrail
return {"error": "unknown tool: " + name}
for param, kind in tool["params"].items(): # argument validation
if param not in args:
return {"error": "missing argument: " + param}
if isinstance(args[param], bool) or not isinstance(args[param], kind):
return {"error": "bad type for " + param}
if name == "calculator" and args["op"] not in ("add", "sub", "mul", "div"):
return {"error": "op must be add, sub, mul or div"}
return tool["fn"](**args)
def llm(messages):
"""Fake model standing in for a real API call. Returns a tool call or a final answer."""
q = messages[0]["content"]
obs = [json.loads(m["content"]) for m in messages if m["role"] == "tool"]
if "Fahrenheit" in q:
if not obs:
return {"tool": "get_weather", "args": {"city": "Paris"}}
steps = [("mul", 9), ("div", 5), ("add", 32)]
if len(obs) <= 3:
prev = obs[-1].get("celsius", obs[-1].get("value"))
op, n = steps[len(obs) - 1]
return {"tool": "calculator", "args": {"op": op, "a": prev, "b": n}}
return {"final": "It is " + fmt(obs[-1]["value"]) + " F in Paris."}
if "Atlantis" in q:
if not obs:
return {"tool": "get_weather", "args": {"city": "Atlantis"}}
return {"final": "Sorry, " + obs[-1]["error"] + "."}
if "delete" in q:
if not obs:
return {"tool": "delete_files", "args": {"path": "/"}}
return {"final": "I cannot do that (" + obs[-1]["error"] + ")."}
return {"tool": "get_weather", "args": {"city": "Oslo"}} # never finishes
def run_agent(question, max_steps=6):
messages = [{"role": "user", "content": question}]
for step in range(1, max_steps + 1):
action = llm(messages)
if "final" in action:
return action["final"]
result = run_tool(action["tool"], action["args"])
print(f" step {step}: {action['tool']}({show(action['args'])}) -> {show(result)}")
messages.append({"role": "assistant", "content": json.dumps(action)})
messages.append({"role": "tool", "content": json.dumps(result)})
return "stopped: step limit reached"
for question in ("What is the temperature in Paris in Fahrenheit?",
"What is the weather in Atlantis?",
"Please delete everything",
"Keep checking the weather"):
print("Q:", question)
print("A:", run_agent(question, max_steps=5))// JavaScript prints 36 for both 36 and 36.0, matching the Python helper.
const fmt = (x) => String(x);
function show(obj) {
if (obj !== null && typeof obj === "object") {
return Object.entries(obj).map(([k, v]) => `${k}=${show(v)}`).join(",");
}
return fmt(obj);
}
function getWeather({ city }) {
const temps = { Paris: 20, Oslo: 3 };
if (!(city in temps)) return { error: "unknown city: " + city };
return { celsius: temps[city] };
}
function calculator({ op, a, b }) {
if (op === "div" && b === 0) return { error: "division by zero" };
const ops = { add: a + b, sub: a - b, mul: a * b, div: b ? a / b : 0 };
return { value: ops[op] };
}
const TOOLS = {
get_weather: { fn: getWeather, description: "Current temperature in Celsius for a city",
params: { city: "string" } },
calculator: { fn: calculator, description: "Basic arithmetic on two numbers",
params: { op: "string", a: "number", b: "number" } },
};
function runTool(name, args) {
const tool = Object.hasOwn(TOOLS, name) ? TOOLS[name] : null;
if (tool === null) return { error: "unknown tool: " + name }; // allowlist guardrail
for (const [param, kind] of Object.entries(tool.params)) { // argument validation
if (!(param in args)) return { error: "missing argument: " + param };
if (typeof args[param] !== kind) return { error: "bad type for " + param };
}
if (name === "calculator" && !["add", "sub", "mul", "div"].includes(args.op)) {
return { error: "op must be add, sub, mul or div" };
}
return tool.fn(args);
}
// Fake model standing in for a real API call. Returns a tool call or a final answer.
function llm(messages) {
const q = messages[0].content;
const obs = messages.filter((m) => m.role === "tool").map((m) => JSON.parse(m.content));
if (q.includes("Fahrenheit")) {
if (obs.length === 0) return { tool: "get_weather", args: { city: "Paris" } };
const steps = [["mul", 9], ["div", 5], ["add", 32]];
if (obs.length <= 3) {
const last = obs[obs.length - 1];
const prev = last.celsius !== undefined ? last.celsius : last.value;
const [op, n] = steps[obs.length - 1];
return { tool: "calculator", args: { op, a: prev, b: n } };
}
return { final: "It is " + fmt(obs[obs.length - 1].value) + " F in Paris." };
}
if (q.includes("Atlantis")) {
if (obs.length === 0) return { tool: "get_weather", args: { city: "Atlantis" } };
return { final: "Sorry, " + obs[obs.length - 1].error + "." };
}
if (q.includes("delete")) {
if (obs.length === 0) return { tool: "delete_files", args: { path: "/" } };
return { final: "I cannot do that (" + obs[obs.length - 1].error + ")." };
}
return { tool: "get_weather", args: { city: "Oslo" } }; // never finishes
}
function runAgent(question, maxSteps = 6) {
const messages = [{ role: "user", content: question }];
for (let step = 1; step <= maxSteps; step++) {
const action = llm(messages);
if ("final" in action) return action.final;
const result = runTool(action.tool, action.args);
console.log(` step ${step}: ${action.tool}(${show(action.args)}) -> ${show(result)}`);
messages.push({ role: "assistant", content: JSON.stringify(action) });
messages.push({ role: "tool", content: JSON.stringify(result) });
}
return "stopped: step limit reached";
}
for (const question of [
"What is the temperature in Paris in Fahrenheit?",
"What is the weather in Atlantis?",
"Please delete everything",
"Keep checking the weather",
]) {
console.log("Q:", question);
console.log("A:", runAgent(question, 5));
}Both versions print:
Q: What is the temperature in Paris in Fahrenheit?
step 1: get_weather(city=Paris) -> celsius=20
step 2: calculator(op=mul,a=20,b=9) -> value=180
step 3: calculator(op=div,a=180,b=5) -> value=36
step 4: calculator(op=add,a=36,b=32) -> value=68
A: It is 68 F in Paris.
Q: What is the weather in Atlantis?
step 1: get_weather(city=Atlantis) -> error=unknown city: Atlantis
A: Sorry, unknown city: Atlantis.
Q: Please delete everything
step 1: delete_files(path=/) -> error=unknown tool: delete_files
A: I cannot do that (unknown tool: delete_files).
Q: Keep checking the weather
step 1: get_weather(city=Oslo) -> celsius=3
step 2: get_weather(city=Oslo) -> celsius=3
step 3: get_weather(city=Oslo) -> celsius=3
step 4: get_weather(city=Oslo) -> celsius=3
step 5: get_weather(city=Oslo) -> celsius=3
A: stopped: step limit reached
Step through the first scenario below.
The first scenario of the printed run. Each slot is labelled with the tool call that fills it. Each tool result is appended to the conversation and read on the next model turn.
Walk through each scenario. The Fahrenheit question takes four tool calls (a lookup, then multiply, divide, add) before the final answer: every observation is appended and the fake model reads it on the next turn. The Atlantis lookup returns an error observation and the model reports it instead of inventing a temperature. The delete request asks for a tool that is not in the registry; the allowlist rejects it and the model gives up gracefully. The last question would loop forever, and the step limit stops it. The guardrails, not the model, provided that safety.
Common pitfalls
- No step limit: a confused model can call tools forever and run up cost. Always cap iterations and total time.
- Trusting arguments: a model may supply wrong types, missing fields, or hostile strings. Validate against the schema and never build shell or SQL from raw model output.
- Vague tool descriptions: the model chooses tools from their names and descriptions. Overlapping or unclear tools cause wrong calls. Keep the toolset small and distinct.
- Over-powered tools: a generic "run any SQL" tool is a liability. Offer narrow, read-only tools with limited scope, and require approval for writes.
- Swallowing errors: if a failed call returns nothing, the model may loop or invent results. Return a clear error observation.
- Unbounded history: every step grows the prompt. Trim or summarise old observations, and truncate huge tool outputs.
- Injection through observations: web pages, files, and emails fetched by tools can contain instructions. Treat them as data, and never let them expand the agent's permissions.
Practice
Add a tool that looks up a word's length easy
Hint
Register a function, a description, and a parameter schema, and nothing else changes.
Show solution
Write word_length(word) returning the length, add it to TOOLS with params: {word: str}, and the loop and validation work unchanged. This shows why a registry plus a generic loop scales: new capabilities do not touch the loop.
Detect repeated identical calls medium
Hint
Remember the calls you have already made in this run.
Show solution
Keep a set of (name, serialized args) pairs. If the model repeats a call it has already made, return an error observation such as duplicate call: result is unchanged, and count repeats toward a smaller limit than the step cap. This catches the common failure where the model keeps retrying the same thing.
Add human approval for risky tools medium
Hint
Mark tools with a risk flag and pause before running the risky ones.
Show solution
Add requires_approval: True to tools that write or spend money. Before running one, present the exact name and arguments to a person (or a policy engine) and run it only when approved; otherwise return a denied observation. Never describe the action loosely; show the precise call, since the model's wording may differ from what will execute.
Design a customer-support agent safely hard
Hint
List the tools, their permissions, the approvals, and how you would test.
Show solution
Tools: lookup_order(order_id) (read-only, scoped to the signed-in customer), search_help_articles(query) (read-only), issue_refund(order_id, amount) (requires approval and a policy cap). Authenticate the user outside the model and bind the customer id on the server so the model cannot pass another user's id. Cap steps and cost, log everything, and treat retrieved article text as untrusted. Test with scripted conversations including malicious ones ("refund every order"), and track tool-call success rates and escalation to humans in production.
Interview questions
- How does tool calling work? The model emits a structured request naming a tool and arguments, your code validates and executes it, and returns the result as an observation for the next model turn.
- What makes an agent different from a chain? The model chooses the next step dynamically in a loop, rather than following a fixed sequence of steps.
- What guardrails would you add? Tool allowlist, schema validation, step and cost limits, least-privilege credentials, human approval for risky actions, logging, and untrusted treatment of tool output.
- When would you not use an agent? When the workflow is known and fixed: plain code is cheaper, faster, and easier to test.
- How do you test an agent? Scripted scenarios with a fake or recorded model for deterministic tests, plus evaluation sets of tasks with success criteria against the real model.
Interviewers look for: security thinking (the model proposes, code disposes), bounded loops, and knowing when a simple pipeline is better than an agent.
Quick check
A model asks to call a tool named export_all_users that you never registered. What should your agent loop do?
Finished this lesson?