DeerFlow
Inside DeerFlow’s middleware: order, context and execution policy
Trace the lead-agent assembly and explain why middleware order and capability-dependent branches matter more than a fixed component count.
What you will learn
- Follow the builder rather than memorizing a count
- Visibility is not execution authorization
- A local sandbox is a mapping layer, not a host boundary
Before you start
- Basic Python, HTTP and container concepts
- An owned task with explicit acceptance criteria
Explain the chapter’s implementation boundary and apply its checklist or isolated helper exercise.
Key takeaways
- Read the effective middleware order and feature branches.
- Tool visibility is separate from execution policy.
- Local path mapping is not host-process isolation.
Follow the builder rather than memorizing a count
build_middlewares begins with the lead runtime middleware stack, then appends dynamic context, explicit skill activation, skill tool policy and durable context. Summarization, planning, token tracking, vision and deferred MCP handling depend on configuration or runtime capability. The older execution-flow document gives fixed counts that do not describe every branch of this builder.
Dynamic context is placed in a user-side reminder so the system prompt can remain stable for prefix reuse, according to the implementation comment. Durable context is registered before summarization to capture completed delegations and loaded skill files before compaction. The engineering concern is preserving the right information at the right boundary, not maximizing the number of middleware classes.
Visibility is not execution authorization
The source distinguishes discoverable skill metadata, explicit slash activation and runtime allowed-tool policy. Deferred MCP schemas can be hidden until tool search promotes them; a separate policy filters visibility, search results and execution for an active skill. Hiding a schema from a model is therefore only one part of the control path.
Ordering assertions place MCP routing before the deferred filter, while promotion auditing wraps inner policy transformations. The builder later coalesces system messages and installs run guards. Custom and extension middleware can alter the final composition, so inspect the effective stack when debugging a deployment rather than inferring it solely from the public architecture diagram.
A local sandbox is a mapping layer, not a host boundary
LocalSandboxProvider creates per-user and per-thread mappings for workspace, uploads and outputs. It uses a bounded LRU cache of sandbox objects and serializes cache changes with a lock. Eviction reconstructs the object on a later acquire and loses a reverse-resolution hint; it is not described as deleting the thread’s persisted files.
The provider explicitly states that its managed skill view is a logical boundary. A host shell can address canonical host paths outside that view, so supports_agent_skill_isolation is false when host bash is allowed or configuration cannot be read. A tenant identifier, mapped path or cached sandbox object must never be presented as equivalent to operating-system isolation.
Implementation steps
- 1
Trace a skill from discovery through activation to an actual tool call.
- 2
Locate context capture before summarization in the builder.
- 3
Document the selected sandbox’s real enforcement boundary.
Copy-ready example
{"conceptualFlow":["discover skill","activate skill","apply tool policy","capture durable context","summarize","guard termination"],"fixedMiddlewareCount":null,"localPathMappingIsOsIsolation":false}Frequently asked questions
How many middlewares does DeerFlow have?
The effective count depends on configuration, model capabilities and extensions. Inspect the pinned builder instead of repeating a fixed count from an older diagram.
Does local sandbox cache eviction remove my files?
The reviewed provider describes eviction of in-memory objects and reconstruction later, not deletion of persisted thread data.
Sources
- README.mdSource checked 2026-09-08
- LICENSESource checked 2026-09-08
- backend/README.mdSource checked 2026-09-08
- backend/pyproject.tomlSource checked 2026-09-08
- backend/docs/middleware-execution-flow.mdSource checked 2026-09-08
- backend/packages/harness/deerflow/agents/lead_agent/agent.pySource checked 2026-09-08
- backend/packages/harness/deerflow/agents/middlewares/loop_detection_middleware.pySource checked 2026-09-08
- backend/packages/harness/deerflow/agents/middlewares/_bounded_dict.pySource checked 2026-09-08
- backend/packages/harness/deerflow/config/loop_detection_config.pySource checked 2026-09-08
- backend/packages/harness/deerflow/sandbox/local/local_sandbox_provider.pySource checked 2026-09-08
- backend/app/gateway/auth_middleware.pySource checked 2026-09-08
- backend/app/gateway/csrf_middleware.pySource checked 2026-09-08
- docker/docker-compose.yamlSource checked 2026-09-08