DeerFlow
Build a DeerFlow run-quality observatory, not another output counter
Design a proposed evaluation project that connects stop reasons, artifacts and human acceptance without collecting sensitive prompts or inventing upstream roadmap commitments.
What you will learn
- Turn the implementation into a testable project idea
- Use the loop detector as a focused regression target
- Visualize evidence without adding unnecessary runtime weight
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
- Link termination reasons to independently reviewed artifacts.
- Keep helper, lifecycle and deployment tests separate.
- Choose a timeline when the important relationship is temporal.
Turn the implementation into a testable project idea
A useful follow-on project is a run-quality observatory that links a task definition, source revision, effective policy and final artifact verdict. This is our proposed extension, not an announced DeerFlow feature or roadmap commitment. Its purpose is to explain why a run stopped and whether the produced artifact was useful, rather than counting final messages as successful work.
Begin with manually exported, redacted records from a disposable evaluation environment. Store a task identifier, stop reason, accepted/rejected decision and coarse resource measurements. Do not collect raw credentials, private documents or full prompts by default. A small schema with explicit unknown values is easier to review than a dashboard that silently labels missing telemetry as zero cost.
Use the loop detector as a focused regression target
Create cases for identical call batches, reordered batches, changed write payloads, reads across a bucket boundary and mixed tool bursts. The inspected helper probe already establishes a few deterministic expectations; lifecycle tests would additionally need real message objects, configuration and middleware execution. Keep those levels separate so a passing fingerprint test is not mistaken for a working server.
A particularly useful integration case verifies that queued warnings appear only after the previous assistant tool calls have their matching responses. Another verifies that a hard-stop update removes both direct tool calls and provider-specific metadata. These are proposed regression cases grounded in inspected code, not a claim that this review ran the full agent stack.
Visualize evidence without adding unnecessary runtime weight
A two-dimensional timeline can show model responses, tool batches, warning injection and artifact review more clearly than a decorative three-dimensional scene. Use static SVG for the article and add interaction only if readers need filtering or event inspection. Three.js would be justified for a genuinely spatial problem, not merely because an agent architecture sounds complex.
The project should graduate only after known failure cases remain visible, resource units are documented and independent reviewers can reproduce a verdict. Record unexecuted tests openly and distinguish editorial self-assessment from real user studies or search-engine performance. A future dashboard should make incompleteness easier to see, not hide it behind an attractive success count.
Implementation steps
- 1
Define a minimal redacted run record.
- 2
Add the deterministic helper cases as one test layer.
- 3
Design message-order and hard-stop integration fixtures.
- 4
Review proposed visualizations against actual reader questions.
Copy-ready example
{"proposal":"run-quality-observatory","sourceRevision":"9ce6fdc","stopReason":null,"artifactAccepted":null,"rawPromptsStored":false,"actualAgentRuns":0,"upstreamRoadmapClaim":false}Frequently asked questions
Is this observatory an official DeerFlow roadmap item?
No. It is an editorial project proposal derived from the inspected execution and stop-reason mechanisms.
Why not use Three.js for every chapter?
The key relationships here are ordering, ownership and policy branches. Lightweight SVG timelines and diagrams communicate them more directly.
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