feat(examples/python): add planning-vs-reactive runnable example

Author: AgentPatterns

examples/foundations/planning-vs-reactive/python/README.md

@@ -0,0 +1,56 @@
+# Planning vs Reactive - Python Implementation
+
+Runnable learning example that compares two agent strategies on the same task:
+planning-first execution vs reactive step-by-step decisions.
+
+---
+
+## Quick start
+
+```bash
+# (optional) create venv
+python -m venv .venv && source .venv/bin/activate
+
+# install dependencies (none required, command kept for consistency)
+pip install -r requirements.txt
+
+# run the comparison
+python main.py
+```
+
+## Full walkthrough
+
+Read the concept article:
+https://agentpatterns.tech/en/foundations/planning-vs-reactive
+
+## What's inside
+
+- Deterministic flaky tools (orders fails once, then succeeds)
+- Planning agent with explicit `create_plan -> execute -> replan`
+- Reactive agent that chooses the next action from current state
+- Side-by-side trace output for easy comparison
+
+## Project layout
+
+```text
+examples/
+  foundations/
+    planning-vs-reactive/
+      python/
+        README.md
+        main.py
+        llm.py
+        planning_agent.py
+        reactive_agent.py
+        tools.py
+        requirements.txt
+```
+
+## Notes
+
+- This code is intentionally simple for learning.
+- The website provides multilingual explanation and context.
+
+## License
+
+MIT

examples/foundations/planning-vs-reactive/python/llm.py

@@ -0,0 +1,45 @@
+from typing import Any
+
+
+DEFAULT_PLAN = ["fetch_profile", "fetch_orders", "fetch_balance", "build_summary"]
+
+
+def create_plan(task: str) -> list[str]:
+    # Learning version: fixed starter plan keeps behavior easy to reason about.
+    _ = task
+    return DEFAULT_PLAN.copy()
+
+
+def replan(task: str, state: dict[str, Any], failed_step: str, error: str) -> list[str]:
+    # Learning version: rebuild plan from missing data in state.
+    _ = task, failed_step, error
+    remaining: list[str] = []
+
+    if "profile" not in state:
+        remaining.append("fetch_profile")
+    if "orders" not in state:
+        remaining.append("fetch_orders")
+    if "balance" not in state:
+        remaining.append("fetch_balance")
+    if "summary" not in state:
+        remaining.append("build_summary")
+
+    return remaining
+
+
+def choose_next_action(task: str, state: dict[str, Any]) -> str:
+    # Learning version: one-step-at-a-time policy driven by current state.
+    _ = task
+
+    if "profile" not in state:
+        return "fetch_profile"
+
+    # If orders just failed, fetch other missing data first.
+    if state.get("last_error") == "orders_api_timeout" and "balance" not in state:
+        return "fetch_balance"
+
+    if "orders" not in state:
+        return "fetch_orders"
+    if "balance" not in state:
+        return "fetch_balance"
+    return "build_summary"

examples/foundations/planning-vs-reactive/python/main.py

@@ -0,0 +1,26 @@
+from planning_agent import run_planning_agent
+from reactive_agent import run_reactive_agent
+
+TASK = "Prepare a short account summary for user_id=42 with profile, orders, and balance."
+USER_ID = 42
+
+
+def print_result(result: dict) -> None:
+    print(f"\n=== {result['mode'].upper()} ===")
+    print(f"done={result['done']} | steps={result['steps']}")
+    print("summary:", result["state"].get("summary"))
+    print("\ntrace:")
+    for line in result["trace"]:
+        print(" ", line)
+
+
+def main() -> None:
+    planning = run_planning_agent(task=TASK, user_id=USER_ID)
+    reactive = run_reactive_agent(task=TASK, user_id=USER_ID)
+
+    print_result(planning)
+    print_result(reactive)
+
+
+if __name__ == "__main__":
+    main()

examples/foundations/planning-vs-reactive/python/planning_agent.py

@@ -0,0 +1,47 @@
+from typing import Any
+
+from llm import create_plan, replan
+from tools import build_summary, fetch_balance, fetch_orders, fetch_profile, make_initial_state
+
+TOOLS = {
+    "fetch_profile": fetch_profile,
+    "fetch_orders": fetch_orders,
+    "fetch_balance": fetch_balance,
+    "build_summary": build_summary,
+}
+
+
+def run_planning_agent(task: str, user_id: int, max_steps: int = 8) -> dict[str, Any]:
+    state = make_initial_state(user_id)
+    plan = create_plan(task)
+    trace: list[str] = [f"Initial plan: {plan}"]
+
+    step = 0
+    while plan and step < max_steps:
+        action = plan.pop(0)
+        step += 1
+        trace.append(f"[{step}] action={action}")
+
+        tool = TOOLS.get(action)
+        if not tool:
+            trace.append(f"unknown_action={action}")
+            state["last_error"] = f"unknown_action:{action}"
+            continue
+
+        result = tool(state)
+        trace.append(f"result={result}")
+
+        if "error" in result:
+            state["last_error"] = result["error"]
+            trace.append("planning: replan after failure")
+            plan = replan(task, state, failed_step=action, error=result["error"])
+            trace.append(f"new_plan={plan}")
+            continue
+
+        state.update(result)
+        state.pop("last_error", None)
+
+        if "summary" in state:
+            return {"mode": "planning", "done": True, "steps": step, "state": state, "trace": trace}
+
+    return {"mode": "planning", "done": False, "steps": step, "state": state, "trace": trace}

examples/foundations/planning-vs-reactive/python/reactive_agent.py

@@ -0,0 +1,41 @@
+from typing import Any
+
+from llm import choose_next_action
+from tools import build_summary, fetch_balance, fetch_orders, fetch_profile, make_initial_state
+
+TOOLS = {
+    "fetch_profile": fetch_profile,
+    "fetch_orders": fetch_orders,
+    "fetch_balance": fetch_balance,
+    "build_summary": build_summary,
+}
+
+
+def run_reactive_agent(task: str, user_id: int, max_steps: int = 8) -> dict[str, Any]:
+    state = make_initial_state(user_id)
+    trace: list[str] = []
+
+    for step in range(1, max_steps + 1):
+        if "summary" in state:
+            return {"mode": "reactive", "done": True, "steps": step - 1, "state": state, "trace": trace}
+
+        action = choose_next_action(task, state)
+        trace.append(f"[{step}] action={action}")
+
+        tool = TOOLS.get(action)
+        if not tool:
+            trace.append(f"unknown_action={action}")
+            state["last_error"] = f"unknown_action:{action}"
+            continue
+
+        result = tool(state)
+        trace.append(f"result={result}")
+
+        if "error" in result:
+            state["last_error"] = result["error"]
+            continue
+
+        state.update(result)
+        state.pop("last_error", None)
+
+    return {"mode": "reactive", "done": False, "steps": max_steps, "state": state, "trace": trace}

examples/foundations/planning-vs-reactive/python/requirements.txt

@@ -0,0 +1 @@
+# No external dependencies for this learning example.

examples/foundations/planning-vs-reactive/python/tools.py

@@ -0,0 +1,61 @@
+from typing import Any
+
+
+def make_initial_state(user_id: int) -> dict[str, Any]:
+    # Deterministic flake config for teaching: orders fails once, then succeeds.
+    return {
+        "user_id": user_id,
+        "_flaky": {
+            "orders_failures_left": 1,
+            "balance_failures_left": 0,
+        },
+    }
+
+
+def fetch_profile(state: dict[str, Any]) -> dict[str, Any]:
+    user_id = state["user_id"]
+    return {
+        "profile": {
+            "user_id": user_id,
+            "name": "Anna",
+            "tier": "pro",
+        }
+    }
+
+
+def fetch_orders(state: dict[str, Any]) -> dict[str, Any]:
+    flaky = state["_flaky"]
+    if flaky["orders_failures_left"] > 0:
+        flaky["orders_failures_left"] -= 1
+        return {"error": "orders_api_timeout"}
+
+    return {
+        "orders": [
+            {"id": "ord-1001", "total": 49.9, "status": "paid"},
+            {"id": "ord-1002", "total": 19.0, "status": "shipped"},
+        ]
+    }
+
+
+def fetch_balance(state: dict[str, Any]) -> dict[str, Any]:
+    flaky = state["_flaky"]
+    if flaky["balance_failures_left"] > 0:
+        flaky["balance_failures_left"] -= 1
+        return {"error": "billing_api_unavailable"}
+
+    return {"balance": {"currency": "USD", "value": 128.4}}
+
+
+def build_summary(state: dict[str, Any]) -> dict[str, Any]:
+    profile = state.get("profile")
+    orders = state.get("orders")
+    balance = state.get("balance")
+
+    if not profile or not orders or not balance:
+        return {"error": "not_enough_data_for_summary"}
+
+    text = (
+        f"User {profile['name']} ({profile['tier']}) has "
+        f"{len(orders)} recent orders and balance {balance['value']} {balance['currency']}."
+    )
+    return {"summary": text}