AI Engineering: Agents and Applications › AI Agents › Day 290
Hands-on lab — Day 290: Designing Tools for Agents
- ← Back to the Day 290 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/ai-engineering/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
- Lesson title: Designing Tools for Agents
- Day number: 290 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-290-designing-tools-for-agents
- 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-290-designing-tools-for-agentswhen the site is running.
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 skeletonexamples/tool_registry.py: Verified reference implementationtests/test_tool_registry.py: Test suiteexpected-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.
Navigation
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
- Type Coercion Failure: Verify that target types in the schema match standard JSON types (
string,integer,number,boolean). - Idempotency Miss: Ensure dictionary arguments are sorted before hashing to maintain deterministic keys.
Security notes
Security Considerations - Day 290
- Side-Effect Protection: Mutating actions require idempotency verification to prevent duplicate execution during network retries.
- Schema Sanitization: Unregistered parameters are stripped before function execution to prevent unauthorized parameter pollution.