DevPath
Tracks

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.

  1. Send the conversation plus tool definitions to the model.
  2. The model replies with either a final answer or a tool call (a name and arguments).
  3. If it is a tool call, your code validates and executes it, producing an observation (a result or an error).
  4. Append the call and the observation to the conversation and go to step 1.
  5. Stop on a final answer, on a step limit, or on any guardrail trigger.

One pass through the loop, as messages between the parties:

UserAgent loopLLMTooltaskmessages + tool definitionstool call: get_weather(Paris)validate, then runobservation: celsius=20messages + observationfinal answeranswer
The model never touches the tool: it only emits a request. Your loop sits in the middle, which is where validation, limits, and logging live. Real runs repeat the middle block once per tool call.
 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.

Tool call from model
Allowlistknown tool name?
Validate argumentsrequired, type, allowed values
Step limitunder the cap?
Run tool
Observation
A failure at any gate skips the tool and returns an error observation instead, so the model can adapt. The gates run in your code and do not depend on the model behaving.

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.

OperationTimeNotes
Agent run with s stepss model calls + s tool callsLatency and cost scale with steps
Prompt size at step iGrows with iHistory accumulates; long runs need trimming or summaries
Argument validationO(size of arguments)Negligible; always do it
Step limitConstant capTurns 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))

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.

get_weather
mul 9
div 5
add 32
answer
Question: temperature in Paris in Fahrenheit. The model will request four tool calls in a row; each observation feeds the next call.
step 1 / 6

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

  1. 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.
  2. 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.
  3. 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.
  4. When would you not use an agent? When the workflow is known and fixed: plain code is cheaper, faster, and easier to test.
  5. 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?

Further resources

Related lessons