Project 5: Planner-Executor Agent

Build an agent that decomposes goals into tasks, executes them with dependency tracking, and replans when observations invalidate assumptions.

Quick Reference

Attribute Value
Difficulty Level 3: Advanced
Time Estimate 14–22 hours
Language Python or JavaScript
Prerequisites Projects 2–4, state management
Key Topics planning, task DAGs, replanning, execution traces

Learning Objectives

By completing this project, you will:

  1. Separate planning from execution in agent design.
  2. Represent plans as DAGs with dependencies.
  3. Trigger replanning when observations invalidate tasks.
  4. Preserve completed work across plan versions.
  5. Generate full execution traces for auditability.

The Core Question You’re Answering

“How does an agent recover when its assumptions about the world are wrong?”

This project forces replanning as a first-class behavior, not an edge case.

Concepts You Must Understand First

Concept Why It Matters Where to Learn
Task decomposition Break goals into steps Planning basics
DAG dependencies Valid execution order Graph theory
Replanning triggers Adapt to failures Agent architectures
Execution traces Debugging and auditing Systems observability

Theoretical Foundation

Plan-Execute Architecture

Goal -> Planner -> Task DAG -> Executor -> Observations
                ^                         |
                |------ Replan -----------|

The planner reasons globally; the executor acts locally. When reality diverges, the planner revises the DAG.

Project Specification

What You’ll Build

An agent that builds a plan, executes tasks, and replans when needed (e.g., missing directory, failed tool).

Functional Requirements

  1. Planner produces a task DAG
  2. Executor runs tasks in dependency order
  3. Replanning triggers on failures
  4. Plan versioning + history
  5. Execution trace with task statuses

Non-Functional Requirements

  • Deterministic replay
  • Clear replan rationale
  • Step budgets and max replans

Real World Outcome

Example execution:

Goal: Summarize TODOs in /src
Plan v1: list files -> scan TODOs -> report
Observation: /src missing
Replan v2: discover dirs -> scan app -> report

Trace report:

{
  "plan_versions": [
    {"version": 1, "status": "failed", "reason": "dir missing"},
    {"version": 2, "status": "success"}
  ],
  "tasks_completed": 5,
  "replans": 1
}

Architecture Overview

┌─────────────┐
│ Planner     │──────▶ Task DAG (vN)
└─────┬───────┘            │
      │ replan             ▼
┌─────────────┐     ┌─────────────┐
│ Replan Ctrl │◀────│ Executor    │
└─────────────┘     └─────────────┘

Implementation Guide

Phase 1: Task Model + Planner (4–6h)

  • Define task nodes and dependencies
  • Checkpoint: valid DAG generated

Phase 2: Executor (4–6h)

  • Run tasks in topological order
  • Checkpoint: tasks complete in order

Phase 3: Replanning (4–8h)

  • Detect failures and rebuild plan
  • Checkpoint: replan succeeds without losing progress

Common Pitfalls & Debugging

Pitfall Symptom Fix
Replan storms too many replans add max replan budget
Lost progress completed tasks reset merge plan state
Hidden failure cause unclear why replan log trigger reason

Interview Questions They’ll Ask

  1. Why separate planner and executor?
  2. How do you decide when to replan vs retry?
  3. How do you preserve completed work across replans?

Hints in Layers

  • Hint 1: Start with a static plan and fixed order.
  • Hint 2: Add dependency checks (DAG).
  • Hint 3: Detect failure and trigger replanning.
  • Hint 4: Preserve completed tasks across plan versions.

Learning Milestones

  1. Planner Works: task DAG produced.
  2. Executor Works: tasks run in correct order.
  3. Resilient: replans handle failures safely.

Submission / Completion Criteria

Minimum Completion

  • Planner + executor with task DAG

Full Completion

  • Replanning + trace logs

Excellence

  • Parallel execution + policy constraints

This guide was generated from project_based_ideas/AI_AGENTS_LLM_RAG/AI_AGENTS_PROJECTS.md.