mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-19 19:00:36 +00:00
* feat(memory): redact queued memory payloads (pii_redaction follow-up) Closes the remaining vector from #3190 (memory storage): request-scoped redaction leaves originals in thread state, and MemoryMiddleware queued that raw conversation into the durable extraction buffer — so the extraction model's input and the persisted facts carried raw PII even with pii_redaction.enabled. - MemoryMiddleware gains pii_redaction_config (same pattern as summarization / durable-context / title); the payload returned by _resolve_add_args() is redacted at the enqueue boundary before add()/aadd(), covering both after_agent and aafter_agent - Reuses the shared redact_text() seam from #5527 via active_pii_detectors/_Redactor/_redact_content; the buffered payload itself becomes clean, not just the extraction model's view - Wired at the lead-agent assembly site - Tests: queue-payload redaction enabled/disabled, detector toggles, message immutability, token stability across turns * fix(memory): reserve existing placeholder indices across the queued batch Review round 1 on #5577: thread state mixes raw user turns with already-redacted tool results and summaries, so a token in a later message must not collide with a new value in an earlier one. Pre-scan the whole queued batch with redactor.reserve() before allocating. Also extend the two MemoryMiddleware stubs in test_lead_agent_model_resolution.py to accept the new pii_redaction_config kwarg (CI backend-unit-tests red). * fix(memory): redact the compaction-triggered memory_flush_hook queue too Review round 2 on #5577: with memory + summarization enabled, memory_flush_hook() queues list(event.messages_to_summarize) directly into MemoryManager.add_nowait(), bypassing MemoryMiddleware entirely — and compaction removes those messages from state right after, so the after-agent redaction can never repair a raw batch queued there. Extract the batch redaction (reserve pre-scan + rebuild) into a shared redact_queued_messages() used by both MemoryMiddleware's enqueue boundary and the hook; the hook gains an optional pii_redaction_config wired via functools.partial at the summarization factory (subagents use skip_memory_flush=True and are unaffected). Regression covers the hook path enabled/disabled/absent. * test(summarization): unwrap the partial in the factory hook identity check edd916e wrapped memory_flush_hook in functools.partial to carry the pii_redaction config, but missed committing the matching update to test_factory_attaches_memory_flush_hook_by_default — a functools.partial is not equal to its wrapped function, so the identity assertion failed deterministically (caught by static review on #5577). * fix(memory): cover tool-call arguments and lenient text blocks in queued payloads Review round 4 on #5577 — two reproduced gaps still allowed raw PII into memory payloads with pii_redaction.enabled=true: - OpenViking retains the full message object, so parsed tool_calls args and provider-format arguments in additional_kwargs bypassed the content-only redaction; queued payloads now redact tool-call args recursively (and reserve them in the pre-scan). - DeerMem's format_conversation_for_update reads p.get("text") of any dict block, not only type=="text" — _redact_content now redacts every string-valued text field so a lenient consumer cannot bypass it. Both repro shapes are pinned as regressions. * fix(pii): value-derived placeholders for stable capture identity Review round 5 on #5577: sequential allocation is order-dependent — the same unchanged message re-redacted in a later batch can get a different token, which flips OpenViking's content-signature and replays already recorded turns into persistent memory sessions. Placeholders are now a pure function of the matched value (sha256-6 per category): identities stay stable across batches, enqueues, seams, and backends with no shared state and no stored mapping. - _Redactor becomes stateless; the reserve machinery (index pre-scans, _PLACEHOLDER_PATTERN) is removed along with its call sites - redact_texts keeps its signature, now a simple per-text redaction - reserve-semantics tests are superseded by cross-enqueue identity tests (two successive captures where the second batch carries higher existing placeholders); the compiled-graph echo regex matches the new format * fix(pii): 128-bit placeholder digests; redact tool-argument keys Review round 6 on #5577: - [P2] The 24-bit truncation collided distinct identities (reproduced: contact3513@ / contact3727@example.com both rendered [EMAIL_575dbb]). Retain 128 bits of the digest so separate people stay separate at any realistic volume; the compiled-graph echo regex and the AGENTS.md entry follow the new format. - [P2] _redact_strings redacted values but preserved mapping keys, so {"contacts": {"alice@example.com": "manager"}} kept the raw email as a key. Redact string keys along with values; deterministic 128-bit tokens make distinct-key collisions a hash-collision non-event, and a redacted key equal to another key merges the entries. Regression pins the email-keyed arguments shape. * docs(agents): trim PiiRedactionMiddleware entry; drop stale reserve wording The chain grew past the 98304-byte AG002 hard limit again (main growth plus the round-6 format example). Trim the entry to fit, and replace the stale reserve-indices wording with the value-derived semantics that replaced it. * docs(agents): shrink PiiRedactionMiddleware entry below the chain budget main moved (#5609) and the base comparison flipped the nearly-over chain back to an AG002 error (98441 > 98304). Trim the entry to the facts that are not documented elsewhere: seams, allowlist, order, enqueue boundary. * fix(pii): letters-only value-derived tokens; wire the factory SDK path Review round 7 on #5577: - [P2] Hex digests carry digit runs that later digit-anchored detectors re-scan, corrupting minted tokens into nested placeholders (reproduced: user280@example.com -> [EMAIL_…[PHONE_…]…], ~1/140 emails). The 128-bit digest is now encoded over a-z, so a minted token survives the full pinned detector order. - [P2] create_deerflow_agent (the SDK path) constructed MemoryMiddleware and DurableContextMiddleware without pii_redaction_config; the knob is now an explicit optional parameter threaded through _assemble_from_features (the factory reads no config files by design, so SDK callers pass it explicitly). - [Nit] hoist the Command rebuild comprehension out of the per-message loop in _redact_result. - [Nit] drop the dead _iter_tool_calls helper and Iterator import. * test(factory): pin pii_redaction_config wiring; document the parameter Review round 8 on #5577: - [P3] test_create_deerflow_agent.py had zero coverage of the pii_redaction_config parameter; two regressions now assert that create_deerflow_agent(pii_redaction_config=cfg) builds a MemoryMiddleware and a DurableContextMiddleware carrying cfg, and that the default is None (redaction off). - [Nit] document the parameter in the create_deerflow_agent docstring: None leaves redaction off; a middleware= takeover bypasses the assembly that would apply it. * fix(pii): HMAC-scoped placeholder tokens; install model-bound redaction in the SDK chain Review round 10 on #5577: - [P2] sha256(category||value) is an unkeyed, globally deterministic fingerprint: a provider or memory backend can confirm candidate values offline and link identical values across users and threads, contradicting the documented no-re-identification guarantee. Placeholders are now HMAC-derived over a deployment-scoped token_secret (new config field); the docstring documents the linkability scope for both modes. - [P2] _assemble_from_features() never appended PiiRedactionMiddleware, so the SDK knob enabled only the downstream seams while the primary model still received raw content. The middleware is now appended in the same relative position as the lead-agent base chain when the gate is on, with a model-call regression through the assembled SDK chain. * docs(pii): document token_secret; update the placeholder format examples Follow-up to the round-10 review on #5577: - config.example.yaml documents the new token_secret knob: a deployment-scoped secret makes placeholders HMAC-derived and only linkable within one deployment; leaving it unset keeps publicly computable fingerprints (documented trade). - the PiiRedactionConfig class docstring's placeholder example now matches the shipped format (128-bit HMAC digests over base-26 letters). * docs(pii): update the module docstring's placeholder format example The module docstring still showed the sequential [EMAIL_1] example; align it with the shipped value-derived format (128-bit HMAC digests over base-26 letters). * fix(pii): require a non-empty token_secret when redaction is enabled Review round 11 on #5577: with the secret optional, the default enabled configuration minted empty-key HMAC digests — publicly computable, globally linkable fingerprints of the raw values, confirmable by offline guessing for low-entropy identifiers such as phone numbers. - PiiRedactionConfig now rejects enabled=true without a non-empty token_secret (minimum 16 characters); the unkeyed mode is gone entirely. - The request-scoped redactor in _process_request now carries the configured key: it built its redactor without it, so user-message placeholders silently diverged from every other seam for the same value. The empty-key guard in _placeholder_token is the backstop that keeps every path keyed. - Module/config docstrings and config.example.yaml no longer describe the placeholders as irreversible or the secret as optional; the stale reserve-semantics wording and the "memory path not covered" note are corrected. - Regressions: validation errors for missing/blank/short secrets, and the user-message boundary minting the same keyed token as redact_text. * fix(memory): redact original_user_content on queued memory payloads Review round 12 on #5577: UploadsMiddleware preserves the raw user turn in additional_kwargs.original_user_content, but redact_queued_messages rewrote only content, tool_calls, and provider-format tool_calls — the queued copy still carried the raw value, so the memory queue and backend received raw PII with redaction enabled. The shared helper now redacts the provenance string field on the queued copy (same batch redactor, merged with the existing additional_kwargs rewrite, rebuilt via model_copy — thread-state messages stay untouched), covering both the enqueue boundary and the compaction flush hook. Regressions pin the redacted provenance field through both paths and the untouched original. * fix(memory): redact human_input_response on queued memory payloads Review round 13 on #5577: clarification replies keep the raw user answer in additional_kwargs.human_input_response.value (DeerMem reads that mapping via its read_human_input_response mirror), but redact_queued_messages rewrote only content, tool_calls, and original_user_content — the queued copy still carried the raw value into the memory queue and backend. The shared helper now rebuilds that mapping with value redacted (same batch redactor) while preserving the protocol fields (version/kind/source/ request_id/option_id/response_kind), merged with the existing additional_kwargs rewrite and rebuilt via model_copy so thread-state messages stay untouched. Regressions pin the redacted value, preserved protocol fields, the untouched original, and the flush-hook path. * chore(config): bump config_version to 47; generate token_secret on upgrade Review round 13 on #5577: existing deployments can legitimately sit at config_version 46 with pii_redaction.enabled: true and no token_secret; the mandatory-secret validator would fail their startup while config.example.yaml still said 46, so the upgrade checker considered them current and emitted no migration warning. - Bump config_version to 47 so the outdated-config warning fires for v46. - Add a v47 migration to scripts/config-upgrade.sh: when pii_redaction is enabled and token_secret is missing/blank, generate a random deployment- scoped secret (secrets.token_urlsafe) and persist it, so the upgraded deployment starts under the mandatory validation. - Regressions: a v46 enabled config is flagged outdated against the real example; the upgrade run generates a >= 16-char secret and the result passes AppConfig validation; a disabled config gets no secret. - Also switch the two v41 script tests from a hardcoded "bash" to SCRIPT_BASH/skipif, matching the documented Windows constraint and the neighboring tests (hardcoded bash resolves to the WSL stub there). * chore(helm): sync chart config_version to 47 Review round 14 on #5577: check_config_version.sh fails whenever the chart's embedded config_version lags config.example.yaml, and the chart workflow is triggered by config.example.yaml — so the v47 bump left this head failing that check. Update the values.yaml config block and the README example to 47; scripts/check_config_version.sh now passes. --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
533 lines
24 KiB
Python
533 lines
24 KiB
Python
"""Pure-argument factory for DeerFlow agents.
|
|
|
|
``create_deerflow_agent`` accepts plain Python arguments — it does not load
|
|
YAML or install process-global runtime dependencies. It is the SDK-level entry
|
|
point sitting between the raw
|
|
``langchain.agents.create_agent`` primitive and the config-driven
|
|
``make_lead_agent`` application factory.
|
|
|
|
Direct callers that need an isolated native-subagent capacity or a durable
|
|
batch worker pass a caller-owned ``SubagentRuntime`` explicitly. When omitted,
|
|
subagent tools retain their application-compatible process-global fallback.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from typing import TYPE_CHECKING
|
|
|
|
from langchain.agents import create_agent
|
|
from langchain.agents.middleware import AgentMiddleware
|
|
|
|
from deerflow.agents.features import RuntimeFeatures
|
|
from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
|
|
from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
|
|
from deerflow.agents.middlewares.tool_error_handling_middleware import ToolErrorHandlingMiddleware
|
|
from deerflow.agents.thread_state import adapt_state_schema_for_mode, get_thread_state_schema, normalize_middleware_state_schemas
|
|
from deerflow.config.database_config import CheckpointChannelMode
|
|
from deerflow.tools.builtins import ask_clarification_tool
|
|
|
|
if TYPE_CHECKING:
|
|
from langchain_core.language_models import BaseChatModel
|
|
from langchain_core.tools import BaseTool
|
|
from langgraph.checkpoint.base import BaseCheckpointSaver
|
|
from langgraph.graph.state import CompiledStateGraph
|
|
|
|
from deerflow.config.memory_config import MemoryConfig
|
|
from deerflow.config.pii_redaction_config import PiiRedactionConfig
|
|
from deerflow.subagents.runtime import SubagentRuntime
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# TodoMiddleware prompts (minimal SDK version)
|
|
# ---------------------------------------------------------------------------
|
|
|
|
_TODO_SYSTEM_PROMPT = """
|
|
<todo_list_system>
|
|
You have access to the `write_todos` tool to help you manage and track complex multi-step objectives.
|
|
|
|
**CRITICAL RULES:**
|
|
- Mark todos as completed IMMEDIATELY after finishing each step - do NOT batch completions
|
|
- Keep EXACTLY ONE task as `in_progress` at any time (unless tasks can run in parallel)
|
|
- Update the todo list in REAL-TIME as you work - this gives users visibility into your progress
|
|
- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
|
|
</todo_list_system>
|
|
"""
|
|
|
|
_TODO_TOOL_DESCRIPTION = "Use this tool to create and manage a structured task list for complex work sessions. Only use for complex tasks (3+ steps)."
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Public API
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def create_deerflow_agent(
|
|
model: BaseChatModel,
|
|
tools: list[BaseTool] | None = None,
|
|
*,
|
|
system_prompt: str | None = None,
|
|
middleware: list[AgentMiddleware] | None = None,
|
|
features: RuntimeFeatures | None = None,
|
|
extra_middleware: list[AgentMiddleware] | None = None,
|
|
plan_mode: bool = False,
|
|
state_schema: type | None = None,
|
|
checkpoint_channel_mode: CheckpointChannelMode = "full",
|
|
checkpoint_snapshot_frequency: int | None = None,
|
|
checkpointer: BaseCheckpointSaver | None = None,
|
|
name: str = "default",
|
|
subagent_runtime: SubagentRuntime | None = None,
|
|
pii_redaction_config: PiiRedactionConfig | None = None,
|
|
) -> CompiledStateGraph:
|
|
"""Create a DeerFlow agent from plain Python arguments.
|
|
|
|
The factory assembly itself reads no config files. Pass ``subagent_runtime``
|
|
when direct SDK-created graphs must share an explicit native-subagent
|
|
capacity or caller-managed durable batch worker.
|
|
|
|
Parameters
|
|
----------
|
|
model:
|
|
Chat model instance.
|
|
tools:
|
|
User-provided tools. Feature-injected tools are appended automatically.
|
|
system_prompt:
|
|
System message. ``None`` uses a minimal default.
|
|
middleware:
|
|
**Full takeover** — if provided, this exact list is used.
|
|
Cannot be combined with *features* or *extra_middleware*.
|
|
features:
|
|
Declarative feature flags. Cannot be combined with *middleware*.
|
|
extra_middleware:
|
|
Additional middlewares inserted into the auto-assembled chain via
|
|
``@Next``/``@Prev`` positioning. Cannot be used with *middleware*.
|
|
plan_mode:
|
|
Enable TodoMiddleware for task tracking.
|
|
state_schema:
|
|
LangGraph state type. Defaults to ``ThreadState``.
|
|
checkpoint_channel_mode:
|
|
Checkpoint representation for accumulating channels. Defaults to the
|
|
full-state compatibility schema. ``"delta"`` requires the guarded
|
|
persistence paths (mode markers + compatibility gate) and is therefore
|
|
rejected when combined with *checkpointer* in this factory; without a
|
|
checkpointer the graph is ephemeral and delta is allowed.
|
|
checkpoint_snapshot_frequency:
|
|
DeltaChannel snapshot cadence for ``"delta"`` mode. ``None`` uses the
|
|
process-frozen value, falling back to the config default. Ignored in
|
|
``"full"`` mode.
|
|
checkpointer:
|
|
Optional persistence backend.
|
|
name:
|
|
Agent name (passed to middleware that cares, e.g. ``MemoryMiddleware``).
|
|
subagent_runtime:
|
|
Explicit process runtime shared by direct SDK-created graphs. Required
|
|
only when the caller needs non-default native-subagent capacity or a
|
|
caller-managed durable batch worker without Gateway/DeerFlowClient
|
|
startup. Requires ``features.subagent`` to be enabled.
|
|
pii_redaction_config:
|
|
Optional PII redaction policy (#3190). ``None`` leaves redaction off;
|
|
when enabled, memory-queue and durable-context redaction apply to the
|
|
assembled middlewares. A ``middleware=`` takeover bypasses the
|
|
assembly that would apply it.
|
|
|
|
Raises
|
|
------
|
|
ValueError
|
|
If both *middleware* and *features*/*extra_middleware* are provided.
|
|
"""
|
|
if middleware is not None and features is not None:
|
|
raise ValueError("Cannot specify both 'middleware' and 'features'. Use one or the other.")
|
|
if checkpoint_channel_mode == "delta" and checkpointer is not None:
|
|
raise ValueError(
|
|
"create_deerflow_agent does not support checkpoint_channel_mode='delta' with a checkpointer: "
|
|
"persisted graphs built here bypass checkpoint mode marker injection and the fail-closed "
|
|
"compatibility gate (see deerflow.runtime.checkpoint_mode), so a mixed-mode store would "
|
|
"silently corrupt thread state. Use the guarded application paths (make_lead_agent or "
|
|
"DeerFlowClient) for delta persistence; delta without a checkpointer is ephemeral and allowed."
|
|
)
|
|
if middleware is not None and extra_middleware:
|
|
raise ValueError("Cannot use 'extra_middleware' with 'middleware' (full takeover).")
|
|
if subagent_runtime is not None and (middleware is not None or features is None or features.subagent is False):
|
|
raise ValueError("subagent_runtime requires features.subagent to be enabled; it cannot be used with middleware full takeover")
|
|
if subagent_runtime is not None and subagent_runtime.batch_config is not None and subagent_runtime.batch_submitter is None:
|
|
raise RuntimeError("The explicit durable batch worker is not running; await subagent_runtime.start() or enter it with 'async with' before calling create_deerflow_agent")
|
|
if extra_middleware:
|
|
for mw in extra_middleware:
|
|
if not isinstance(mw, AgentMiddleware):
|
|
raise TypeError(f"extra_middleware items must be AgentMiddleware instances, got {type(mw).__name__}")
|
|
|
|
effective_tools: list[BaseTool] = list(tools or [])
|
|
effective_state = get_thread_state_schema(checkpoint_channel_mode, checkpoint_snapshot_frequency) if state_schema is None else adapt_state_schema_for_mode(state_schema, checkpoint_channel_mode, checkpoint_snapshot_frequency)
|
|
|
|
if middleware is not None:
|
|
effective_middleware = list(middleware)
|
|
else:
|
|
feat = features or RuntimeFeatures()
|
|
effective_middleware, extra_tools = _assemble_from_features(
|
|
feat,
|
|
name=name,
|
|
plan_mode=plan_mode,
|
|
extra_middleware=extra_middleware or [],
|
|
subagent_runtime=subagent_runtime,
|
|
pii_redaction_config=pii_redaction_config,
|
|
)
|
|
# Deduplicate by tool name — user-provided tools take priority.
|
|
existing_names = {t.name for t in effective_tools}
|
|
for t in extra_tools:
|
|
if t.name not in existing_names:
|
|
effective_tools.append(t)
|
|
existing_names.add(t.name)
|
|
|
|
effective_middleware = normalize_middleware_state_schemas(
|
|
effective_middleware,
|
|
checkpoint_channel_mode,
|
|
checkpoint_snapshot_frequency,
|
|
)
|
|
|
|
return create_agent(
|
|
model=model,
|
|
tools=effective_tools or None,
|
|
middleware=effective_middleware,
|
|
system_prompt=system_prompt,
|
|
state_schema=effective_state,
|
|
checkpointer=checkpointer,
|
|
name=name,
|
|
)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Internal: feature-driven middleware assembly
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def _assemble_from_features(
|
|
feat: RuntimeFeatures,
|
|
*,
|
|
name: str = "default",
|
|
plan_mode: bool = False,
|
|
extra_middleware: list[AgentMiddleware] | None = None,
|
|
subagent_runtime: SubagentRuntime | None = None,
|
|
pii_redaction_config: PiiRedactionConfig | None = None,
|
|
) -> tuple[list[AgentMiddleware], list[BaseTool]]:
|
|
"""Build an ordered middleware chain + extra tools from *feat*.
|
|
|
|
Middleware order matches ``make_lead_agent`` (14 middlewares):
|
|
|
|
0-2. Sandbox infrastructure (ThreadData → Uploads → Sandbox)
|
|
3. DanglingToolCallMiddleware (always)
|
|
4. GuardrailMiddleware (guardrail feature)
|
|
5. ToolErrorHandlingMiddleware (always)
|
|
5a. DurableContextMiddleware (always)
|
|
5b. SystemMessageCoalescingMiddleware (always)
|
|
6. SummarizationMiddleware (summarization feature)
|
|
7. TodoMiddleware (plan_mode parameter)
|
|
8. TitleMiddleware (auto_title feature)
|
|
9. MemoryMiddleware (memory feature)
|
|
10. ViewImageMiddleware (vision feature)
|
|
11. SubagentLimitMiddleware (subagent feature)
|
|
12. LoopDetectionMiddleware (loop_detection feature)
|
|
13. ClarificationMiddleware (always last)
|
|
|
|
Two-phase ordering:
|
|
1. Built-in chain — fixed sequential append.
|
|
2. Extra middleware — inserted via @Next/@Prev.
|
|
|
|
Each feature value is handled as:
|
|
- ``False``: skip
|
|
- ``True``: create the built-in default middleware (not available for
|
|
``summarization`` and ``guardrail`` — these require a custom instance)
|
|
- ``AgentMiddleware`` instance: use directly (custom replacement)
|
|
"""
|
|
chain: list[AgentMiddleware] = []
|
|
extra_tools: list[BaseTool] = []
|
|
|
|
# --- [0-2] Sandbox infrastructure ---
|
|
if feat.sandbox is not False:
|
|
if isinstance(feat.sandbox, AgentMiddleware):
|
|
chain.append(feat.sandbox)
|
|
else:
|
|
from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
|
|
from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware
|
|
from deerflow.sandbox.middleware import SandboxMiddleware
|
|
|
|
chain.append(ThreadDataMiddleware(lazy_init=True))
|
|
chain.append(UploadsMiddleware())
|
|
chain.append(SandboxMiddleware(lazy_init=True))
|
|
|
|
# --- [3] DanglingToolCall (always) ---
|
|
chain.append(DanglingToolCallMiddleware())
|
|
|
|
# --- [4] Guardrail ---
|
|
if feat.guardrail is not False:
|
|
if isinstance(feat.guardrail, AgentMiddleware):
|
|
chain.append(feat.guardrail)
|
|
else:
|
|
raise ValueError("guardrail=True requires a custom AgentMiddleware instance (no built-in GuardrailMiddleware yet)")
|
|
|
|
# --- [5] ToolErrorHandling (always) ---
|
|
chain.append(ToolErrorHandlingMiddleware())
|
|
|
|
# --- [5a] DurableContext (always) ---
|
|
# Summarization moves compacted history into ``summary_text``, and
|
|
# SubagentLimitMiddleware counts the run's delegations from the
|
|
# ``delegations`` ledger. This middleware writes that ledger and projects
|
|
# both into model requests. It sits ahead of summarization, as in
|
|
# make_lead_agent, so delegations are captured before they are compacted.
|
|
from deerflow.agents.middlewares.durable_context_middleware import DurableContextMiddleware
|
|
from deerflow.agents.middlewares.system_message_coalescing_middleware import SystemMessageCoalescingMiddleware
|
|
|
|
if pii_redaction_config is not None and pii_redaction_config.enabled:
|
|
from deerflow.agents.middlewares.pii_redaction_middleware import PiiRedactionMiddleware
|
|
|
|
chain.append(PiiRedactionMiddleware(pii_redaction_config))
|
|
|
|
chain.append(DurableContextMiddleware(pii_redaction_config=pii_redaction_config))
|
|
# DurableContext adds its authority contract as a second SystemMessage; strict backends
|
|
# (vLLM, SGLang, Qwen, Anthropic) reject that, so merge them into one leading message.
|
|
chain.append(SystemMessageCoalescingMiddleware())
|
|
|
|
# --- [6] Summarization ---
|
|
if feat.summarization is not False:
|
|
if isinstance(feat.summarization, AgentMiddleware):
|
|
chain.append(feat.summarization)
|
|
else:
|
|
raise ValueError("summarization=True requires a custom AgentMiddleware instance (SummarizationMiddleware needs a model argument)")
|
|
|
|
# --- [7] TodoMiddleware (plan_mode) ---
|
|
if plan_mode:
|
|
from deerflow.agents.middlewares.todo_middleware import TodoMiddleware
|
|
|
|
chain.append(TodoMiddleware(system_prompt=_TODO_SYSTEM_PROMPT, tool_description=_TODO_TOOL_DESCRIPTION))
|
|
|
|
# --- [8] Auto Title ---
|
|
if feat.auto_title is not False:
|
|
if isinstance(feat.auto_title, AgentMiddleware):
|
|
chain.append(feat.auto_title)
|
|
else:
|
|
from deerflow.agents.middlewares.title_middleware import TitleMiddleware
|
|
|
|
chain.append(TitleMiddleware())
|
|
|
|
# --- [9] Memory ---
|
|
if feat.memory is not False:
|
|
if isinstance(feat.memory, AgentMiddleware):
|
|
chain.append(feat.memory)
|
|
else:
|
|
from deerflow.config.memory_config import get_memory_config, should_use_memory_tools
|
|
|
|
memory_cfg: MemoryConfig = feat.memory_config or get_memory_config()
|
|
if should_use_memory_tools(memory_cfg):
|
|
from deerflow.agents.memory.manager import backend_requires_passive_writes_in_tool_mode
|
|
from deerflow.agents.memory.tools import get_memory_tools
|
|
|
|
existing_names = {tool.name for tool in extra_tools}
|
|
for memory_tool in get_memory_tools():
|
|
if memory_tool.name in existing_names:
|
|
logger.warning("Memory tool name %r already exists and was skipped.", memory_tool.name)
|
|
continue
|
|
extra_tools.append(memory_tool)
|
|
existing_names.add(memory_tool.name)
|
|
if backend_requires_passive_writes_in_tool_mode(memory_cfg.manager_class):
|
|
from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
|
|
|
|
chain.append(
|
|
MemoryMiddleware(
|
|
agent_name=name,
|
|
memory_config=memory_cfg,
|
|
pii_redaction_config=pii_redaction_config,
|
|
)
|
|
)
|
|
else:
|
|
if memory_cfg.mode == "tool" and not memory_cfg.enabled:
|
|
logger.warning("memory.mode is 'tool' but memory.enabled is false; memory tools will not be registered.")
|
|
from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
|
|
|
|
chain.append(
|
|
MemoryMiddleware(
|
|
agent_name=name,
|
|
memory_config=memory_cfg,
|
|
pii_redaction_config=pii_redaction_config,
|
|
)
|
|
)
|
|
|
|
# --- [10] Vision ---
|
|
if feat.vision is not False:
|
|
if isinstance(feat.vision, AgentMiddleware):
|
|
chain.append(feat.vision)
|
|
else:
|
|
from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
|
|
|
|
chain.append(ViewImageMiddleware())
|
|
|
|
if feat.sandbox is not False:
|
|
from deerflow.tools.builtins import view_image_tool
|
|
|
|
extra_tools.append(view_image_tool)
|
|
|
|
# --- [11] Subagent ---
|
|
if feat.subagent is not False:
|
|
if isinstance(feat.subagent, AgentMiddleware):
|
|
chain.append(feat.subagent)
|
|
else:
|
|
from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
|
|
from deerflow.config.subagents_config import DEFAULT_MAX_TOTAL_SUBAGENTS_PER_RUN
|
|
from deerflow.subagents.capacity import configured_subagent_max_running
|
|
|
|
max_concurrent = subagent_runtime.config.max_running if subagent_runtime is not None else configured_subagent_max_running()
|
|
max_total = subagent_runtime.max_total_per_run if subagent_runtime is not None else DEFAULT_MAX_TOTAL_SUBAGENTS_PER_RUN
|
|
chain.append(
|
|
SubagentLimitMiddleware(
|
|
max_concurrent=max_concurrent,
|
|
max_total=max_total,
|
|
)
|
|
)
|
|
from deerflow.tools.builtins import task_tool
|
|
|
|
if subagent_runtime is None:
|
|
extra_tools.append(task_tool)
|
|
else:
|
|
from deerflow.tools.builtins.task_tool import bind_task_tool
|
|
|
|
extra_tools.append(
|
|
bind_task_tool(
|
|
subagent_runtime.execution_capacity,
|
|
app_config=subagent_runtime.app_config,
|
|
)
|
|
)
|
|
|
|
if subagent_runtime is not None and subagent_runtime.batch_submitter is not None:
|
|
from deerflow.tools.builtins.batch_task_tool import bind_batch_tools
|
|
|
|
extra_tools.extend(
|
|
bind_batch_tools(
|
|
submitter_provider=lambda: subagent_runtime.batch_submitter,
|
|
app_config=subagent_runtime.app_config,
|
|
)
|
|
)
|
|
elif subagent_runtime is None:
|
|
from deerflow.subagents.batch_runtime import is_subagent_batch_runtime_available
|
|
|
|
if is_subagent_batch_runtime_available():
|
|
from deerflow.tools.builtins import batch_status, batch_task, cancel_batch
|
|
|
|
extra_tools.extend((batch_task, batch_status, cancel_batch))
|
|
|
|
# --- [12] LoopDetection ---
|
|
if feat.loop_detection is not False:
|
|
if isinstance(feat.loop_detection, AgentMiddleware):
|
|
chain.append(feat.loop_detection)
|
|
else:
|
|
from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
|
|
from deerflow.config.loop_detection_config import LoopDetectionConfig
|
|
|
|
chain.append(LoopDetectionMiddleware.from_config(LoopDetectionConfig()))
|
|
|
|
# --- [13] TokenBudget ---
|
|
if feat.token_budget is not False:
|
|
if isinstance(feat.token_budget, AgentMiddleware):
|
|
chain.append(feat.token_budget)
|
|
else:
|
|
from deerflow.agents.middlewares.token_budget_middleware import TokenBudgetMiddleware
|
|
from deerflow.config.token_budget_config import TokenBudgetConfig
|
|
|
|
# ``enabled`` defaults to False for config.yaml; ``token_budget=True`` is the opt-in.
|
|
chain.append(TokenBudgetMiddleware.from_config(TokenBudgetConfig(enabled=True)))
|
|
|
|
# --- [14] Clarification (always last among built-ins) ---
|
|
chain.append(ClarificationMiddleware())
|
|
extra_tools.append(ask_clarification_tool)
|
|
|
|
# --- Insert extra_middleware via @Next/@Prev ---
|
|
if extra_middleware:
|
|
_insert_extra(chain, extra_middleware)
|
|
# Invariant: ClarificationMiddleware must always be last.
|
|
# @Next(ClarificationMiddleware) could push it off the tail.
|
|
clar_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
|
|
if clar_idx != len(chain) - 1:
|
|
chain.append(chain.pop(clar_idx))
|
|
|
|
return chain, extra_tools
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Internal: extra middleware insertion with @Next/@Prev
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def _insert_extra(chain: list[AgentMiddleware], extras: list[AgentMiddleware]) -> None:
|
|
"""Insert extra middlewares into *chain* using ``@Next``/``@Prev`` anchors.
|
|
|
|
Algorithm:
|
|
1. Validate: no middleware has both @Next and @Prev.
|
|
2. Conflict detection: two extras targeting same anchor (same or opposite direction) → error.
|
|
3. Insert unanchored extras before ClarificationMiddleware.
|
|
4. Insert anchored extras iteratively (supports cross-external anchoring).
|
|
5. If an anchor cannot be resolved after all rounds → error.
|
|
"""
|
|
next_targets: dict[type, type] = {}
|
|
prev_targets: dict[type, type] = {}
|
|
|
|
anchored: list[tuple[AgentMiddleware, str, type]] = []
|
|
unanchored: list[AgentMiddleware] = []
|
|
|
|
for mw in extras:
|
|
next_anchor = getattr(type(mw), "_next_anchor", None)
|
|
prev_anchor = getattr(type(mw), "_prev_anchor", None)
|
|
|
|
if next_anchor and prev_anchor:
|
|
raise ValueError(f"{type(mw).__name__} cannot have both @Next and @Prev")
|
|
|
|
if next_anchor:
|
|
if next_anchor in next_targets:
|
|
raise ValueError(f"Conflict: {type(mw).__name__} and {next_targets[next_anchor].__name__} both @Next({next_anchor.__name__})")
|
|
if next_anchor in prev_targets:
|
|
raise ValueError(f"Conflict: {type(mw).__name__} @Next({next_anchor.__name__}) and {prev_targets[next_anchor].__name__} @Prev({next_anchor.__name__}) — use cross-anchoring between extras instead")
|
|
next_targets[next_anchor] = type(mw)
|
|
anchored.append((mw, "next", next_anchor))
|
|
elif prev_anchor:
|
|
if prev_anchor in prev_targets:
|
|
raise ValueError(f"Conflict: {type(mw).__name__} and {prev_targets[prev_anchor].__name__} both @Prev({prev_anchor.__name__})")
|
|
if prev_anchor in next_targets:
|
|
raise ValueError(f"Conflict: {type(mw).__name__} @Prev({prev_anchor.__name__}) and {next_targets[prev_anchor].__name__} @Next({prev_anchor.__name__}) — use cross-anchoring between extras instead")
|
|
prev_targets[prev_anchor] = type(mw)
|
|
anchored.append((mw, "prev", prev_anchor))
|
|
else:
|
|
unanchored.append(mw)
|
|
|
|
# Unanchored → before ClarificationMiddleware
|
|
clarification_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
|
|
for mw in unanchored:
|
|
chain.insert(clarification_idx, mw)
|
|
clarification_idx += 1
|
|
|
|
# Anchored → iterative insertion (supports external-to-external anchoring)
|
|
pending = list(anchored)
|
|
max_rounds = len(pending) + 1
|
|
for _ in range(max_rounds):
|
|
if not pending:
|
|
break
|
|
remaining = []
|
|
for mw, direction, anchor in pending:
|
|
idx = next(
|
|
(i for i, m in enumerate(chain) if isinstance(m, anchor)),
|
|
None,
|
|
)
|
|
if idx is None:
|
|
remaining.append((mw, direction, anchor))
|
|
continue
|
|
if direction == "next":
|
|
chain.insert(idx + 1, mw)
|
|
else:
|
|
chain.insert(idx, mw)
|
|
if len(remaining) == len(pending):
|
|
names = [type(m).__name__ for m, _, _ in remaining]
|
|
anchor_types = {a for _, _, a in remaining}
|
|
remaining_types = {type(m) for m, _, _ in remaining}
|
|
circular = anchor_types & remaining_types
|
|
if circular:
|
|
raise ValueError(f"Circular dependency among extra middlewares: {', '.join(t.__name__ for t in circular)}")
|
|
raise ValueError(f"Cannot resolve positions for {', '.join(names)} — anchors {', '.join(a.__name__ for _, _, a in remaining)} not found in chain")
|
|
pending = remaining
|