deer-flow/backend/docs/plan_mode_usage.md

Plan Mode with TodoList Middleware

This document describes how to enable and use the Plan Mode feature with TodoList middleware in DeerFlow 2.0.

Overview

Plan Mode adds a TodoList middleware to the agent, which provides a write_todos tool that helps the agent:

• Break down complex tasks into smaller, manageable steps
• Track progress as work progresses
• Provide visibility to users about what's being done

The TodoList middleware is built on LangChain's TodoListMiddleware.

Configuration

Enabling Plan Mode

Plan mode is controlled via runtime configuration through the is_plan_mode parameter in the configurable section of RunnableConfig. This allows you to dynamically enable or disable plan mode on a per-request basis.

from langchain_core.runnables import RunnableConfig
from deerflow.agents.lead_agent.agent import make_lead_agent

# Enable plan mode via runtime configuration
config = RunnableConfig(
    configurable={
        "thread_id": "example-thread",
        "thinking_enabled": True,
        "is_plan_mode": True,  # Enable plan mode
    }
)

# Create agent with plan mode enabled
agent = make_lead_agent(config)

Configuration Options

• is_plan_mode (bool): Whether to enable plan mode with TodoList middleware. Default: False
  • Pass via config.get("configurable", {}).get("is_plan_mode", False)
  • Can be set dynamically for each agent invocation
  • No global configuration needed

Default Behavior

When plan mode is enabled with default settings, the agent will have access to a write_todos tool with the following behavior:

When to Use TodoList

The agent will use the todo list for:

1. Complex multi-step tasks (3+ distinct steps)
2. Non-trivial tasks requiring careful planning
3. When user explicitly requests a todo list
4. When user provides multiple tasks

When NOT to Use TodoList

The agent will skip using the todo list for:

1. Single, straightforward tasks
2. Trivial tasks (< 3 steps)
3. Purely conversational or informational requests

Task States

• pending: Task not yet started
• in_progress: Currently working on (can have multiple parallel tasks)
• completed: Task finished successfully

Usage Examples

Basic Usage

from langchain_core.runnables import RunnableConfig
from deerflow.agents.lead_agent.agent import make_lead_agent

# Create agent with plan mode ENABLED
config_with_plan_mode = RunnableConfig(
    configurable={
        "thread_id": "example-thread",
        "thinking_enabled": True,
        "is_plan_mode": True,  # TodoList middleware will be added
    }
)
agent_with_todos = make_lead_agent(config_with_plan_mode)

# Create agent with plan mode DISABLED (default)
config_without_plan_mode = RunnableConfig(
    configurable={
        "thread_id": "another-thread",
        "thinking_enabled": True,
        "is_plan_mode": False,  # No TodoList middleware
    }
)
agent_without_todos = make_lead_agent(config_without_plan_mode)

Dynamic Plan Mode per Request

You can enable/disable plan mode dynamically for different conversations or tasks:

from langchain_core.runnables import RunnableConfig
from deerflow.agents.lead_agent.agent import make_lead_agent

def create_agent_for_task(task_complexity: str):
    """Create agent with plan mode based on task complexity."""
    is_complex = task_complexity in ["high", "very_high"]

    config = RunnableConfig(
        configurable={
            "thread_id": f"task-{task_complexity}",
            "thinking_enabled": True,
            "is_plan_mode": is_complex,  # Enable only for complex tasks
        }
    )

    return make_lead_agent(config)

# Simple task - no TodoList needed
simple_agent = create_agent_for_task("low")

# Complex task - TodoList enabled for better tracking
complex_agent = create_agent_for_task("high")

How It Works

1. When make_lead_agent(config) is called, it extracts is_plan_mode from config.configurable
2. The config is passed to _build_middlewares(config)
3. _build_middlewares() reads is_plan_mode and calls _create_todo_list_middleware(is_plan_mode)
4. If is_plan_mode=True, a TodoListMiddleware instance is created and added to the middleware chain
5. The middleware automatically adds a write_todos tool to the agent's toolset
6. The agent can use this tool to manage tasks during execution
7. The middleware handles the todo list state and provides it to the agent

Architecture

make_lead_agent(config)
  │
  ├─> Extracts: is_plan_mode = config.configurable.get("is_plan_mode", False)
  │
  └─> _build_middlewares(config)
        │
        ├─> ThreadDataMiddleware
        ├─> SandboxMiddleware
        ├─> SummarizationMiddleware (if enabled via global config)
        ├─> TodoListMiddleware (if is_plan_mode=True) ← NEW
        ├─> TitleMiddleware
        └─> ClarificationMiddleware

Implementation Details

Agent Module

• Location: packages/harness/deerflow/agents/lead_agent/agent.py
• Function: _create_todo_list_middleware(is_plan_mode: bool) - Creates TodoListMiddleware if plan mode is enabled
• Function: _build_middlewares(config: RunnableConfig) - Builds middleware chain based on runtime config
• Function: make_lead_agent(config: RunnableConfig) - Creates agent with appropriate middlewares

Runtime Configuration

Plan mode is controlled via the is_plan_mode parameter in RunnableConfig.configurable:

config = RunnableConfig(
    configurable={
        "is_plan_mode": True,  # Enable plan mode
        # ... other configurable options
    }
)

Key Benefits

1. Dynamic Control: Enable/disable plan mode per request without global state
2. Flexibility: Different conversations can have different plan mode settings
3. Simplicity: No need for global configuration management
4. Context-Aware: Plan mode decision can be based on task complexity, user preferences, etc.

Custom Prompts

DeerFlow uses custom system_prompt and tool_description for the TodoListMiddleware that match the overall DeerFlow prompt style:

System Prompt Features

• Uses XML tags (<todo_list_system>) for structure consistency with DeerFlow's main prompt
• Emphasizes CRITICAL rules and best practices
• Clear "When to Use" vs "When NOT to Use" guidelines
• Focuses on real-time updates and immediate task completion

Tool Description Features

• Detailed usage scenarios with examples
• Strong emphasis on NOT using for simple tasks
• Clear task state definitions (pending, in_progress, completed)
• Comprehensive best practices section
• Task completion requirements to prevent premature marking

The custom prompts are defined in _create_todo_list_middleware() in /Users/hetao/workspace/deer-flow/backend/packages/harness/deerflow/agents/lead_agent/agent.py:57.

Notes

• TodoList middleware uses LangChain's built-in TodoListMiddleware with custom DeerFlow-style prompts
• Plan mode is disabled by default (is_plan_mode=False) to maintain backward compatibility
• The middleware is positioned before ClarificationMiddleware to allow todo management during clarification flows
• Custom prompts emphasize the same principles as DeerFlow's main system prompt (clarity, action-oriented, critical rules)