LLMs and Generative AI › LLM APIs › Day 256
Hands-on lab — Day 256: Tool Use and Function Calling
- ← Back to the Day 256 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/llms-and-generative-ai/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_resultpayloads 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
- Verify tool registration stores valid schemas.
- Confirm dispatcher executes target Python function with arguments.
- Validate error message is returned for unregistered tools.
- 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
- Implement an async parallel tool runner with
asyncio.gather. - Build an AST-validated SQL query executor tool.
Navigation
- Lesson title: Tool Use and Function Calling
- Day number: 256 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-256-tool-use-and-function-calling
- Lab files: everything you need is in this directory — follow “How to run” below.
- Browse the course locally: from the repository root, this lab also appears in the course website at
/labs/day-256-tool-use-and-function-callingwhen the site is running.
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
- 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.