LLMs and Generative AI › LLM APIs › Day 256

Hands-on lab — Day 256: Tool Use and Function Calling

Commands

Setup

pip install -r requirements/requirements.txt

Run

python3 examples/tool_use_and_function_calling_lib.py

Test

./tests/run_tests.sh

File tree

conftest.py
examples/test_tool_use_and_function_calling_lib.py
examples/tool_use_and_function_calling_lib.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/starter-run.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/test_tool_use_and_function_calling_lib.py
starter/tool_use_and_function_calling_lib.py
tests/run_tests.sh
tests/test_tool_use_and_function_calling_lib.py
troubleshooting.md

Lab README

Lab: Day 256 -- Tool Use and Function Calling

Lesson

Day number: 256 of 365. Course: Course06-SS02 (LLMs and Generative AI - LLM APIs). Topic: Tool Use, Function Calling, and Automated Dispatchers.

Purpose

Build and test an Automated Tool Dispatcher and Agent Loop in Python. Register custom mathematical and lookup tools with JSON Schema declarations, parse tool use stop reasons, and package structured tool results.

Learning objectives

  • Register custom Python functions in a typed tool dispatcher.
  • Format declarative JSON Schema tool definitions.
  • Execute local functions safely and handle execution exceptions.
  • Package tool_result payloads for multi-turn agent loops.

Prerequisites

  • Day 255 (Streaming Responses).
  • Python 3.11+ with Pytest.

Supported operating systems

  • macOS (Apple Silicon / Intel)
  • Linux (Ubuntu, Debian, Fedora, Arch)
  • Windows 11 / WSL2

Hardware requirements

  • 1+ CPU cores.
  • 1 GB RAM.
  • 100 MB disk space.

Required software

  • Python 3.11 or newer.
  • pip package manager.
  • virtualenv or venv module.

Free and open-source options

Python and standard typing/json modules are open source.

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/tool_use_and_function_calling_lib.py: Student scaffold file.
  • examples/tool_use_and_function_calling_lib.py: Complete reference implementation.
  • tests/test_tool_use_and_function_calling_lib.py: Pytest automated validation suite.
  • expected-output/: Verified output logs and baseline values.

How to run

Execute the reference demonstration script:

python3 examples/tool_use_and_function_calling_lib.py

What the commands do

  • Registers calculation tool.
  • Simulates tool calling response turn.
  • Runs unit test assertions.

Expected output

Dispatcher Demo Executed. Result: 107.25

Validation steps

  1. Verify tool registration stores valid schemas.
  2. Confirm dispatcher executes target Python function with arguments.
  3. Validate error message is returned for unregistered tools.
  4. Ensure all unit test assertions pass.

Tests

Run the test runner script:

./tests/run_tests.sh

Cleanup

find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type d -name ".pytest_cache" -exec rm -rf {} +

Troubleshooting

  • Argument mismatch error: Ensure function argument names match JSON schema properties.

Security notes

All tools execute strictly in local memory.

Extension exercises

  1. Implement an async parallel tool runner with asyncio.gather.
  2. Build an AST-validated SQL query executor tool.

Expected output

FIELDS.md

# Expected Output Fields: Day 256

- `Dispatcher Demo`: Status of tool dispatcher execution.

examples-run.txt

Dispatcher Demo Executed. Result: 107.25

measured-values.txt

Dispatcher Demo: Success
Executed Tool: calculate_tax
Result Value: 107.25

starter-run.txt

Starter scaffold executed. Ready for student implementation.

test-run.txt

============================= test session starts ==============================
collected 3 items

tests/test_tool_use_and_function_calling_lib.py::test_tool_registration_and_execution PASSED [ 33%]
tests/test_tool_use_and_function_calling_lib.py::test_unregistered_tool PASSED                [ 66%]
tests/test_tool_use_and_function_calling_lib.py::test_agent_turn_packaging PASSED           [100%]

============================== 3 passed in 0.38s ===============================

Source files

conftest.py (585 bytes)
"""Make this lab importable when the suite runs.

pytest puts the test file's own directory on sys.path, not the lab root, so a
test that does `from examples.<module> import ...` -- or imports a module that
lives in examples/ directly -- fails without this. Putting it here rather than
in run_tests.sh means a bare `pytest` from the lab root works too.
"""

import os
import sys

LAB = os.path.dirname(os.path.abspath(__file__))
for candidate in (LAB, os.path.join(LAB, "examples")):
    if os.path.isdir(candidate) and candidate not in sys.path:
        sys.path.insert(0, candidate)
examples/test_tool_use_and_function_calling_lib.py (1171 bytes)
import pytest
from examples.tool_use_and_function_calling_lib import (
    ToolDispatcher,
    calculate_tax,
    get_order_status
)

def test_tool_registration_and_execution():
    dispatcher = ToolDispatcher()
    dispatcher.register_tool("tax", "Calc tax", {}, calculate_tax)

    res = dispatcher.execute_tool("tax", {"amount": 100.0, "state": "CA"})
    assert res == "107.25"

def test_unregistered_tool():
    dispatcher = ToolDispatcher()
    res = dispatcher.execute_tool("unknown", {})
    assert "Error: Tool 'unknown' is not registered." in res

def test_agent_turn_packaging():
    dispatcher = ToolDispatcher()
    dispatcher.register_tool("order", "Order lookup", {}, get_order_status)

    mock_resp = {
        "stop_reason": "tool_use",
        "content": [{
            "type": "tool_use",
            "id": "call_ord_99",
            "name": "order",
            "input": {"order_id": "ORD-101"}
        }]
    }

    turn_output = dispatcher.run_agent_turn(mock_resp)
    assert not turn_output["is_complete"]
    assert turn_output["tool_results"][0]["tool_use_id"] == "call_ord_99"
    assert turn_output["tool_results"][0]["content"] == "Shipped"
examples/tool_use_and_function_calling_lib.py (2559 bytes)
from typing import Dict, Any, List, Callable
import json

def calculate_tax(amount: float, state: str = "CA") -> float:
    rate = 0.0725 if state == "CA" else 0.05
    return round(amount * (1 + rate), 2)

def get_order_status(order_id: str) -> str:
    orders = {"ORD-101": "Shipped", "ORD-102": "Processing"}
    return orders.get(order_id, "Order not found")

class ToolDispatcher:
    def __init__(self):
        self.registry: Dict[str, Callable] = {}
        self.schemas: List[Dict[str, Any]] = []

    def register_tool(self, name: str, description: str, schema: Dict[str, Any], func: Callable):
        self.registry[name] = func
        self.schemas.append({
            "name": name,
            "description": description,
            "input_schema": schema
        })

    def execute_tool(self, name: str, args: Dict[str, Any]) -> str:
        if name not in self.registry:
            return f"Error: Tool '{name}' is not registered."
        try:
            return str(self.registry[name](**args))
        except Exception as e:
            return f"Error executing tool '{name}': {str(e)}"

    def run_agent_turn(self, mock_model_response: Dict[str, Any]) -> Dict[str, Any]:
        tool_results = []
        if mock_model_response.get("stop_reason") == "tool_use":
            for call in mock_model_response.get("content", []):
                if call.get("type") == "tool_use":
                    out = self.execute_tool(call["name"], call["input"])
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": call["id"],
                        "content": out
                    })
        return {
            "tool_results": tool_results,
            "is_complete": len(tool_results) == 0
        }

def run_dispatcher_demo():
    dispatcher = ToolDispatcher()
    dispatcher.register_tool(
        "calculate_tax",
        "Calculates tax for an amount and state",
        {"type": "object", "properties": {"amount": {"type": "number"}, "state": {"type": "string"}}},
        calculate_tax
    )

    mock_response = {
        "stop_reason": "tool_use",
        "content": [{
            "type": "tool_use",
            "id": "toolu_tax_01",
            "name": "calculate_tax",
            "input": {"amount": 100.0, "state": "CA"}
        }]
    }

    result = dispatcher.run_agent_turn(mock_response)
    print("Dispatcher Demo Executed. Result:", result["tool_results"][0]["content"])
    return result

if __name__ == "__main__":
    run_dispatcher_demo()
metadata.yml (442 bytes)
lesson_id: D256
day: 256
kind: lab
languages:
  - python
setup_commands:
  - 'pip install -r requirements/requirements.txt'
run_commands:
  - 'python3 examples/tool_use_and_function_calling_lib.py'
test_commands:
  - './tests/run_tests.sh'
cleanup_commands:
  - 'find . -type d -name "__pycache__" -exec rm -rf {} +'
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: 'macos-arm64'
requirements/requirements.txt (41 bytes)
torch>=2.2.0
numpy>=1.26.0
pytest>=8.0.0
starter/test_tool_use_and_function_calling_lib.py (1171 bytes)
import pytest
from examples.tool_use_and_function_calling_lib import (
    ToolDispatcher,
    calculate_tax,
    get_order_status
)

def test_tool_registration_and_execution():
    dispatcher = ToolDispatcher()
    dispatcher.register_tool("tax", "Calc tax", {}, calculate_tax)

    res = dispatcher.execute_tool("tax", {"amount": 100.0, "state": "CA"})
    assert res == "107.25"

def test_unregistered_tool():
    dispatcher = ToolDispatcher()
    res = dispatcher.execute_tool("unknown", {})
    assert "Error: Tool 'unknown' is not registered." in res

def test_agent_turn_packaging():
    dispatcher = ToolDispatcher()
    dispatcher.register_tool("order", "Order lookup", {}, get_order_status)

    mock_resp = {
        "stop_reason": "tool_use",
        "content": [{
            "type": "tool_use",
            "id": "call_ord_99",
            "name": "order",
            "input": {"order_id": "ORD-101"}
        }]
    }

    turn_output = dispatcher.run_agent_turn(mock_resp)
    assert not turn_output["is_complete"]
    assert turn_output["tool_results"][0]["tool_use_id"] == "call_ord_99"
    assert turn_output["tool_results"][0]["content"] == "Shipped"
starter/tool_use_and_function_calling_lib.py (598 bytes)
from typing import Dict, Any, List, Callable
import json

class ToolDispatcher:
    def __init__(self):
        # TODO: Initialize registry and schema list
        pass

    def register_tool(self, name: str, description: str, schema: Dict[str, Any], func: Callable):
        # TODO: Register tool and schema
        pass

    def execute_tool(self, name: str, args: Dict[str, Any]) -> str:
        # TODO: Execute tool safely
        pass

    def run_agent_turn(self, mock_model_response: Dict[str, Any]) -> Dict[str, Any]:
        # TODO: Process tool calls and format tool_results
        pass
tests/run_tests.sh (227 bytes)
#!/usr/bin/env bash
set -euo pipefail
echo "========================================"
echo "Running Day 256 Lab Test Suite"
echo "========================================"
pytest tests/ -v
echo "All tests passed successfully."
tests/test_tool_use_and_function_calling_lib.py (1171 bytes)
import pytest
from examples.tool_use_and_function_calling_lib import (
    ToolDispatcher,
    calculate_tax,
    get_order_status
)

def test_tool_registration_and_execution():
    dispatcher = ToolDispatcher()
    dispatcher.register_tool("tax", "Calc tax", {}, calculate_tax)

    res = dispatcher.execute_tool("tax", {"amount": 100.0, "state": "CA"})
    assert res == "107.25"

def test_unregistered_tool():
    dispatcher = ToolDispatcher()
    res = dispatcher.execute_tool("unknown", {})
    assert "Error: Tool 'unknown' is not registered." in res

def test_agent_turn_packaging():
    dispatcher = ToolDispatcher()
    dispatcher.register_tool("order", "Order lookup", {}, get_order_status)

    mock_resp = {
        "stop_reason": "tool_use",
        "content": [{
            "type": "tool_use",
            "id": "call_ord_99",
            "name": "order",
            "input": {"order_id": "ORD-101"}
        }]
    }

    turn_output = dispatcher.run_agent_turn(mock_resp)
    assert not turn_output["is_complete"]
    assert turn_output["tool_results"][0]["tool_use_id"] == "call_ord_99"
    assert turn_output["tool_results"][0]["content"] == "Shipped"

Troubleshooting

Troubleshooting: Day 256 - Tool Use and Function Calling

Common Issues

  1. Unregistered tool call error:
    • Cause: Model requested a tool name not present in the dispatcher registry.
    • Fix: Ensure all declared tool schemas have corresponding registered Python functions.

Security notes

Security & Privacy: Day 256 - Tool Use and Function Calling

Security Guidance

  • Restrict tool execution to safe sandboxed operations; never expose unrestricted shell execution.