Skip to main content
DeerFlow’s agent system is built on LangGraph, providing a powerful framework for orchestrating AI agents with tools, memory, and sub-agents.

​
Lead Agent

The lead agent is the entry point for all user interactions. It’s implemented in backend/src/agents/lead_agent/agent.py. Key Components:
  • Dynamic model selection
  • Tool loading and management
  • System prompt generation
  • Middleware chain execution

​
Agent Creation

The agent is created via the make_lead_agent() function, registered in langgraph.json: 
def make_lead_agent(config: RunnableConfig):
    # Get configuration
    thinking_enabled = config.get("configurable", {}).get("thinking_enabled", False)
    model_name = config.get("configurable", {}).get("model_name")
    
    # Create model
    model = create_chat_model(model_name, thinking_enabled)
    
    # Load tools
    tools = get_available_tools(
        groups=config.tool_groups,
        model_name=model_name,
        subagent_enabled=config.subagent_enabled
    )
    
    # Generate system prompt
    system_prompt = apply_prompt_template(config)
    
    # Build agent
    agent = create_react_agent(model, tools, state_schema=ThreadState)
    
    return agent

​
Runtime Configuration

The agent behavior can be customized per-request via config.configurable:
​
thinking_enabled
boolean
default:"false"
Enable extended thinking mode for complex reasoning
​
model_name
string
Override the default model for this request
​
is_plan_mode
boolean
default:"false"
Enable TodoList middleware for task tracking
​
subagent_enabled
boolean
default:"true"
Enable sub-agent delegation tool

​
ThreadState

ThreadState extends LangGraph’s AgentState with DeerFlow-specific fields. Location: backend/src/agents/thread_state.py 
class ThreadState(AgentState):
    messages: Annotated[list, add_messages]
    sandbox: Optional[Sandbox]
    thread_data: dict
    title: Optional[str]
    artifacts: Annotated[list[dict], merge_artifacts]
    todos: Optional[list[dict]]
    uploaded_files: list[str]
    viewed_images: Annotated[list[dict], merge_viewed_images]

​
State Fields

Conversation history with custom add_messages reducer.Type: list[BaseMessage]Includes HumanMessage, AIMessage, ToolMessage, and SystemMessage types.
Sandbox instance for file operations and command execution.Type: Optional[Sandbox]Set by SandboxMiddleware, used by sandbox tools.
Thread-specific metadata and configuration.Type: dict
{
    "thread_id": "abc123",
    "workspace_path": "/path/to/workspace",
    "uploads_path": "/path/to/uploads",
    "outputs_path": "/path/to/outputs"
}
Output files created by the agent.Type: list[dict]Reducer: merge_artifacts (deduplicates by path)
[
    {
        "path": "/mnt/user-data/outputs/report.html",
        "type": "html",
        "title": "Analysis Report"
    }
]
Task list for Plan Mode.Type: Optional[list[dict]]Only populated when is_plan_mode=true.
List of files uploaded by the user.Type: list[str]File paths in the uploads directory.
Images loaded for vision-enabled models.Type: list[dict]Reducer: merge_viewed_images (supports clearing)

​
Custom Reducers

merge_artifacts: Deduplicates artifacts by path 
def merge_artifacts(left: list, right: list) -> list:
    seen = {a["path"] for a in left}
    return left + [a for a in right if a["path"] not in seen]
merge_viewed_images: Merges images, supports clearing 
def merge_viewed_images(left: list, right: list | str) -> list:
    if right == "clear":
        return []
    return left + right

​
Middleware Chain

Middlewares execute in strict order around the agent:
  1. ThreadDataMiddleware - Creates thread directories
  2. UploadsMiddleware - Injects uploaded files into conversation
  3. SandboxMiddleware - Acquires and stores sandbox instance
  4. DanglingToolCallMiddleware - Handles interrupted tool calls
  5. SummarizationMiddleware - Context reduction (optional)
  6. TodoListMiddleware - Task tracking (optional, Plan Mode)
  7. TitleMiddleware - Auto-generates thread title
  8. MemoryMiddleware - Queues conversations for memory updates
  9. ViewImageMiddleware - Injects image data for vision models
  10. SubagentLimitMiddleware - Enforces concurrent subagent limits
  11. ClarificationMiddleware - Handles ask_clarification interrupts (must be last)

Middleware Chain

Learn about each middleware in detail

​
System Prompt

The agent’s system prompt is dynamically generated with:
  • Skills: Enabled skills with their descriptions
  • Memory: Top 15 facts and user context
  • Sub-agents: Available sub-agent types
  • Tools: Tool usage guidelines
  • Sandbox paths: Virtual filesystem structure
Example: 
You are a super agent with access to skills, tools, and sub-agents.

Skills:
- deep-research: Comprehensive research with multi-source analysis
- data-analysis: Analyze datasets with pandas and create visualizations

Memory:
User Context:
- Work: Software engineer at TechCorp
- Preferences: Prefers Python over JavaScript

Key Facts:
- Uses VS Code as primary editor (confidence: 0.9)
- Works on microservices architecture (confidence: 0.85)

Tools:
- bash: Execute commands in sandbox
- read_file: Read file contents
- task: Delegate to sub-agents

Sandbox:
- /mnt/user-data/workspace - Your working directory
- /mnt/user-data/uploads - User uploaded files
- /mnt/user-data/outputs - Output files for the user
- /mnt/skills/public - Public skills
- /mnt/skills/custom - Custom skills

​
Tool Loading

Tools are loaded via get_available_tools(): 
tools = get_available_tools(
    groups=["sandbox", "research"],  # Tool groups from config
    include_mcp=True,                # Include MCP tools
    model_name="gpt-4",             # Current model
    subagent_enabled=True           # Include task() tool
)
Tool Sources:
  1. Config-defined tools: From config.yaml via reflection
  2. MCP tools: From enabled MCP servers
  3. Built-in tools: present_files, ask_clarification, view_image
  4. Sub-agent tool: task() for delegation

​
Model Selection

Models are created via the model factory: 
from src.models.factory import create_chat_model

model = create_chat_model(
    name="gpt-4",
    thinking_enabled=True
)
The factory:
  • Resolves model configuration from config.yaml
  • Instantiates via reflection system
  • Applies thinking mode overrides
  • Handles environment variable resolution

Model Factory

Deep dive into model instantiation

​
Next Steps

Middleware Chain

Understand each middleware component

ThreadState

Deep dive into state management

Tools

Learn about available tools

Sub-agents

Delegate tasks to sub-agents

Build docs developers (and LLMs) love

Get started for freeTalk to us