Deep Agents — Reflection, Planning & Long-Term Memory

Why shallow agents fail on long tasks advanced

Picture handing a bright but forgetful intern a week-long project with no notebook, no checklist, and a memory that wipes every few hours. They'd start strong, do good work for an afternoon, then slowly lose the plot — re-deriving decisions they already made, forgetting the third of five requirements, and turning in whatever they happened to be holding when the clock ran out. That's not a talent problem; it's a process problem. A shallow ReAct agent has exactly this shape, and no amount of "just be smarter" in the prompt fixes it.

Here's the honest thing most tutorials skip: the plain loop isn't broken — it's simply operating past the horizon it was built for. A ReAct agent thinks, acts, observes and repeats, holding everything it knows in one growing context window. For a three-step task that's perfect. But "research this market and write a 20-page report" isn't three steps; it's dozens of sub-tasks stretched over hundreds of tool calls, and every one of them competes for the same finite window. The failures below aren't random bugs — they're the predictable consequences of asking one flat loop to carry a load it was never sized for.

The common mistake is to attack these symptoms with prompt tweaks — "remember your earlier findings," "double-check your work," "don't lose track of the goal." It feels like it should work, and it fails for a subtle reason: you're asking the model to do reliably, from inside a filling context, the very bookkeeping the context is too small to hold. The deep-agent answer is the opposite move — take that bookkeeping out of the model's head and into the system around it: a plan it re-reads, a critic that runs with fresh eyes, a store that outlives the window, and helpers that shoulder their own context. A plain ReAct agent (L1) works great for a few steps. Point it at "research this market and write a 20-page report" and it falls apart in predictable ways — the exact failures the four pillars fix.

Lab M4.1 · Planning as state advanced

Think about how you tackle a big move. You don't hold "pack the kitchen, cancel the internet, book the van, forward the mail" purely in your head and hope — you write it down, then work the list, crossing off items and adding the ones you forgot. The written list is doing something your memory can't: it's an external, re-readable record of intent that survives distraction. That is exactly what planning-as-state gives an agent, and it's why this is the first and highest-leverage pillar — the cheapest change with the biggest effect on a long run.

Why store the plan as data rather than just prompting for it? Because a plan that lives only in the model's reasoning is written in disappearing ink. As the context fills with tool results, that reasoning scrolls out of view, and the agent quietly substitutes a fuzzy sense of "roughly what I'm doing" for the crisp list it started with. Put the plan in a state field — an ordinary list of steps the code owns — and it stops being a memory and becomes a source of truth: the agent can re-read it at the top of every step, mark items done, and re-plan when reality diverges from expectation. The model does the thinking; the state holds the truth. That division of labour is the whole trick.

The common mistake is treating the plan as write-once — generate a nice numbered list at the start, then never look at it again. A stale plan is almost worse than none, because it lulls you into thinking the agent is on track while it improvises. A good plan is a living field: read it, act on the top open item, record the outcome, and if the task turned out different than expected, rewrite the remaining steps. The tiny loop below has exactly that spine — one node writes the plan, another checks whether any steps remain — and everything richer (sub-tasks, re-planning) is just more logic hung on this skeleton. The simplest, highest-leverage pillar: give the agent an explicit to-do list in its state that it writes first and updates as it goes. It's L1's plan-and-execute, made durable via L4 state.

plan.pyfrom typing import TypedDict, Annotated
from langgraph.graph import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]
    plan: list[str]        # the to-do list, e.g. ["research X", "draft", "review"]
    done: list[str]        # completed steps, for progress & self-check

def make_plan(s):
    steps = model.invoke(f"Break this task into 3-6 concrete steps:\n{s['messages'][-1]}")
    return {"plan": _parse_steps(steps), "done": []}

def next_step(s) -> str:
    return END if not s["plan"] else "execute"   # plan empty → finished

Lab M4.2 · Reflection advanced

Every writer knows the trap: the draft you just wrote always reads better to you than it is. You're too close to it — you see what you meant, not what's on the page, so the missing caveat and the half-answered question slide right past. The fix professionals use isn't "try harder"; it's to put the work down and come back with fresh eyes, or better yet hand it to an editor who wasn't in your head while you wrote. Reflection is that editor, built into the agent: a second pass that critiques the draft against the requirements before anyone calls it finished.

Why this needs to be a distinct step, and why a fresh critic matters. If you simply ask the same reasoning that produced the draft "is this good?", you tend to get a rationalization — the model defends the choices it just made, because they're right there in its context looking justified. The stronger move is to run the critique with a separate prompt and a clean framing ("list concrete problems, or reply PASS"), so it's genuinely evaluating the artifact rather than protecting its author. That's the same generate-then-critique split you met in L1, now expressed as a bounded loop: critique, and if there are real problems, feed them back to the generator and try again.

The common mistake — and it's the one that bites hardest — is leaving the loop unbounded. "Keep revising until it's perfect" sounds diligent and is actually a token bonfire: past a pass or two the critic runs out of substantive faults and starts nitpicking, or worse, second-guesses good decisions and makes the draft worse. Reflection has a genuine sweet spot, and you enforce it with a hard cap (two revisions is a sound default) plus an explicit PASS exit. The snippet below shows exactly that shape — a critique that can say PASS, a revision counter that forces a stop, and a graph edge that routes "revise" back to the generator and "finish" to the end. Before finalizing, a deep agent critiques its own work and revises — L1's reflection architecture, as a bounded loop (L5). A fresh-context critic catches what the generator missed.

END = "__end__"          # sentinel used by graph examples
class _g_t:
    add_conditional_edges = 'demo'
    def add_conditional_edges(self, *a, **k): return 'demo'
    def __getattr__(self, k): return 'demo'
g = _g_t()
class _model_t:
    invoke = 'demo'
    def invoke(self, *a, **k): return 'demo'
    def __getattr__(self, k): return 'demo'
model = _model_t()

reflect.pydef reflect(s) -> str:
    """Critique the draft against the plan; decide revise or finish."""
    critique = model.invoke(
        f"Critique this draft against the requirements. "
        f"List concrete problems, or reply 'PASS'.\n\n{s['draft']}").content
    if "PASS" in critique or s["revisions"] >= 2:   # bound it — quality has diminishing returns
        return "finish"
    return "revise"   # feed the critique back to the generator

g.add_conditional_edges("reflect", reflect, {"revise": "generate", "finish": END})

Lab M4.3 · Long-term memory expert

Your working memory holds about seven things; your notebook holds everything. Nobody solves a hard problem by trying to keep every fact suspended in their head at once — you jot the important findings down and free your mind for the next step, trusting you can look the notes back up when you need them. An agent's context window is its working memory, and it's just as finite: on a long task the earliest, often most important, findings get shoved out to make room for the latest tool output. The model didn't decide those facts were unimportant — the window simply ran out of room. Long-term memory is the notebook that fixes this.

The key distinction is short-term versus long-term, and beginners routinely conflate them. Short-term memory is the messages currently in context (L2/L4) — fast, automatic, and doomed to be overwritten. Long-term memory is an external store — a file, a database, or a vector store — that the agent deliberately writes to and later recalls from as a tool. The crucial property is durability: what you save there survives not just the filling window but the end of the run entirely, so a research agent can pick up tomorrow where it left off today. Mechanically it reuses machinery you already have: a durable backend (L5's checkpointer or a real DB) plus semantic recall (M3's retrieval) to fetch the right note by meaning rather than exact wording.

The common mistake is treating memory as a dumping ground — saving whole raw transcripts, every tool result, the full conversation "just in case." That poisons the well: recall then returns pages of noise, costs more tokens, and buries the one fact you actually needed. The real skill here isn't the plumbing (the lab below is only a few lines) — it's the judgement about what deserves to be remembered. Save distilled decisions and findings — "the user prefers concise answers," "source X contradicts the client's claim" — not the transcript that produced them. A good memory is curated, not comprehensive. The context window is finite; a long task overflows it. Long-term memory offloads durable facts to external storage the agent reads and writes as a tool — surviving both the context window and the run itself.

memory.pyfrom langchain_core.tools import tool

@tool
def save_memory(key: str, value: str) -> str:
    """Save a durable fact for later. Use for findings you'll need after the context fills."""
    store.put(key, value)                 # file / DB / vector store — outlives this run
    return "saved"

@tool
def recall_memory(query: str) -> str:
    """Retrieve durable facts saved earlier."""
    return store.search(query)             # semantic recall (M3 retrieval)

agent = create_react_agent(model, tools=[save_memory, recall_memory, ...])

Sub-agents: focus through isolation expert

A good manager doesn't sit in on every phone call their team makes. They hand a report the brief — "check these three sources and tell me what you find" — and get back a one-paragraph summary, not a transcript of every dead end, wrong turn and re-read along the way. If the manager did absorb all that raw detail from five reports at once, their own head would be so cluttered they'd lose sight of the project. Delegation isn't just about doing more at once; it's about protecting the manager's attention. Sub-agents are that same instinct applied to context windows.

This is why the framing "context hygiene, not just parallelism" matters, and it's the point most people miss. The obvious reason to spawn sub-agents is speed — investigate three sources concurrently instead of one after another. Real, but secondary. The deeper win is isolation: a sub-agent researching one source burns through dozens of tool calls, false starts and half-relevant snippets inside its own context, then hands the orchestrator only the clean, distilled result. The parent's window never sees the mess. So the main agent's context stays focused on the plan and the findings that matter, instead of drowning in the intermediate noise of every subtask — which is exactly the failure mode a single flat loop hits. It's the supervisor topology from L1/M1, reused wholesale.

The common mistake is delegating for the sake of delegating. Spinning up a sub-agent for a trivial one-line step adds a whole extra LLM round-trip, its own failure surface, and coordination overhead — all to isolate context that was never going to overflow. Reach for a sub-agent when a subtask is both focused (a clean, self-contained brief) and context-heavy (it'll generate a lot of intermediate work you don't want in the parent). Verifying one claim across ten documents: yes. Formatting a date: no. The fourth pillar reuses M1/M2 directly. A deep agent spawns a sub-agent for a focused subtask (research one source, verify one claim); the sub-agent burns its own context and returns only the result, keeping the main agent's context clean and on-plan.

Putting the four pillars together expert

You've now built each pillar in isolation — but a deep agent is the composition, not the parts. The pieces reinforce each other in a loop: the plan decides what to do next; executing a step may spawn a sub-agent for the heavy lifting; whatever it learns gets written to long-term memory; the item is marked done and the plan re-checked; and before anything ships, reflection critiques the result. Round and round until the plan is drained. Nothing here is new — it's L1's plan-execute and reflection, L4's state, L5's persistence and cycles, and M1/M2's sub-agents, snapped together into one graph. "Deep agent" names the assembly, not a new framework.

The most important thing to internalize is the honest cost of this, because the skeleton makes it look free. Every pillar you add multiplies LLM calls, latency, and the surface where things can go wrong — a prompt injection in one retrieved source (T1, M3), a sub-agent that returns garbage, a reflection loop that runs long. The seasoned move is restraint: start with the shallow ReAct loop and add a pillar only when the task demonstrably fails without it. Most problems need one or two pillars, not all four; reaching for the full stack by default is over-engineering that costs real money and reliability. And notice the one non-negotiable in the skeleton below: no matter how sophisticated the agent grows, every irreversible action still passes the L5 human-in-the-loop safety gate. Depth buys capability; it never buys a pass on safety. A deep agent is a LangGraph graph that wires all four into one loop:

Common pitfalls expert

Exercises expert

PILLARS = {
    "planning (to-do as state)": "drift / forgetting the goal mid-task",
    "reflection (critique loop)": "shipping a first draft with obvious errors",
    "long-term memory":          "re-learning facts every run / losing context",
    "sub-agents":                "one context window overloaded with everything",
}
for pillar, fixes in PILLARS.items():
    print(f"{pillar:<28} fixes -> {fixes}")

class Plan:
    def __init__(self, tasks):
        self.tasks = [{"task": t, "done": False} for t in tasks]
    def next_open(self):
        for t in self.tasks:
            if not t["done"]:
                return t["task"]
        return None
    def complete(self, task):
        for t in self.tasks:
            if t["task"] == task:
                t["done"] = True
    def progress(self):
        done = sum(t["done"] for t in self.tasks)
        return f"{done}/{len(self.tasks)} done; next: {self.next_open()}"

p = Plan(["gather sources", "draft", "review", "publish"])
print(p.progress())
p.complete("gather sources"); p.complete("draft")
print(p.progress())

def critique(draft):
    problems = []
    if len(draft.split()) < 5:      problems.append("too short")
    if "TODO" in draft:            problems.append("has placeholder")
    if not draft.endswith("."):    problems.append("no closing punctuation")
    return problems

def revise(draft, problems):
    if "too short" in problems:        draft += " with more detail added here"
    if "has placeholder" in problems:  draft = draft.replace("TODO", "the result")
    if "no closing punctuation" in problems and not draft.endswith("."):
        draft += "."
    return draft

def reflect(draft, max_passes=3):
    for p in range(1, max_passes + 1):
        problems = critique(draft)
        if not problems:
            return f"PASS on pass {p}: {draft!r}"
        draft = revise(draft, problems)
    return f"stop after {max_passes} passes (best effort): {draft!r}"

print(reflect("TODO"))

class Memory:
    def __init__(self):
        self.facts = []               # would be a vector store in production
    def save(self, fact):
        self.facts.append(fact)
    def recall(self, query, k=2):
        qt = set(query.lower().split())
        scored = [(len(qt & set(f.lower().split())), f) for f in self.facts]
        scored = [s for s in scored if s[0] > 0]
        return [f for _, f in sorted(scored, reverse=True)[:k]]

mem = Memory()
mem.save("The user prefers concise, bulleted answers.")
mem.save("The user's timezone is IST.")
mem.save("Project deadline is the 30th.")
print(mem.recall("what answer format does the user like"))
print(mem.recall("when is the deadline"))

def sub_agent(name, task, context):
    # isolated: only sees the slice it needs, returns a compact result
    return {"agent": name, "task": task,
            "result": f"[{name}] done '{task}' using {len(context)} ctx items"}

def manager(goal, subtasks, shared_ctx):
    results = []
    for name, task, needed_keys in subtasks:
        isolated = {k: shared_ctx[k] for k in needed_keys if k in shared_ctx}
        results.append(sub_agent(name, task, isolated))
    return {"goal": goal, "merged": [r["result"] for r in results]}

ctx = {"sources": [1, 2, 3], "style": "concise", "budget": 100}
plan = [("researcher", "gather facts", ["sources"]),
        ("writer",     "draft summary", ["style"])]
import json
print(json.dumps(manager("write a brief", plan, ctx), indent=2))

def deep_agent(goal, tasks):
    plan = [{"task": t, "done": False} for t in tasks]
    memory, transcript = [], []
    for step in plan:
        # 1) plan: take next task  2) sub-agent: do it (isolated)
        raw = f"output for '{step['task']}'"
        # 3) reflect: one bounded critique/revise pass
        good = raw if raw.endswith("'") else raw + "."
        # 4) memory: persist a learning
        memory.append(f"learned: {step['task']} completed")
        step["done"] = True
        transcript.append({"task": step["task"], "result": good})
    return {"goal": goal, "done": all(s["done"] for s in plan),
            "steps": transcript, "memory": memory}

import json
print(json.dumps(deep_agent("write a report", ["research", "draft", "review"]),
                 indent=2))

# needs the SDK -- the same idea with LangGraph's prebuilt agent (documented API):
# from langgraph.prebuilt import create_react_agent
# from langgraph.checkpoint.memory import MemorySaver
# agent = create_react_agent(model, tools=[plan_tool, memory_tool, subagent_tool],
#                            checkpointer=MemorySaver())   # persistence = long-term memory
# agent.invoke({"messages": [("user", "write a report")]},
#              config={"configurable": {"thread_id": "run-1"}})

Knowledge check check yourself