langchain-ai/deepagents · error · ValueError

At least one async subagent must be specified

Error message

At least one async subagent must be specified

What it means

AsyncSubAgentMiddleware requires at least one async subagent; constructing it with an empty list (or empty dict-like) raises this ValueError immediately in __init__. The middleware has nothing to expose to the agent otherwise.

Source

Thrown at libs/deepagents/deepagents/middleware/async_subagents.py:895

        ```
    """

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

    state_schema = AsyncSubAgentState

    def __init__(
        self,
        *,
        async_subagents: list[AsyncSubAgent],
        system_prompt: str | None = None,
    ) -> None:
        """Initialize the `AsyncSubAgentMiddleware`."""
        super().__init__()
        if not async_subagents:
            msg = "At least one async subagent must be specified"
            raise ValueError(msg)

        names = [a["name"] for a in async_subagents]
        dupes = {n for n in names if names.count(n) > 1}
        if dupes:
            msg = f"Duplicate async subagent names: {dupes}"
            raise ValueError(msg)

        self.tools = _build_async_subagent_tools(async_subagents)

        if system_prompt:
            agents_desc = "\n".join(f"- {a['name']}: {a['description']}" for a in async_subagents)
            self.system_prompt: str | None = system_prompt + "\n\nAvailable async subagent types:\n\n" + agents_desc
        else:
            self.system_prompt = system_prompt

    def wrap_model_call(
        self,
        request: ModelRequest[ContextT],

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass at least one async subagent spec
2. Remove the middleware entirely if no async subagents are needed
3. Fix the config loading/flag logic that produced an empty list

Example fix

// before
AsyncSubAgentMiddleware(async_subagents=[])
// after
AsyncSubAgentMiddleware(async_subagents=[{"name": "researcher", "url": "http://localhost:8123"}])

if not async_subagents:
    raise ValueError("async_subagents must contain at least one spec (or omit the middleware)")

When it happens

Trigger: AsyncSubAgentMiddleware(async_subagents=[]) or async_subagents=None; building the list programmatically and it ends up empty at runtime.

Common situations: Feature-flagged subagent config resolving to no entries; refactoring that moved subagents elsewhere but left an empty middleware instantiation.

Related errors

• allow_list must not be empty; disable shell access instead
• interpreter_ptc='all' exposes every host tool to PTC calls t
• Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'al
• interpreter_ptc list entries cannot include 'all'; use 'all'
• interpreter_ptc must be False, 'safe', 'all', or a list of t

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