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

Hands-on lab — Day 288: What an AI Agent Is

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/agent_state_machine.py

Test

bash tests/run_tests.sh

File tree

examples/agent_state_machine.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_state_machine.py
tests/run_tests.sh
tests/test_agent_state_machine.py
troubleshooting.md

Lab README

Day 288 Lab: What an AI Agent Is

Lesson

  • Lesson title: What an AI Agent Is
  • Day number: 288 of 365
  • Lesson article: https://ai-roadmap-365.github.io/day-288-what-an-ai-agent-is
  • 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-288-what-an-ai-agent-is when the site is running.

Purpose

Construct an autonomous AI agent runtime featuring an explicit discrete State Machine, Perception-Cognition-Action loop, cycle detection hash table, and step budget guards.

Learning objectives

  • Deconstruct the perception-cognition-action loop driving autonomous AI agents.
  • Implement discrete state machine transitions (INITIALIZED, REASONING, ACTING, TERMINATED).
  • Incorporate cycle detection and maximum execution budgets.
  • Execute goal-directed tasks with observation feedback loops.

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/agent_state_machine.py: Starter implementation skeleton
  • examples/agent_state_machine.py: Verified reference implementation
  • tests/test_agent_state_machine.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/agent_state_machine.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: 288 of 365

Expected output

FIELDS.md

# Measured Values
- `max_steps`: 5
- `cycles_detected`: 1

examples-run.txt


measured-values.txt

max_steps=5
cycles_detected=1

run-output.txt


starter-run.txt

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


self = <examples.agent_state_machine.ToolRegistry object at 0x10b61e780>
name = 'calculator', func = <function safe_calc at 0x10b64c720>

    def register(self, name: str, func: Callable[[str], str]):
>       raise NotImplementedError('TASK 3: implement register.')
E       NotImplementedError: TASK 3: implement register.

examples/agent_state_machine.py:39: NotImplementedError
=========================== short test summary info ============================
ERROR tests/test_agent_state_machine.py::test_tool_registry_execution - NotIm...
ERROR tests/test_agent_state_machine.py::test_agent_single_pass_final_answer
ERROR tests/test_agent_state_machine.py::test_agent_multi_step_tool_execution
ERROR tests/test_agent_state_machine.py::test_agent_max_steps_exceeded - NotI...
ERROR tests/test_agent_state_machine.py::test_agent_cycle_detection - NotImpl...
============================== 5 errors 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/ai-engineering/day-288-what-an-ai-agent-is
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_agent_state_machine.py::test_tool_registry_execution PASSED   [ 20%]
tests/test_agent_state_machine.py::test_agent_single_pass_final_answer PASSED [ 40%]
tests/test_agent_state_machine.py::test_agent_multi_step_tool_execution PASSED [ 60%]
tests/test_agent_state_machine.py::test_agent_max_steps_exceeded PASSED  [ 80%]
tests/test_agent_state_machine.py::test_agent_cycle_detection 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/ai-engineering/day-288-what-an-ai-agent-is
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_agent_state_machine.py::test_tool_registry_execution PASSED   [ 20%]
tests/test_agent_state_machine.py::test_agent_single_pass_final_answer PASSED [ 40%]
tests/test_agent_state_machine.py::test_agent_multi_step_tool_execution PASSED [ 60%]
tests/test_agent_state_machine.py::test_agent_max_steps_exceeded PASSED  [ 80%]
tests/test_agent_state_machine.py::test_agent_cycle_detection PASSED     [100%]

============================== 5 passed in 0.01s ===============================

Source files

examples/agent_state_machine.py (4651 bytes)
from enum import Enum
from typing import Dict, Any, List, Optional, Callable
import json

class AgentState(Enum):
    IDLE = "IDLE"
    THINKING = "THINKING"
    TOOL_CALL = "TOOL_CALL"
    OBSERVING = "OBSERVING"
    FINAL_ANSWER = "FINAL_ANSWER"
    MAX_STEPS_EXCEEDED = "MAX_STEPS_EXCEEDED"
    CYCLE_DETECTED = "CYCLE_DETECTED"
    ERROR = "ERROR"

class AgentTrajectory:
    def __init__(self):
        self.steps: List[Dict[str, Any]] = []
        
    def add_step(self, step_type: str, content: str, metadata: Optional[Dict] = None):
        self.steps.append({
            "step": len(self.steps) + 1,
            "type": step_type,
            "content": content,
            "metadata": metadata or {}
        })
        
    def get_scratchpad(self) -> str:
        lines = []
        for s in self.steps:
            lines.append(f"[{s['type'].upper()}]: {s['content']}")
        return "\n".join(lines)

class ToolRegistry:
    def __init__(self):
        self._tools: Dict[str, Callable[[str], str]] = {}
        
    def register(self, name: str, func: Callable[[str], str]):
        self._tools[name] = func
        
    def execute(self, name: str, arg: str) -> str:
        if name not in self._tools:
            return f"Error: Tool '{name}' not found in registry."
        try:
            return self._tools[name](arg)
        except Exception as e:
            return f"Error executing '{name}': {str(e)}"

class AgentRuntime:
    def __init__(self, tool_registry: ToolRegistry, max_steps: int = 5):
        self.state = AgentState.IDLE
        self.tools = tool_registry
        self.max_steps = max_steps
        self.trajectory = AgentTrajectory()
        self.transition_history: List[AgentState] = []
        
    def _set_state(self, new_state: AgentState):
        self.state = new_state
        self.transition_history.append(new_state)
        
    def step_loop(self, goal: str, mock_decisions: Optional[List[Dict[str, Any]]] = None) -> Dict[str, Any]:
        self._set_state(AgentState.THINKING)
        self.trajectory.add_step("goal", goal)
        step_count = 0
        dec_idx = 0
        last_action = None
        
        while self.state not in (AgentState.FINAL_ANSWER, AgentState.MAX_STEPS_EXCEEDED, AgentState.CYCLE_DETECTED, AgentState.ERROR):
            step_count += 1
            if step_count > self.max_steps:
                self._set_state(AgentState.MAX_STEPS_EXCEEDED)
                self.trajectory.add_step("system", "Max steps budget exceeded.")
                break
                
            # Fetch decision (either from scripted mock decisions or heuristic fallback)
            if mock_decisions and dec_idx < len(mock_decisions):
                decision = mock_decisions[dec_idx]
                dec_idx += 1
            else:
                decision = {"type": "final_answer", "content": f"Completed objective: {goal}"}
                
            if decision["type"] == "tool_call":
                current_action = f"{decision['tool']}:{decision.get('args', '')}"
                if current_action == last_action:
                    self._set_state(AgentState.CYCLE_DETECTED)
                    self.trajectory.add_step("system", f"Cycle detected for action: {current_action}")
                    break
                last_action = current_action
                
                self._set_state(AgentState.TOOL_CALL)
                self.trajectory.add_step("thought", decision.get("thought", "Executing tool."))
                self.trajectory.add_step("action", json.dumps({"tool": decision["tool"], "args": decision.get("args", "")}))
                
                # Execute tool
                self._set_state(AgentState.OBSERVING)
                obs = self.tools.execute(decision["tool"], decision.get("args", ""))
                self.trajectory.add_step("observation", obs)
                
                # Re-enter thinking state
                self._set_state(AgentState.THINKING)
                
            elif decision["type"] == "final_answer":
                self._set_state(AgentState.FINAL_ANSWER)
                self.trajectory.add_step("final_answer", decision["content"])
                break
            else:
                self._set_state(AgentState.ERROR)
                self.trajectory.add_step("error", f"Unknown decision type: {decision['type']}")
                break
                
        return {
            "final_state": self.state.value,
            "step_count": step_count,
            "transitions": [s.value for s in self.transition_history],
            "scratchpad": self.trajectory.get_scratchpad()
        }
metadata.yml (406 bytes)
lesson_id: D288
day: 288
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/agent_state_machine.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/agent_state_machine.py (1923 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.
"""

from enum import Enum
from typing import Dict, Any, List, Optional, Callable
import json

class AgentState(Enum):
    IDLE = 'IDLE'
    THINKING = 'THINKING'
    TOOL_CALL = 'TOOL_CALL'
    OBSERVING = 'OBSERVING'
    FINAL_ANSWER = 'FINAL_ANSWER'
    MAX_STEPS_EXCEEDED = 'MAX_STEPS_EXCEEDED'
    CYCLE_DETECTED = 'CYCLE_DETECTED'
    ERROR = 'ERROR'

class AgentTrajectory:

    def __init__(self):
        self.steps: List[Dict[str, Any]] = []

    def add_step(self, step_type: str, content: str, metadata: Optional[Dict]=None):
        raise NotImplementedError('TASK 1: implement add_step.')

    def get_scratchpad(self) -> str:
        raise NotImplementedError('TASK 2: implement get_scratchpad.')

class ToolRegistry:

    def __init__(self):
        self._tools: Dict[str, Callable[[str], str]] = {}

    def register(self, name: str, func: Callable[[str], str]):
        raise NotImplementedError('TASK 3: implement register.')

    def execute(self, name: str, arg: str) -> str:
        raise NotImplementedError('TASK 4: implement execute.')

class AgentRuntime:

    def __init__(self, tool_registry: ToolRegistry, max_steps: int=5):
        self.state = AgentState.IDLE
        self.tools = tool_registry
        self.max_steps = max_steps
        self.trajectory = AgentTrajectory()
        self.transition_history: List[AgentState] = []

    def _set_state(self, new_state: AgentState):
        raise NotImplementedError('TASK 5: implement _set_state.')

    def step_loop(self, goal: str, mock_decisions: Optional[List[Dict[str, Any]]]=None) -> Dict[str, Any]:
        raise NotImplementedError('TASK 6: implement step_loop.')
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_state_machine.py (2738 bytes)
import pytest
from examples.agent_state_machine import AgentState, AgentTrajectory, ToolRegistry, AgentRuntime

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

def mock_search(query: str) -> str:
    if "python" in query.lower():
        return "Python 3.14 includes performance enhancements."
    return "No records found."

@pytest.fixture
def registry():
    reg = ToolRegistry()
    reg.register("calculator", safe_calc)
    reg.register("search", mock_search)
    return reg

def test_tool_registry_execution(registry):
    assert registry.execute("calculator", "12 * 12") == "144"
    assert "Python 3.14" in registry.execute("search", "python release")
    assert "Error: Tool 'unknown' not found" in registry.execute("unknown", "")

def test_agent_single_pass_final_answer(registry):
    runtime = AgentRuntime(registry, max_steps=5)
    res = runtime.step_loop("Tell me a joke")
    assert res["final_state"] == AgentState.FINAL_ANSWER.value
    assert res["step_count"] == 1
    assert "THINKING" in res["transitions"]
    assert "FINAL_ANSWER" in res["transitions"]

def test_agent_multi_step_tool_execution(registry):
    runtime = AgentRuntime(registry, max_steps=5)
    mock_decisions = [
        {"type": "tool_call", "thought": "Calculate 40 + 2", "tool": "calculator", "args": "40 + 2"},
        {"type": "final_answer", "content": "The answer is 42"}
    ]
    res = runtime.step_loop("What is 40 + 2?", mock_decisions=mock_decisions)
    assert res["final_state"] == AgentState.FINAL_ANSWER.value
    assert res["step_count"] == 2
    assert "TOOL_CALL" in res["transitions"]
    assert "OBSERVING" in res["transitions"]
    assert "[OBSERVATION]: 42" in res["scratchpad"]

def test_agent_max_steps_exceeded(registry):
    runtime = AgentRuntime(registry, max_steps=2)
    mock_decisions = [
        {"type": "tool_call", "thought": "Step 1", "tool": "calculator", "args": "1+1"},
        {"type": "tool_call", "thought": "Step 2", "tool": "calculator", "args": "2+2"},
        {"type": "tool_call", "thought": "Step 3", "tool": "calculator", "args": "3+3"}
    ]
    res = runtime.step_loop("Infinite task", mock_decisions=mock_decisions)
    assert res["final_state"] == AgentState.MAX_STEPS_EXCEEDED.value

def test_agent_cycle_detection(registry):
    runtime = AgentRuntime(registry, max_steps=5)
    mock_decisions = [
        {"type": "tool_call", "thought": "Try calc", "tool": "calculator", "args": "100 / 0"},
        {"type": "tool_call", "thought": "Try same calc again", "tool": "calculator", "args": "100 / 0"}
    ]
    res = runtime.step_loop("Failing calculation", mock_decisions=mock_decisions)
    assert res["final_state"] == AgentState.CYCLE_DETECTED.value

Troubleshooting

Troubleshooting - Day 288

  1. Invalid State Transition: Transitions must adhere strictly to the lifecycle graph.
  2. KeyError in Tool Execution: Verify that tool names match registered identifiers in the registry.

Security notes

Security Considerations - Day 288

  1. Tool Execution Sandboxing: The calculator tool uses restricted evaluation scopes (__builtins__: None) to prevent arbitrary code execution vulnerabilities.
  2. Loop Exhaustion Protection: Strict maximum step boundaries ($K \le 10$) prevent denial-of-service and runaway token consumption.