mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 11:20:35 +00:00
* docs: turn README into an index and move reference detail to docs/guide The README had grown to 393 KB because every change appended its notes there. The text moves verbatim into 18 topic guides under docs/guide/; only headings are re-leveled and relative links re-pointed. The README keeps the introduction, a quick start and a guide index. Contributor test notes move to CONTRIBUTING.md. * docs: send user docs to topic guides and budget the root README The rule 'update README.md for user-facing changes' is what grew the README. Guidance now points to docs/guide/, and check_agent_guidance.py fails when the root README exceeds 16 KiB (AG003). * chore: remove unreferenced screenshots and finished plan notes pr-build/ holds two PR screenshots (3 MB) from #1986. plans/ holds the plan for the merged #4049. docs/SKILL_NAME_CONFLICT_FIX.md is a February change note. Nothing references them. * docs: route always-loaded AGENTS.md files to scoped guides * docs(agents): cut scoped guides to scope, verify, traps, decisions Each AGENTS.md keeps four kinds of content: the scope of the directory, the verification commands, traps a local test run does not show, and decisions the code cannot state. Values, field lists, function inventories, test names, issue numbers and history are deleted, because the code, the tests and git state them. Search and fetch providers share one community guide. Four guides with no remaining content are removed. The size check now allows 6 KiB per file (hard limit 8 KiB) and 24 KiB per chain (hard limit 32 KiB). * style: format frontend guide table and guidance test imports --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
2.8 KiB
2.8 KiB
Agents (deerflow/agents/)
The lead agent factory, its system prompt, the thread state and its reducers.
Scoped guides: middlewares, memory,
task continuity. Runtime options and state fields
are in lead_agent/agent.py and thread_state.py.
Verify
cd backend
python -m pytest tests -q -k "lead_agent or thread_state or assembly or prompt"
Lead agent
make_lead_agent(config)is the publishedlanggraph.jsonentry point. Keep its signature and its bare-graph return type. The Gateway callsassemble_lead_agent, which also returns the descriptor and the effective model.- A consumer unwraps through
runtime/runs/worker.py::_agent_graph, because a third-party factory can return a bare graph. - The graph and the assembly descriptor receive the same rendered prompt and the same middleware objects. Observers then describe the graph that runs.
- Skill
allowed_toolsin the descriptor is exported metadata. It never filters tools. Omitted, declared empty and non-empty are three states. - A custom graph integration supplies the runtime
run_id. Without it, the delegation cap counts the thread's whole ledger and logs a warning. - One
SubagentRuntimeis shared per capacity boundary when you build the graph directly withcreate_deerflow_agent.
Prompt trust
- Framework authority uses the system channel. Text that a user or a model can
influence goes into the sanitized
HumanMessagedata channel. Do not interpolate an untrusted value into system text; escaping tags does not neutralize an instruction written in natural language. - The locale preference is request-only human data. The static system prompt stays independent of it, and an explicit language request from the user wins.
lead_prompt_overlayis literal operator text. Do not template-format it or source it from the run context.
Thread state
merge_message_writeskeeps the publicadd_messagesbehavior in full. LangGraph's private delta reducer omits part of it and cannot replace it. The differential tests cover the parity.- Reducers encode rules that a plain overwrite breaks: the active goal survives ordinary updates, and a terminal delegation status is never downgraded. Read the reducer before you write its field.
Import hygiene
- The package roots of
deerflow.agentsanddeerflow.subagentsload the graph and the executor lazily. A module that needs only a type, a config or a registry imports the concrete submodule. An eager import at the package root pulls the tool graph into every state and schema import. deerflow.agents:make_lead_agentis a real module-level function, because LangGraph Server resolves factories from the module dictionary. Its heavy imports stay inside the function.