AI Engineering: Agents and Applications › AI Agents › Day 289
Hands-on lab — Day 289: The Agent Loop: Reason, Act, Observe
- ← Back to the Day 289 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-289-the-agent-loop-reason-act-observe/
Commands
Setup
pip install -r requirements/requirements.txt Run
python examples/react_engine.py Test
bash tests/run_tests.sh File tree
examples/react_engine.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/react_engine.py tests/run_tests.sh tests/test_react_engine.py troubleshooting.md
Lab README
Day 289 Lab: The Agent Loop: Reason, Act, Observe
Lesson
- Lesson title: The Agent Loop: Reason, Act, Observe
- Day number: 289 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-289-the-agent-loop-reason-act-observe
- 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-289-the-agent-loop-reason-act-observewhen the site is running.
Purpose
Implement an autonomous ReAct (Reason + Act) execution loop with regex token stream parsing, self-healing JSON error observation feedback, and deterministic termination predicates.
Learning objectives
- Deconstruct the ReAct Thought-Action-Observation execution cycle.
- Build regex-based parsers extracting structured Action and Action Input payloads.
- Implement self-healing error observation injection for malformed parameters.
- Enforce deterministic termination on Final Answer extraction.
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/react_engine.py: Starter implementation skeletonexamples/react_engine.py: Verified reference implementationtests/test_react_engine.py: Test suiteexpected-output/: Captured execution logs
How to run
python3 examples/react_engine.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: 289 of 365
Expected output
FIELDS.md
# Measured Values
- `max_iterations`: 6
- `scratchpad_steps`: 3
examples-run.txt
measured-values.txt
max_iterations=6
scratchpad_steps=3
run-output.txt
starter-run.txt
An untouched starter fails the suite. Captured from a real run:
self = <examples.react_engine.ReActEngine object at 0x1091eab10>
name = 'calculate', func = <function calc_fn at 0x1092147d0>
def register_tool(self, name: str, func: Callable):
> raise NotImplementedError('TASK 1: implement register_tool.')
E NotImplementedError: TASK 1: implement register_tool.
examples/react_engine.py:20: NotImplementedError
=========================== short test summary info ============================
ERROR tests/test_react_engine.py::test_parse_final_answer - NotImplementedErr...
ERROR tests/test_react_engine.py::test_parse_and_execute_valid_action - NotIm...
ERROR tests/test_react_engine.py::test_syntax_error_handling - NotImplemented...
ERROR tests/test_react_engine.py::test_unknown_tool_handling - NotImplemented...
ERROR tests/test_react_engine.py::test_full_trajectory_accumulation - 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-289-the-agent-loop-reason-act-observe
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items
tests/test_react_engine.py::test_parse_final_answer PASSED [ 20%]
tests/test_react_engine.py::test_parse_and_execute_valid_action PASSED [ 40%]
tests/test_react_engine.py::test_syntax_error_handling PASSED [ 60%]
tests/test_react_engine.py::test_unknown_tool_handling PASSED [ 80%]
tests/test_react_engine.py::test_full_trajectory_accumulation 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-289-the-agent-loop-reason-act-observe
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items
tests/test_react_engine.py::test_parse_final_answer PASSED [ 20%]
tests/test_react_engine.py::test_parse_and_execute_valid_action PASSED [ 40%]
tests/test_react_engine.py::test_syntax_error_handling PASSED [ 60%]
tests/test_react_engine.py::test_unknown_tool_handling PASSED [ 80%]
tests/test_react_engine.py::test_full_trajectory_accumulation PASSED [100%]
============================== 5 passed in 0.01s ===============================
Source files
examples/react_engine.py (3434 bytes)
import re
import json
from typing import Dict, Any, Tuple, Optional, Callable
class ReActEngine:
def __init__(self, tools: Optional[Dict[str, Callable]] = None, max_iterations: int = 6):
self.tools = tools or {}
self.max_iterations = max_iterations
self.scratchpad: list = []
def register_tool(self, name: str, func: Callable):
self.tools[name] = func
def parse_generation(self, text: str) -> Tuple[str, str, Optional[Dict[str, Any]], Optional[str]]:
# Extract Thought
thought_match = re.search(r"Thought:\s*(.*?)(?=\nAction:|\nFinal Answer:|$)", text, re.DOTALL)
thought = thought_match.group(1).strip() if thought_match else ""
# Check for Final Answer
if "Final Answer:" in text:
final_match = re.search(r"Final Answer:\s*(.*)", text, re.DOTALL)
final_answer = final_match.group(1).strip() if final_match else text.strip()
return "FINAL", thought, None, final_answer
# Extract Action
action_match = re.search(r"Action:\s*([a-zA-Z0-9_]+)\s*\((.*)\)", text, re.DOTALL)
if action_match:
tool_name = action_match.group(1).strip()
args_raw = action_match.group(2).strip()
try:
args = json.loads(args_raw) if args_raw else {}
return "ACTION", thought, {"tool": tool_name, "args": args}, None
except json.JSONDecodeError as err:
return "SYNTAX_ERROR", thought, {"tool": tool_name, "raw": args_raw, "error": str(err)}, None
return "UNKNOWN", thought, None, None
def execute_step(self, mock_llm_response: str) -> Dict[str, Any]:
step_type, thought, action_data, final_ans = self.parse_generation(mock_llm_response)
if step_type == "FINAL":
self.scratchpad.append(f"Thought: {thought}\nFinal Answer: {final_ans}")
return {"status": "COMPLETE", "final_answer": final_ans, "thought": thought}
elif step_type == "ACTION":
tool = action_data["tool"]
args = action_data["args"]
if tool in self.tools:
try:
res = self.tools[tool](**args)
obs = f"Observation: {res}"
except Exception as e:
obs = f"Observation: Error executing tool '{tool}': {str(e)}"
else:
obs = f"Observation: Tool '{tool}' does not exist in registry."
self.scratchpad.append(f"Thought: {thought}\nAction: {tool}({json.dumps(args)})\n{obs}")
return {"status": "CONTINUE", "thought": thought, "tool": tool, "observation": obs}
elif step_type == "SYNTAX_ERROR":
obs = f"Observation: JSON parse error in action parameters: {action_data['error']}. Please re-emit with valid JSON."
self.scratchpad.append(f"Thought: {thought}\nAction: {action_data['tool']}({action_data['raw']})\n{obs}")
return {"status": "CONTINUE", "thought": thought, "observation": obs}
else:
obs = "Observation: Format error. Expected 'Action: tool_name(args)' or 'Final Answer: answer'."
self.scratchpad.append(f"Thought: {thought}\n{obs}")
return {"status": "CONTINUE", "thought": thought, "observation": obs}
metadata.yml (399 bytes)
lesson_id: D289
day: 289
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/react_engine.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/react_engine.py (1023 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 re
import json
from typing import Dict, Any, Tuple, Optional, Callable
class ReActEngine:
def __init__(self, tools: Optional[Dict[str, Callable]]=None, max_iterations: int=6):
self.tools = tools or {}
self.max_iterations = max_iterations
self.scratchpad: list = []
def register_tool(self, name: str, func: Callable):
raise NotImplementedError('TASK 1: implement register_tool.')
def parse_generation(self, text: str) -> Tuple[str, str, Optional[Dict[str, Any]], Optional[str]]:
raise NotImplementedError('TASK 2: implement parse_generation.')
def execute_step(self, mock_llm_response: str) -> Dict[str, Any]:
raise NotImplementedError('TASK 3: implement execute_step.')
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_react_engine.py (2158 bytes)
import pytest
from examples.react_engine import ReActEngine
def calc_fn(expr: str) -> str:
return str(eval(expr, {"__builtins__": None}, {}))
def search_fn(query: str) -> str:
if "seattle" in query.lower():
return "Seattle population is 750000"
return "No match found."
@pytest.fixture
def engine():
eng = ReActEngine()
eng.register_tool("calculate", calc_fn)
eng.register_tool("search_kb", search_fn)
return eng
def test_parse_final_answer(engine):
resp = "Thought: I know the answer directly.\nFinal Answer: Paris is the capital of France."
res = engine.execute_step(resp)
assert res["status"] == "COMPLETE"
assert res["final_answer"] == "Paris is the capital of France."
assert "Paris" in res["thought"] or "directly" in res["thought"]
def test_parse_and_execute_valid_action(engine):
resp = 'Thought: Search for Seattle population.\nAction: search_kb({"query": "Seattle"})'
res = engine.execute_step(resp)
assert res["status"] == "CONTINUE"
assert res["tool"] == "search_kb"
assert "750000" in res["observation"]
def test_syntax_error_handling(engine):
# Malformed JSON with unquoted key and trailing comma
resp = 'Thought: Run calculation.\nAction: calculate({expr: 100 + 50,})'
res = engine.execute_step(resp)
assert res["status"] == "CONTINUE"
assert "JSON parse error" in res["observation"]
def test_unknown_tool_handling(engine):
resp = 'Thought: Use missing tool.\nAction: nonexistent_tool({"data": 123})'
res = engine.execute_step(resp)
assert res["status"] == "CONTINUE"
assert "does not exist in registry" in res["observation"]
def test_full_trajectory_accumulation(engine):
s1 = 'Thought: Need Seattle pop.\nAction: search_kb({"query": "Seattle"})'
engine.execute_step(s1)
s2 = 'Thought: Need 20% growth.\nAction: calculate({"expr": "750000 * 1.20"})'
engine.execute_step(s2)
s3 = 'Thought: Done.\nFinal Answer: Projected population is 900,000.'
res3 = engine.execute_step(s3)
assert res3["status"] == "COMPLETE"
assert len(engine.scratchpad) == 3
assert "900000" in engine.scratchpad[1]
Troubleshooting
Troubleshooting - Day 289
- JSONDecodeError on Tool Args: Ensure arguments are formatted as valid JSON strings with double quotes.
- Infinite Loop: Check that
max_iterationsterminates execution if noFinal Answer:is reached.
Security notes
Security Considerations - Day 289
- Argument Validation: All parsed tool arguments are verified against JSON format requirements before passing to execution functions.
- Safe Math Evaluator: Mathematical evaluation restricts Python builtins to eliminate code injection vectors.