langchain-ai/deepagents · error · ValueError

At least one subagent must be specified

Error message

At least one subagent must be specified

What it means

`SubAgentMiddleware.__init__` refuses an empty `subagents` mapping: with zero subagents the `task` tool would have nothing valid to call, so the middleware raises `ValueError` at construction time rather than failing later at runtime.

Source

Thrown at libs/deepagents/deepagents/middleware/subagents.py:685

    trace_policy = TracePolicy(process_inputs=omit_payload)
    """Omit hook inputs from traces by default; set a `TracePolicy` to override."""

    def __init__(
        self,
        *,
        backend: BackendProtocol,
        subagents: Sequence[SubAgent | CompiledSubAgent],
        system_prompt: str | None = None,
        task_description: str | None = None,
        private_state_keys: frozenset[str] | None = None,
        state_schema: type | None = None,
    ) -> None:
        """Initialize the `SubAgentMiddleware`."""
        super().__init__()

        if not subagents:
            msg = "At least one subagent must be specified"
            raise ValueError(msg)
        self._backend = backend
        self._subagents = subagents
        self._private_state_keys = private_state_keys or frozenset()
        self._task_description = task_description
        self._state_schema = state_schema
        self.subagent_names: frozenset[str] = frozenset(spec["name"] for spec in subagents)
        """Declared subagent names. Public so streamers can discover them
        without introspecting the `task` tool's closure."""

        task_tool = _build_task_tool(
            self._subagents,
            task_description,
            private_state_keys=self._private_state_keys,
            state_schema=self._state_schema,
        )

        # Build system prompt with available agents
        if system_prompt and subagents:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Register at least one subagent spec or compiled subagent
2. If no subagents are needed, don't attach `SubAgentMiddleware` at all
3. Fix config loading so an empty section falls back to defaults or skips the middleware

Example fix

// before
SubAgentMiddleware(subagents={})
// after
SubAgentMiddleware(subagents={"researcher": {"name": "researcher", "model": "openai:gpt-4.1", "tools": []}})

if not subagents:
    raise ValueError("configure at least one subagent or omit SubAgentMiddleware")
mw = SubAgentMiddleware(subagents=subagents)

def has_subagents(specs: dict) -> bool:
    return bool(specs)

try:
    mw = SubAgentMiddleware(subagents=config.get("subagents", {}))
except ValueError:
    logger.warning("no subagents configured; skipping middleware")
    mw = None

When it happens

Trigger: Constructing `SubAgentMiddleware(subagents={})` or passing an empty/falsy subagents collection (also reachable via `create_deep_agent` with no subagents configured where the middleware is still instantiated).

Common situations: Config-driven apps where the subagents section is empty; feature flags disabling all subagents; mistyped variable defaulting to an empty dict.

Related errors

• SDK {name} tool is unavailable.
• SubAgent '{spec['name']}' must specify 'model'
• SubAgent '{spec['name']}' must specify 'tools'
• response_schema cannot be used with compiled subagent "{spec
• CompiledSubAgent must return a state containing a 'messages'

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/128d93af1a418826. Report an issue: GitHub.