Xinmin Zeng 2a97ec3e58
docs: turn README into an index and move reference detail to docs/guide (#8113)
* 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>
2026-11-11 13:26:17 +08:00

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 published langgraph.json entry point. Keep its signature and its bare-graph return type. The Gateway calls assemble_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_tools in 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 SubagentRuntime is shared per capacity boundary when you build the graph directly with create_deerflow_agent.

Prompt trust

  • Framework authority uses the system channel. Text that a user or a model can influence goes into the sanitized HumanMessage data 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_overlay is literal operator text. Do not template-format it or source it from the run context.

Thread state

  • merge_message_writes keeps the public add_messages behavior 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.agents and deerflow.subagents load 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_agent is a real module-level function, because LangGraph Server resolves factories from the module dictionary. Its heavy imports stay inside the function.