DeerFlow
DeerFlow explained: the harness around a long-running agent
Understand DeerFlow’s lead agent, skills, memory, tools and sandbox boundaries before treating a fluent answer as a completed task.
What you will learn
- The harness is the product, not a new foundation model
- Five responsibilities that should not be confused
- Read the completion reason as well as the answer
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
- A harness coordinates execution around the model.
- Skills, authorization and sandboxing solve different problems.
- A stopped run may still be an incomplete task.
The harness is the product, not a new foundation model
DeerFlow coordinates model calls, tools, skills, memory and delegated work. The inspected backend package declares version 2.1.0 and Python 3.12 or later; the repository includes an MIT license. A model supplies reasoning and generated text, while the harness manages the surrounding execution. Changing the model therefore does not replace the need to configure permissions, persistence and operational limits.
Consider a permitted research assignment that reads supplied files and prepares a report. The useful result is a checked artifact with traceable claims, not merely a plan or a final chat message. DeerFlow provides mechanisms for doing work across multiple calls, but the operator still needs a definition of done and a policy for external actions.
Five responsibilities that should not be confused
The lead-agent builder assembles the middleware and tools for a run. Skill activation supplies task instructions; tool policy constrains the active skill’s usable tools; durable context captures delegated results and loaded skills before summarization. These responsibilities appear separately in the source. A skill being discoverable is not the same event as activating its runtime policy.
The Gateway exposes the application API and hosts active execution. The production composition connects it with the frontend, nginx and Redis. Redis helps stream delivery across workers, but the composition explicitly warns that cancellation, deduplication and some channel services remain worker-local. A component diagram must show those ownership boundaries instead of drawing Redis as a universal state solution.
Read the completion reason as well as the answer
A run can stop because it finished, repeated tool calls, hit a token budget or encountered a provider limit. The builder installs separate guards for several of these outcomes. Loop detection clears pending tool calls and exposes a stop reason for the caller; readable final text does not establish that the original assignment passed its acceptance criteria.
This series is based on a pinned commit, not an assumed current release. We ran inspected pure Python helpers for argument normalization, fingerprints and bounded storage, but did not start the full Gateway, call a paid model or build a sandbox. Deployment instructions and workload experiments are clearly marked as proposed checks rather than claimed production results.
Implementation steps
- 1
Define an artifact and its acceptance checks.
- 2
Map every external action to an explicit permission.
- 3
Record both output quality and the run’s stopping reason.
Copy-ready example
{"task":"summarize supplied test documents","acceptance":["claims have sources","artifact opens","no external writes"],"modelCallsExecuted":0,"fullRuntimeExecuted":false}Frequently asked questions
Is DeerFlow itself a language model?
No. It is an agent harness that connects models to execution, context and tool-management capabilities.
Does a completed run mean the report is correct?
No. Inspect the stop reason and independently check the artifact against the assignment.
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