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

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

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

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

  1. JSONDecodeError on Tool Args: Ensure arguments are formatted as valid JSON strings with double quotes.
  2. Infinite Loop: Check that max_iterations terminates execution if no Final Answer: is reached.

Security notes

Security Considerations - Day 289

  1. Argument Validation: All parsed tool arguments are verified against JSON format requirements before passing to execution functions.
  2. Safe Math Evaluator: Mathematical evaluation restricts Python builtins to eliminate code injection vectors.