Capstone › Capstone Build I: Foundation › Day 355

Hands-on lab — 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

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 skeleton
  • examples/agent.py: Verified reference implementation
  • tests/test_agent.py: Test suite
  • expected-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.

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

Troubleshooting

Troubleshooting - Day 355\nVerify tool names and parameter schemas match exactly between model output and registry.\n

Security notes

Security - Day 355\nAgent dispatcher enforces sandboxed tool permissions and bounds maximum execution cycles.\n