# DeerFlow Issue Tracker and Architecture: Deep Dive into Bytedance's Super-Agent System

> Explore DeerFlow, ByteDance's open-source super agent system. Discover its issue tracker, LangGraph architecture, and multi-agent orchestration for automating complex tasks.

- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: deep-dive
- Published: 2026-03-08

---

**DeerFlow is an open-source super-agent harness built on LangGraph and LangChain that orchestrates multiple sub-agents, persistent memory, and sandboxed execution environments to automate complex multi-step tasks.**

DeerFlow (often referenced in GitHub issue trackers and technical discussions as "deer-flow") is ByteDance's comprehensive AI agent framework. Whether you are reporting bugs in the DeerFlow issue tracker or contributing to the codebase, understanding its architecture is essential. This article explores the complete system architecture—from the Lead Agent orchestration in [`src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/lead_agent/agent.py) to the sandboxed execution environments—providing developers with the technical depth needed to navigate, debug, and extend the system effectively.

## Core Architecture and Runtime Configuration

DeerFlow operates as a full-stack system configurable via [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) and [`extensions_config.json`](https://github.com/bytedance/deer-flow/blob/main/extensions_config.json). The configuration defines models, tools, sandbox providers, memory settings, and sub-agent limits. Both files are watched for changes; the Gateway reloads them automatically, and the embedded client invalidates its internal agent when updated.

When a request arrives via the Gateway, HTTP streaming, or the `DeerFlowClient`, the system builds a `RunnableConfig` containing:

```python
configurable = {
    "thread_id": thread_id,
    "model_name": model_name,
    "thinking_enabled": thinking_enabled,
    "is_plan_mode": plan_mode,
    "subagent_enabled": subagent_enabled,
}

```

This configuration is processed in `src/client.py::_get_runnable_config`. The agent is created lazily using `create_agent` with a chat model from [`src/models/factory.py`](https://github.com/bytedance/deer-flow/blob/main/src/models/factory.py), tools from [`src/tools/__init__.py`](https://github.com/bytedance/deer-flow/blob/main/src/tools/__init__.py), and a middleware stack built by `_build_middlewares` in [`src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/lead_agent/agent.py).

## The Lead Agent and Middleware Pipeline

The **Lead Agent** serves as the central orchestrator running the LangGraph workflow. It loads tools, skills, and middleware to process user requests. The middleware stack consists of ten ordered processors defined in [`src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/lead_agent/agent.py) (lines 19-33):

1. **ThreadDataMiddleware** – Creates per-thread directories at `backend/.deer-flow/threads/<id>/user-data/`
2. **UploadsMiddleware** – Detects uploaded files and injects virtual paths
3. **SandboxMiddleware** – Acquires sandbox instances and stores `sandbox_id` in state
4. **DanglingToolCallMiddleware** – Handles interrupted tool calls
5. **SummarizationMiddleware** – Triggers context summarization near token limits
6. **TodoListMiddleware** – Provides `write_todos` tool for plan mode
7. **TitleMiddleware** – Auto-generates thread titles
8. **MemoryMiddleware** – Queues messages for async memory extraction
9. **ViewImageMiddleware** – Processes images for vision-enabled models
10. **SubagentLimitMiddleware** – Enforces `MAX_CONCURRENT_SUBAGENTS` (default 3)
11. **ClarificationMiddleware** – Intercepts `ask_clarification` tool calls

## Sandbox and Execution Environment

DeerFlow provides isolated execution environments through a provider pattern implemented in [`src/sandbox/sandbox_provider.py`](https://github.com/bytedance/deer-flow/blob/main/src/sandbox/sandbox_provider.py). Two primary implementations exist:

- **LocalSandboxProvider** – Uses a single host directory for all sandboxed file I/O
- **AioSandboxProvider** – Spins up Docker containers or Kubernetes pods per request

Path translation functions (`replace_virtual_path`, `replace_virtual_paths_in_command`) map virtual `/mnt/user-data/...` paths to actual host paths, enabling secure file system access within the sandbox.

## Sub-Agent System and Task Delegation

When the `task` tool is invoked, the **Subagent Executor** ([`src/subagents/executor.py`](https://github.com/bytedance/deer-flow/blob/main/src/subagents/executor.py)) launches background threads running built-in sub-agents like `general-purpose` or `bash`. The executor respects configurable concurrency limits and returns SSE-style events (`task_started`, `task_running`, `task_completed`, `task_failed`, `task_timed_out`).

The Lead Agent receives these events via the LangGraph runtime and incorporates sub-agent outputs into the main thread's state, enabling complex multi-agent workflows.

## Memory and Persistence Layer

The memory subsystem operates asynchronously to maintain persistent, fact-based context:

1. **MemoryMiddleware** filters messages (user + final AI responses)
2. **MemoryUpdater** ([`src/agents/memory/updater.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/memory/updater.py)) batches updates with a 30-second debounce window
3. Facts are extracted via LLM and stored in [`backend/.deer-flow/memory.json`](https://github.com/bytedance/deer-flow/blob/main/backend/.deer-flow/memory.json)
4. Top N facts (default 15) are injected into system prompts under `<memory>` placeholders on each turn

## Gateway API and Client Interface

The **Gateway API** ([`src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/src/gateway/app.py)) provides FastAPI routes exposing system functionality:

| Router | Primary Endpoints |
|--------|------------------|
| **models** | `GET /api/models`, `GET /api/models/{name}` |
| **skills** | `GET /api/skills`, `GET /api/skills/{name}`, `PUT /api/skills/{name}`, `POST /api/skills/install` |
| **memory** | `GET /api/memory`, `GET /api/memory/config`, `POST /api/memory/reload` |
| **uploads** | `POST /api/threads/{id}/uploads`, `GET /api/threads/{id}/uploads/list`, `DELETE /api/threads/{id}/uploads/{filename}` |
| **artifacts** | `GET /api/threads/{id}/artifacts/{path}?download=true` |
| **mcp** | `GET /api/mcp/config`, `PUT /api/mcp/config` |

The **Embedded Client** ([`src/client.py`](https://github.com/bytedance/deer-flow/blob/main/src/client.py)) provides `DeerFlowClient`, a Python API mirroring all Gateway endpoints for in-process usage.

## Practical Implementation Examples

### Quick One-Shot Chat

```python
from src.client import DeerFlowClient

client = DeerFlowClient()
reply = client.chat(
    "Summarise the latest advances in large language model alignment.",
    thread_id="demo-thread"
)
print(reply)

```

### Streaming Conversation

```python
from src.client import DeerFlowClient

client = DeerFlowClient()
for ev in client.stream(
    "Explain the differences between reinforcement learning from human feedback and supervised fine-tuning.",
    thread_id="stream-demo"
):
    if ev.type == "messages-tuple" and ev.data["type"] == "ai":
        print("AI:", ev.data["content"])
    elif ev.type == "values":
        print("State snapshot:", ev.data["title"])

```

### Document Upload and Processing

```python
client = DeerFlowClient()
upload_res = client.upload_files(
    thread_id="doc-demo",
    files=["./example.pdf"]
)

# Retrieve converted markdown artifact

artifact_path = upload_res["files"][0]["markdown_virtual_path"]
bytes_, mime = client.get_artifact("doc-demo", artifact_path)
print(bytes_.decode()[:500])

```

### Skill Management

```python
client = DeerFlowClient()

# Enable built-in skill

client.update_skill("web-search", enabled=True)

# Install community skill

client.install_skill("./my-awesome.skill")

# Reload agent to apply changes

client.reset_agent()

```

### MCP Server Configuration

```python
client = DeerFlowClient()
print("MCP config:", client.get_mcp_config())

# Update configuration

new_cfg = {
    "my_server": {
        "enabled": True,
        "type": "http",
        "url": "https://my-mcp.example.com",
        "headers": {"Authorization": "Bearer <token>"}
    }
}
client.update_mcp_config(new_cfg)

```

## Summary

- **DeerFlow** is a LangGraph-based super-agent harness that orchestrates multiple sub-agents through a sophisticated middleware pipeline defined in [`src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/lead_agent/agent.py).
- The **middleware stack** processes every request through eleven ordered stages, handling everything from sandbox acquisition to memory persistence and sub-agent limits.
- **Sandboxed execution** supports both local filesystem and Docker/Kubernetes environments via the provider pattern in [`src/sandbox/sandbox_provider.py`](https://github.com/bytedance/deer-flow/blob/main/src/sandbox/sandbox_provider.py).
- The **Gateway API** ([`src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/src/gateway/app.py)) and embedded `DeerFlowClient` ([`src/client.py`](https://github.com/bytedance/deer-flow/blob/main/src/client.py)) provide comprehensive REST and Python interfaces for models, skills, memory, uploads, and MCP servers.
- **Asynchronous memory updates** extract facts from conversations and inject them into subsequent prompts, maintaining context across sessions.

## Frequently Asked Questions

### Where is the DeerFlow issue tracker located?

The DeerFlow issue tracker is hosted on GitHub at the official `bytedance/deer-flow` repository. Developers can report bugs, request features, and track development progress through GitHub Issues. When submitting issues, reference specific file paths such as [`src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/lead_agent/agent.py) or [`src/client.py`](https://github.com/bytedance/deer-flow/blob/main/src/client.py) to help maintainers quickly identify relevant components.

### How does DeerFlow handle task tracking and todo lists?

DeerFlow includes built-in task tracking through the `TodoListMiddleware` (position 6 in the middleware stack) and the `write_todos` tool. When operating in plan mode (`is_plan_mode: true`), the Lead Agent can create, update, and check off todo items to track multi-step workflows. This functionality is implemented in [`src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/lead_agent/agent.py) and persists state through the LangGraph thread mechanism.

### What is the maximum number of concurrent sub-agents in DeerFlow?

DeerFlow enforces a default limit of **3 concurrent sub-agents** through the `SubagentLimitMiddleware` (position 10 in the middleware stack). This limit is configurable via the `MAX_CONCURRENT_SUBAGENTS` setting in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml). When the limit is exceeded, the middleware truncates excess `task` tool calls to prevent resource exhaustion, as implemented in [`src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/src/agents/lead_agent/agent.py).

### How do I report sandbox execution errors in DeerFlow?

When reporting sandbox-related issues to the DeerFlow issue tracker, include details about your sandbox provider configuration from [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml). DeerFlow supports two providers: `LocalSandboxProvider` (using host directories) and `AioSandboxProvider` (using Docker/Kubernetes). Reference the specific provider implementation in [`src/sandbox/sandbox_provider.py`](https://github.com/bytedance/deer-flow/blob/main/src/sandbox/sandbox_provider.py) and include error logs from the sandbox acquisition phase, which is handled by `SandboxMiddleware` in the Lead Agent pipeline.