{"record":{"id":"128d93af1a418826","repo":"langchain-ai/deepagents","slug":"at-least-one-subagent-must-be-specified","errorCode":null,"errorMessage":"At least one subagent must be specified","messagePattern":"At least one subagent must be specified","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/middleware/subagents.py","lineNumber":685,"sourceCode":"    trace_policy = TracePolicy(process_inputs=omit_payload)\n    \"\"\"Omit hook inputs from traces by default; set a `TracePolicy` to override.\"\"\"\n\n    def __init__(\n        self,\n        *,\n        backend: BackendProtocol,\n        subagents: Sequence[SubAgent | CompiledSubAgent],\n        system_prompt: str | None = None,\n        task_description: str | None = None,\n        private_state_keys: frozenset[str] | None = None,\n        state_schema: type | None = None,\n    ) -> None:\n        \"\"\"Initialize the `SubAgentMiddleware`.\"\"\"\n        super().__init__()\n\n        if not subagents:\n            msg = \"At least one subagent must be specified\"\n            raise ValueError(msg)\n        self._backend = backend\n        self._subagents = subagents\n        self._private_state_keys = private_state_keys or frozenset()\n        self._task_description = task_description\n        self._state_schema = state_schema\n        self.subagent_names: frozenset[str] = frozenset(spec[\"name\"] for spec in subagents)\n        \"\"\"Declared subagent names. Public so streamers can discover them\n        without introspecting the `task` tool's closure.\"\"\"\n\n        task_tool = _build_task_tool(\n            self._subagents,\n            task_description,\n            private_state_keys=self._private_state_keys,\n            state_schema=self._state_schema,\n        )\n\n        # Build system prompt with available agents\n        if system_prompt and subagents:","sourceCodeStart":667,"sourceCodeEnd":703,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/middleware/subagents.py#L667-L703","documentation":"`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.","triggerScenarios":"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).","commonSituations":"Config-driven apps where the subagents section is empty; feature flags disabling all subagents; mistyped variable defaulting to an empty dict.","solutions":["Register at least one subagent spec or compiled subagent","If no subagents are needed, don't attach `SubAgentMiddleware` at all","Fix config loading so an empty section falls back to defaults or skips the middleware"],"exampleFix":"// before\nSubAgentMiddleware(subagents={})\n// after\nSubAgentMiddleware(subagents={\"researcher\": {\"name\": \"researcher\", \"model\": \"openai:gpt-4.1\", \"tools\": []}})","handlingStrategy":"validation","validationCode":"if not subagents:\n    raise ValueError(\"configure at least one subagent or omit SubAgentMiddleware\")\nmw = SubAgentMiddleware(subagents=subagents)","typeGuard":"def has_subagents(specs: dict) -> bool:\n    return bool(specs)","tryCatchPattern":"try:\n    mw = SubAgentMiddleware(subagents=config.get(\"subagents\", {}))\nexcept ValueError:\n    logger.warning(\"no subagents configured; skipping middleware\")\n    mw = None","preventionTips":["Validate config-derived subagent maps before constructing the middleware","Conditionally attach the middleware only when subagents exist","Add a startup assertion that required agent roles are registered"],"tags":["python","subagents","middleware","initialization"],"backgroundTag":"empty-collection-not-allowed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}