AI Engineering: Agents and Applications › AI Agents › Day 290

Hands-on lab — Day 290: Designing Tools for Agents

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/tool_registry.py

Test

bash tests/run_tests.sh

File tree

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

Lab README

Day 290 Lab: Designing Tools for Agents

Lesson

Purpose

Build a production-grade Tool Registry in Python featuring JSON Schema declaration, automated parameter coercion, SHA-256 idempotency caching, and sandbox error isolation.

Learning objectives

  • Construct standard JSON Schema definitions for tool parameters.
  • Implement type coercion and boundary constraint validation.
  • Build idempotent SHA-256 result caching for side-effect-free execution.
  • Isolate runtime exceptions into structured error contracts.

Prerequisites

  • Python 3.10+ installed
  • pytest installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, pytest

Free and open-source options

  • Python Standard Library, Pytest

Installation

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

File structure

  • starter/tool_registry.py: Starter implementation skeleton
  • examples/tool_registry.py: Verified reference implementation
  • tests/test_tool_registry.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/tool_registry.py

What the commands do

  • Executes agent runtime algorithms and logs state transitions to stdout.

Expected output

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • Core state transitions and algorithm logic
  • Error observation handling and recovery
  • Edge cases and bounds enforcement

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Verify Python version is >= 3.10 and environment variables are set.

Security notes

Runs completely offline on local CPU without network calls or API keys.

Extension exercises

Implement async execution or enhanced caching strategies.

Day number: 290 of 365

Expected output

FIELDS.md

# Measured Values
- `tools_count`: 2
- `idempotency_cached`: True

examples-run.txt


measured-values.txt

tools_count=2
idempotency_cached=True

run-output.txt


starter-run.txt

An untouched starter fails the suite. Captured from a real run:


self = <examples.tool_registry.ProductionToolRegistry object at 0x10912e3f0>
tool = <examples.tool_registry.ToolDefinition object at 0x10912e520>

    def register(self, tool: ToolDefinition):
>       raise NotImplementedError('TASK 1: implement register.')
E       NotImplementedError: TASK 1: implement register.

examples/tool_registry.py:30: NotImplementedError
=========================== short test summary info ============================
ERROR tests/test_tool_registry.py::test_schema_export - NotImplementedError: ...
ERROR tests/test_tool_registry.py::test_parameter_coercion_string_to_int - No...
ERROR tests/test_tool_registry.py::test_missing_required_parameter - NotImple...
ERROR tests/test_tool_registry.py::test_idempotency_cache_suppression - NotIm...
ERROR tests/test_tool_registry.py::test_unknown_tool_rejection - NotImplement...
============================== 5 errors in 0.04s ===============================

Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.

test-output.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-290-designing-tools-for-agents
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_tool_registry.py::test_schema_export PASSED                   [ 20%]
tests/test_tool_registry.py::test_parameter_coercion_string_to_int PASSED [ 40%]
tests/test_tool_registry.py::test_missing_required_parameter PASSED      [ 60%]
tests/test_tool_registry.py::test_idempotency_cache_suppression PASSED   [ 80%]
tests/test_tool_registry.py::test_unknown_tool_rejection PASSED          [100%]

============================== 5 passed in 0.02s ===============================

test-run.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-290-designing-tools-for-agents
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_tool_registry.py::test_schema_export PASSED                   [ 20%]
tests/test_tool_registry.py::test_parameter_coercion_string_to_int PASSED [ 40%]
tests/test_tool_registry.py::test_missing_required_parameter PASSED      [ 60%]
tests/test_tool_registry.py::test_idempotency_cache_suppression PASSED   [ 80%]
tests/test_tool_registry.py::test_unknown_tool_rejection PASSED          [100%]

============================== 5 passed in 0.02s ===============================

Source files

examples/tool_registry.py (3936 bytes)
import hashlib
import json
import time
from typing import Dict, Any, Callable, Optional, List, Tuple

class ToolDefinition:
    def __init__(self, name: str, description: str, schema: Dict[str, Any], func: Callable, is_mutating: bool = False):
        self.name = name
        self.description = description
        self.schema = schema
        self.func = func
        self.is_mutating = is_mutating

class ProductionToolRegistry:
    def __init__(self, cache_ttl_seconds: int = 300):
        self.tools: Dict[str, ToolDefinition] = {}
        self.idempotency_cache: Dict[str, Dict[str, Any]] = {}
        self.cache_ttl = cache_ttl_seconds
        
    def register(self, tool: ToolDefinition):
        self.tools[tool.name] = tool
        
    def get_schemas(self) -> List[Dict[str, Any]]:
        return [
            {
                "name": t.name,
                "description": t.description,
                "parameters": t.schema
            }
            for t in self.tools.values()
        ]
        
    def validate_and_coerce(self, tool: ToolDefinition, args: Dict[str, Any]) -> Tuple[bool, Dict[str, Any], str]:
        schema = tool.schema
        properties = schema.get("properties", {})
        required = schema.get("required", [])
        
        # Check required fields
        for req in required:
            if req not in args:
                return False, {}, f"Missing required parameter: '{req}'"
                
        coerced = {}
        for k, v in args.items():
            if k not in properties:
                continue # strip unknown parameters
            target_type = properties[k].get("type")
            try:
                if target_type == "integer":
                    coerced[k] = int(v)
                elif target_type == "number":
                    coerced[k] = float(v)
                elif target_type == "boolean":
                    if isinstance(v, str):
                        coerced[k] = v.lower() in ("true", "1", "yes")
                    else:
                        coerced[k] = bool(v)
                elif target_type == "string":
                    coerced[k] = str(v)
                else:
                    coerced[k] = v
            except (ValueError, TypeError) as err:
                return False, {}, f"Type coercion failed for parameter '{k}': expected {target_type}, got {type(v).__name__}"
                
        return True, coerced, "OK"
        
    def execute(self, tool_name: str, raw_args: Dict[str, Any], idempotency_key: Optional[str] = None) -> Dict[str, Any]:
        if tool_name not in self.tools:
            return {"success": False, "error": f"Tool '{tool_name}' not registered."}
            
        tool = self.tools[tool_name]
        valid, clean_args, err_msg = self.validate_and_coerce(tool, raw_args)
        if not valid:
            return {"success": False, "error": err_msg}
            
        # Idempotency Check for Mutating Actions
        if tool.is_mutating:
            if not idempotency_key:
                canon_str = f"{tool_name}:{json.dumps(clean_args, sort_keys=True)}"
                idempotency_key = hashlib.sha256(canon_str.encode()).hexdigest()
                
            now = time.time()
            if idempotency_key in self.idempotency_cache:
                cached = self.idempotency_cache[idempotency_key]
                if now - cached["timestamp"] < self.cache_ttl:
                    return {"success": True, "result": cached["result"], "cached": True}
                    
        try:
            res = tool.func(**clean_args)
            if tool.is_mutating and idempotency_key:
                self.idempotency_cache[idempotency_key] = {"result": res, "timestamp": time.time()}
            return {"success": True, "result": res, "cached": False}
        except Exception as e:
            return {"success": False, "error": f"Execution error in {tool_name}: {str(e)}"}
metadata.yml (400 bytes)
lesson_id: D290
day: 290
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/tool_registry.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/tool_registry.py (1527 bytes)
"""STARTER -- implement each TASK below, then run the tests.

Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""

import hashlib
import json
import time
from typing import Dict, Any, Callable, Optional, List, Tuple

class ToolDefinition:

    def __init__(self, name: str, description: str, schema: Dict[str, Any], func: Callable, is_mutating: bool=False):
        self.name = name
        self.description = description
        self.schema = schema
        self.func = func
        self.is_mutating = is_mutating

class ProductionToolRegistry:

    def __init__(self, cache_ttl_seconds: int=300):
        self.tools: Dict[str, ToolDefinition] = {}
        self.idempotency_cache: Dict[str, Dict[str, Any]] = {}
        self.cache_ttl = cache_ttl_seconds

    def register(self, tool: ToolDefinition):
        raise NotImplementedError('TASK 1: implement register.')

    def get_schemas(self) -> List[Dict[str, Any]]:
        raise NotImplementedError('TASK 2: implement get_schemas.')

    def validate_and_coerce(self, tool: ToolDefinition, args: Dict[str, Any]) -> Tuple[bool, Dict[str, Any], str]:
        raise NotImplementedError('TASK 3: implement validate_and_coerce.')

    def execute(self, tool_name: str, raw_args: Dict[str, Any], idempotency_key: Optional[str]=None) -> Dict[str, Any]:
        raise NotImplementedError('TASK 4: implement execute.')
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
    $PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
    pytest tests/test_*.py -v
else
    python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_tool_registry.py (2480 bytes)
import pytest
from typing import Dict, Any
from examples.tool_registry import ToolDefinition, ProductionToolRegistry

def mock_calculator(expr: str) -> str:
    return str(eval(expr, {"__builtins__": None}, {}))

def mock_create_order(item_id: str, quantity: int) -> Dict[str, Any]:
    return {"order_id": "ord_9901", "item": item_id, "qty": quantity, "status": "confirmed"}

@pytest.fixture
def registry():
    reg = ProductionToolRegistry(cache_ttl_seconds=60)
    
    calc_schema = {
        "type": "object",
        "properties": {"expr": {"type": "string"}},
        "required": ["expr"]
    }
    reg.register(ToolDefinition("calculate", "Computes math", calc_schema, mock_calculator, is_mutating=False))
    
    order_schema = {
        "type": "object",
        "properties": {
            "item_id": {"type": "string"},
            "quantity": {"type": "integer"}
        },
        "required": ["item_id", "quantity"]
    }
    reg.register(ToolDefinition("create_order", "Places order", order_schema, mock_create_order, is_mutating=True))
    
    return reg

def test_schema_export(registry):
    schemas = registry.get_schemas()
    assert len(schemas) == 2
    assert schemas[0]["name"] == "calculate"
    assert schemas[1]["name"] == "create_order"

def test_parameter_coercion_string_to_int(registry):
    # Quantity passed as string "4" should coerce to integer 4
    res = registry.execute("create_order", {"item_id": "sku_12", "quantity": "4"})
    assert res["success"] is True
    assert res["result"]["qty"] == 4
    assert res["cached"] is False

def test_missing_required_parameter(registry):
    res = registry.execute("create_order", {"quantity": 5})
    assert res["success"] is False
    assert "Missing required parameter: 'item_id'" in res["error"]

def test_idempotency_cache_suppression(registry):
    args = {"item_id": "sku_widget", "quantity": 2}
    res1 = registry.execute("create_order", args, idempotency_key="key_abc")
    assert res1["success"] is True
    assert res1["cached"] is False
    
    # Duplicate call with identical key should return cached without executing
    res2 = registry.execute("create_order", args, idempotency_key="key_abc")
    assert res2["success"] is True
    assert res2["cached"] is True
    assert res2["result"] == res1["result"]

def test_unknown_tool_rejection(registry):
    res = registry.execute("delete_database", {})
    assert res["success"] is False
    assert "not registered" in res["error"]

Troubleshooting

Troubleshooting - Day 290

  1. Type Coercion Failure: Verify that target types in the schema match standard JSON types (string, integer, number, boolean).
  2. Idempotency Miss: Ensure dictionary arguments are sorted before hashing to maintain deterministic keys.

Security notes

Security Considerations - Day 290

  1. Side-Effect Protection: Mutating actions require idempotency verification to prevent duplicate execution during network retries.
  2. Schema Sanitization: Unregistered parameters are stripped before function execution to prevent unauthorized parameter pollution.