bytedance/deer-flow: a SuperAgent for deep research
I have been testing deer-flow (an open source “SuperAgent” framework from ByteDance, designed to do multi-step research tasks that combine web search, document reading, and code execution in a single workflow) for about three weeks. The premise is that most “research” tasks I do are not one query. They are a sequence: search, read, search again, cross-reference, summarize. The premise of deer-flow is that an agent should be able to do that sequence in one shot, with planning, tool use, and a final synthesized answer.
The framework is not for everyone. It is for the kind of person who already builds AI pipelines and wants a research assistant that does not require them to write the orchestration. For that person, it is good. For anyone else, the learning curve is real.
What it is, in one paragraph
deer-flow is a Python framework and a set of agent definitions for running multi-step research tasks. The agent definitions are JSON files that declare the planning strategy, the tools available to the agent, and the model to use. The framework executes the agent on a task, gives the agent access to the declared tools (web search, browser automation, file system, code execution), and returns a final report.
The framework is built on top of LangGraph (a library for building stateful, multi-step AI workflows as directed graphs, where each step is a node and the connections between steps are edges), which is the underlying orchestration engine. The deer-flow contribution is the research-specific agent definitions, the default tool integrations, and the report-generation logic.
The “SuperAgent” framing in the README is the maintainers’ term for an agent that can do everything a research analyst can do: search the web, read documents, write code, and produce a coherent report. I am skeptical of the framing as a general claim. For the specific kind of research task I do, the framing is accurate.
The research task I gave it
I have been writing a series of reports on the state of open source agent frameworks. The reports require me to read 5 to 10 sources, cross-reference claims, and produce a summary that cites the sources. The process usually takes me about 6 hours per report. I gave deer-flow the same task.
The task definition looked like this.
task = """
Research the current state of open source agent frameworks in 2026.
Cover: the major frameworks, their maintainers, their adoption in
production, the trade-offs between them, and the emerging trends.
Use at least 8 sources. Cite every claim. Produce a 1500-word report.
"""
report = deer_flow.run(task)
The agent ran for about 12 minutes. It used the web search tool 14 times, opened 9 documents, wrote and executed 3 small Python scripts to cross-reference data, and produced a 1,400-word report with 11 citations.
The report was not as good as the 6-hour version I would have written. It missed two of the frameworks I would have included. It made one factual error that I caught. The citations were real links to real sources, which is the part I was most worried about and the part that worked best.
What the framework actually does well
I want to be specific about the parts that worked.
- Multi-step planning. The agent broke the task into a research plan, executed the plan, and revised the plan when an early search did not return useful results. The plan was visible in the output, which made the failure modes easy to diagnose.
- Tool use. The agent used the web search tool, the browser automation tool, the document reader, and the Python execution sandbox (an isolated environment where the agent can run code without affecting the rest of the system). The tool use was not perfect. The agent made one web search that returned no results and tried a different query. The retry behavior is the part that distinguishes a research agent from a single-query LLM call.
- Citation. The agent cited every claim in the final report with a real URL. I spot-checked 6 of the 11 citations. All 6 linked to real sources that supported the claim. This is the part that I was most worried about, and the part that worked.
- Output structure. The final report had a clear structure: introduction, methodology, findings, citations. The structure was not the structure I would have written by hand, but it was readable and it was consistent across two different tasks I gave it. Predictable output structure is underrated.
What the framework does not do well
I want to be specific about the failure modes, because every tool has them and this tool has more than most.
- Long-running tasks are fragile. The 12-minute research task ran cleanly. I tried a longer task (a 45-minute comprehensive market analysis) and the agent lost track of its plan halfway through. The plan-revision logic does not handle long contexts well.
- The default tool integrations are limited. The web search tool uses a single search backend. The browser automation tool uses a headless Chrome instance. The Python sandbox is local. If your task requires a different tool, you have to write a custom integration, which is documented but not trivial.
- The cost is real. The 12-minute research task consumed about 80 cents of LLM API credits. The 45-minute task consumed about $6. For personal research, this is acceptable. For production use, the cost adds up.
The cost one is the one I underestimated. A single research task at 80 cents is not expensive. Ten research tasks a day at 80 cents each is $8 a day, which is $240 a month. For a research workflow that produces reports, that is a real operating cost.
What I would tell past me
If I could send a message back to the version of me that was about to test deer-flow, I would say three things.
- Start with a task you have already done by hand. The reason I could evaluate the output is that I had a 6-hour version of the same research to compare against. Without the comparison, I would not have known what was good and what was missing. Pick a task you have done before, not a new task.
- Budget for the LLM cost. The framework is going to make a lot of LLM calls. A 12-minute task is 80 cents. A 45-minute task is $6. The cost is the part that surprises people, because the README does not lead with it.
- Read the plan output, not just the final report. The plan is the part of the output that tells you what the agent was thinking. If the plan is wrong, the report is going to be wrong. If the plan is right, the report is going to be mostly right. The plan is the leading indicator.
Trade-offs
The framework is built on LangGraph, which means it inherits LangGraph‘s complexity. If you do not already know LangGraph, the learning curve is steep. If you do, the framework is a thin layer on top. The trade is “easy to start” versus “easy to extend.” The framework chose the second.
Default agent definitions are designed for English-language research. I tried a Chinese-language task, and the agent’s web search returned mostly English results. The framework is being developed by a Chinese team and the Chinese-language support is improving. For now, the English-language support is better.
Output is a Markdown report. The format is fixed. If you need a different output format (a slide deck, a structured JSON, a database row), you have to write a custom output adapter. The adapter is straightforward. The adapter is not built in.
Bottom line
deer-flow is the research agent framework I would recommend to a developer who is already building AI pipelines and wants a research assistant that can do multi-step work. The 12-minute research task I gave it produced a report that was about 70% as good as the 6-hour version I would have written, at about 5% of the cost. The trade is one I am willing to make for the kind of research where 70% accuracy is enough. For the kind where it is not, I still do it by hand.