AI Engineering: Agents and Applications › AI Agents › Day 288
Hands-on lab — Day 288: What an AI Agent Is
- ← Back to the Day 288 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-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-iswhen 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 skeletonexamples/agent_state_machine.py: Verified reference implementationtests/test_agent_state_machine.py: Test suiteexpected-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.
Navigation
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
- Invalid State Transition: Transitions must adhere strictly to the lifecycle graph.
- KeyError in Tool Execution: Verify that tool names match registered identifiers in the registry.
Security notes
Security Considerations - Day 288
- Tool Execution Sandboxing: The calculator tool uses restricted evaluation scopes (
__builtins__: None) to prevent arbitrary code execution vulnerabilities. - Loop Exhaustion Protection: Strict maximum step boundaries ($K \le 10$) prevent denial-of-service and runaway token consumption.