Capstone › Capstone Build I: Foundation › Day 355
Hands-on lab — Day 355: Agent and Tool Integration
- ← Back to the Day 355 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/capstone/day-355-agent-and-tool-integration/
Commands
Setup
pip install -r requirements/requirements.txt Run
python examples/agent.py Test
bash tests/run_tests.sh File tree
examples/agent.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/agent.py tests/run_tests.sh tests/test_agent.py troubleshooting.md
Lab README
Day 355 Lab: Agent and Tool Integration
Lesson
- Lesson title: Agent and Tool Integration
- Day number: 355 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-355-agent-and-tool-integration
- 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-355-agent-and-tool-integrationwhen the site is running.
Purpose
Build a Production ReAct Agent Engine in Python featuring a schema-validated tool registry, sandboxed tool dispatcher, multi-turn reasoning loop, and JSON state checkpointing.
Learning objectives
- Register tool schemas and execution handlers.
- Execute tools safely within a sandboxed dispatcher.
- Run a multi-turn ReAct reasoning loop with turn limits.
- Capture serializable execution checkpoints.
Prerequisites
- Python 3.10+ installed
- pydantic and pytest installed
Supported operating systems
- macOS, Linux, Windows WSL2
Hardware requirements
- Standard CPU, 512MB RAM
Required software
- Python 3.10+, pytest, pydantic
Free and open-source options
- Python Standard Library, Pytest, Pydantic
Installation
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt
File structure
starter/agent.py: Starter implementation skeletonexamples/agent.py: Verified reference implementationtests/test_agent.py: Test suiteexpected-output/: Captured execution logs
How to run
python3 examples/agent.py
What the commands do
- Executes multi-turn agent reasoning, runs sandboxed tools, and records state checkpoints.
Expected output
{'status': 'SUCCESS', 'total_turns': 1, 'final_answer': '15000', 'checkpoints': [{'turn': 1, 'thought': 'done', 'action': 'FINAL_ANSWER', 'action_input': {'answer': '15000'}, 'observation': 'COMPLETED'}]}
Validation steps
Run test runner:
bash tests/run_tests.sh
Tests
The test suite validates:
- Tool registration and schema definition
- Sandboxed tool execution and error capture
- Multi-turn ReAct reasoning workflow
- Max turn limit enforcement
- State checkpoint serialization
Cleanup
rm -rf .pytest_cache __pycache__ .venv
Troubleshooting
Ensure tool return values are JSON-serializable.
Security notes
Runs locally with zero external network calls.
Extension exercises
Implement a rate limiter on tool executions.
Navigation
Day number: 355 of 365
Expected output
FIELDS.md
# Measured Values
- `max_turns_limit`: 5
- `tool_accuracy_rate`: 100.0
examples-run.txt
{'status': 'SUCCESS', 'total_turns': 1, 'final_answer': '15000', 'checkpoints': [{'turn': 1, 'thought': 'done', 'action': 'FINAL_ANSWER', 'action_input': {'answer': '15000'}, 'observation': 'COMPLETED'}]}
measured-values.txt
max_turns_limit=5
tool_accuracy_rate=100.0
run-output.txt
{'status': 'SUCCESS', 'total_turns': 1, 'final_answer': '15000', 'checkpoints': [{'turn': 1, 'thought': 'done', 'action': 'FINAL_ANSWER', 'action_input': {'answer': '15000'}, 'observation': 'COMPLETED'}]}
starter-run.txt
An untouched starter fails the suite. Captured from a real run:
self = <examples.agent.AgentOrchestrator object at 0x10b5696e0>, name = 'fail'
description = 'Failing tool', param_schema = {}
handler = <function test_tool_exception_recovery.<locals>.failing_tool at 0x10b5959b0>
def register_tool(self, name: str, description: str, param_schema: Dict[str, Any], handler: Callable):
> raise NotImplementedError('TASK 2: implement register_tool.')
E NotImplementedError: TASK 2: implement register_tool.
examples/agent.py:39: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_agent.py::test_tool_registration - NotImplementedError: TAS...
FAILED tests/test_agent.py::test_tool_not_found_handling - NotImplementedErro...
FAILED tests/test_agent.py::test_successful_multi_turn_agent_execution - NotI...
FAILED tests/test_agent.py::test_max_turns_exceeded_safety_guard - NotImpleme...
FAILED tests/test_agent.py::test_tool_exception_recovery - NotImplementedErro...
============================== 5 failed in 0.03s ===============================
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/capstone/day-355-agent-and-tool-integration
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items
tests/test_agent.py::test_tool_registration PASSED [ 20%]
tests/test_agent.py::test_tool_not_found_handling PASSED [ 40%]
tests/test_agent.py::test_successful_multi_turn_agent_execution PASSED [ 60%]
tests/test_agent.py::test_max_turns_exceeded_safety_guard PASSED [ 80%]
tests/test_agent.py::test_tool_exception_recovery PASSED [100%]
============================== 5 passed in 0.01s ===============================
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/capstone/day-355-agent-and-tool-integration
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items
tests/test_agent.py::test_tool_registration PASSED [ 20%]
tests/test_agent.py::test_tool_not_found_handling PASSED [ 40%]
tests/test_agent.py::test_successful_multi_turn_agent_execution PASSED [ 60%]
tests/test_agent.py::test_max_turns_exceeded_safety_guard PASSED [ 80%]
tests/test_agent.py::test_tool_exception_recovery PASSED [100%]
============================== 5 passed in 0.01s ===============================
Source files
examples/agent.py (4587 bytes)
import json
from typing import Dict, Any, List, Callable, Tuple
class ToolDefinition:
def __init__(self, name: str, description: str, parameters_schema: Dict[str, Any]):
self.name = name
self.description = description
self.parameters_schema = parameters_schema
class AgentCheckpoint:
def __init__(self, turn: int, thought: str, action: str, action_input: Dict[str, Any], observation: str):
self.turn = turn
self.thought = thought
self.action = action
self.action_input = action_input
self.observation = observation
def model_dump(self) -> Dict[str, Any]:
return {
"turn": self.turn,
"thought": self.thought,
"action": self.action,
"action_input": self.action_input,
"observation": self.observation
}
class AgentOrchestrator:
def __init__(self, model_fn: Callable[[str], str], max_turns: int = 5):
self.model_fn = model_fn
self.max_turns = max_turns
self.tool_registry: Dict[str, Tuple[ToolDefinition, Callable]] = {}
self.checkpoints: List[AgentCheckpoint] = []
def register_tool(self, name: str, description: str, param_schema: Dict[str, Any], handler: Callable):
tool_def = ToolDefinition(name=name, description=description, parameters_schema=param_schema)
self.tool_registry[name] = (tool_def, handler)
def _execute_sandboxed_tool(self, name: str, args: Dict[str, Any]) -> str:
if name not in self.tool_registry:
return f"ERROR: Tool '{name}' not found in registry."
_, handler = self.tool_registry[name]
try:
result = handler(**args)
return json.dumps(result) if isinstance(result, (dict, list)) else str(result)
except Exception as e:
return f"ERROR executing tool '{name}': {str(e)}"
def run_agent(self, user_goal: str) -> Dict[str, Any]:
scratchpad = f"User Goal: {user_goal}\n"
self.checkpoints = []
for turn in range(1, self.max_turns + 1):
tools_desc = "\n".join([f"- {t.name}: {t.description}" for t, _ in self.tool_registry.values()])
prompt = (
f"You are an autonomous AI agent. Available tools:\n{tools_desc}\n\n"
f"Scratchpad:\n{scratchpad}\n\n"
f"Emit JSON with 'thought', 'action' (tool name or 'FINAL_ANSWER'), and 'action_input'."
)
raw_resp = self.model_fn(prompt)
try:
cleaned = raw_resp.strip().removeprefix("```json").removesuffix("```").strip()
action_payload = json.loads(cleaned)
thought = action_payload.get("thought", "")
action = action_payload.get("action", "")
action_input = action_payload.get("action_input", {})
except Exception:
thought = "Parse error"
action = "FINAL_ANSWER"
action_input = {"answer": raw_resp}
if action == "FINAL_ANSWER":
self.checkpoints.append(AgentCheckpoint(
turn=turn, thought=thought, action="FINAL_ANSWER",
action_input=action_input, observation="COMPLETED"
))
return {
"status": "SUCCESS",
"total_turns": turn,
"final_answer": action_input.get("answer", raw_resp),
"checkpoints": [c.model_dump() for c in self.checkpoints]
}
observation = self._execute_sandboxed_tool(action, action_input)
scratchpad += f"\nTurn {turn}:\nThought: {thought}\nAction: {action}({action_input})\nObservation: {observation}\n"
self.checkpoints.append(AgentCheckpoint(
turn=turn, thought=thought, action=action,
action_input=action_input, observation=observation
))
return {
"status": "MAX_TURNS_EXCEEDED",
"total_turns": self.max_turns,
"final_answer": "Agent reached maximum recursion depth without finishing.",
"checkpoints": [c.model_dump() for c in self.checkpoints]
}
if __name__ == "__main__":
def mock_db(account_id: str): return {"balance": 15000}
agent = AgentOrchestrator(model_fn=lambda p: '{"thought": "done", "action": "FINAL_ANSWER", "action_input": {"answer": "15000"}}')
agent.register_tool("get_balance", "Get account balance", {}, mock_db)
print(agent.run_agent("Check balance"))
metadata.yml (392 bytes)
lesson_id: D355
day: 355
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/agent.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 55
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (30 bytes)
pydantic>=2.0.0
pytest>=7.0.0
starter/agent.py (2122 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 json
from typing import Dict, Any, List, Callable, Tuple
class ToolDefinition:
def __init__(self, name: str, description: str, parameters_schema: Dict[str, Any]):
self.name = name
self.description = description
self.parameters_schema = parameters_schema
class AgentCheckpoint:
def __init__(self, turn: int, thought: str, action: str, action_input: Dict[str, Any], observation: str):
self.turn = turn
self.thought = thought
self.action = action
self.action_input = action_input
self.observation = observation
def model_dump(self) -> Dict[str, Any]:
raise NotImplementedError('TASK 1: implement model_dump.')
class AgentOrchestrator:
def __init__(self, model_fn: Callable[[str], str], max_turns: int=5):
self.model_fn = model_fn
self.max_turns = max_turns
self.tool_registry: Dict[str, Tuple[ToolDefinition, Callable]] = {}
self.checkpoints: List[AgentCheckpoint] = []
def register_tool(self, name: str, description: str, param_schema: Dict[str, Any], handler: Callable):
raise NotImplementedError('TASK 2: implement register_tool.')
def _execute_sandboxed_tool(self, name: str, args: Dict[str, Any]) -> str:
raise NotImplementedError('TASK 3: implement _execute_sandboxed_tool.')
def run_agent(self, user_goal: str) -> Dict[str, Any]:
raise NotImplementedError('TASK 4: implement run_agent.')
if __name__ == '__main__':
def mock_db(account_id: str):
raise NotImplementedError('TASK 5: implement mock_db.')
agent = AgentOrchestrator(model_fn=lambda p: '{"thought": "done", "action": "FINAL_ANSWER", "action_input": {"answer": "15000"}}')
agent.register_tool('get_balance', 'Get account balance', {}, mock_db)
print(agent.run_agent('Check balance'))
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_agent.py (2160 bytes)
import pytest
from examples.agent import AgentOrchestrator
def test_tool_registration():
agent = AgentOrchestrator(model_fn=lambda p: "")
agent.register_tool("calc", "Calculator", {"a": "int", "b": "int"}, lambda a, b: a + b)
assert "calc" in agent.tool_registry
res = agent._execute_sandboxed_tool("calc", {"a": 5, "b": 10})
assert res == "15"
def test_tool_not_found_handling():
agent = AgentOrchestrator(model_fn=lambda p: "")
res = agent._execute_sandboxed_tool("missing_tool", {})
assert "ERROR: Tool 'missing_tool' not found" in res
def test_successful_multi_turn_agent_execution():
step = 0
def mock_llm(p: str) -> str:
nonlocal step
step += 1
if step == 1:
return '{"thought": "Fetch data", "action": "fetch", "action_input": {"key": "revenue"}}'
return '{"thought": "Synthesize", "action": "FINAL_ANSWER", "action_input": {"answer": "Revenue is $10M"}}'
agent = AgentOrchestrator(model_fn=mock_llm)
agent.register_tool("fetch", "Fetch metric", {}, lambda key: 10000000)
result = agent.run_agent("What is revenue?")
assert result["status"] == "SUCCESS"
assert result["total_turns"] == 2
assert "Revenue is $10M" in result["final_answer"]
assert len(result["checkpoints"]) == 2
def test_max_turns_exceeded_safety_guard():
# Model that keeps calling tools forever
def infinite_loop_llm(p: str) -> str:
return '{"thought": "Keep going", "action": "noop", "action_input": {}}'
agent = AgentOrchestrator(model_fn=infinite_loop_llm, max_turns=3)
agent.register_tool("noop", "No operation", {}, lambda: "ok")
result = agent.run_agent("Do endless work")
assert result["status"] == "MAX_TURNS_EXCEEDED"
assert result["total_turns"] == 3
assert len(result["checkpoints"]) == 3
def test_tool_exception_recovery():
def failing_tool(): raise ValueError("Database timeout")
agent = AgentOrchestrator(model_fn=lambda p: "")
agent.register_tool("fail", "Failing tool", {}, failing_tool)
res = agent._execute_sandboxed_tool("fail", {})
assert "ERROR executing tool 'fail'" in res