{"record":{"id":"99565ec883fb5b14","repo":"langchain-ai/deepagents","slug":"response-schema-cannot-be-used-with-compiled-subag","errorCode":null,"errorMessage":"response_schema cannot be used with compiled subagent \"{spec[\"name\"]}\"; dynamic schemas require a raw SubAgent spec.","messagePattern":"response_schema cannot be used with compiled subagent \"(.+?)\"; dynamic schemas require a raw SubAgent spec\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/middleware/subagents.py","lineNumber":434,"sourceCode":"            uses default template. Supports `{available_agents}` placeholder.\n        private_state_keys: State keys marked with `PrivateStateAttr` that\n            should be stripped from parent state before invoking subagents.\n        state_schema: Base graph state schema forwarded to raw subagent specs.\n\n    Returns:\n        A StructuredTool that can invoke subagents by type.\n    \"\"\"\n\n    def _compile_spec(\n        spec: SubAgent | CompiledSubAgent,\n        *,\n        response_format: ResponseFormat[Any] | type | dict[str, Any] | None = None,\n    ) -> CompiledSubAgent:\n        \"\"\"Compile one raw spec or configure one provided runnable.\"\"\"\n        if \"runnable\" in spec:\n            if response_format is not None:\n                msg = f'response_schema cannot be used with compiled subagent \"{spec[\"name\"]}\"; dynamic schemas require a raw SubAgent spec.'\n                raise ValueError(msg)\n\n            # Use with_config (not attribute mutation) so the original runnable is\n            # untouched and a shared instance can be registered under multiple names.\n            compiled = cast(\"CompiledSubAgent\", spec)\n            runnable = compiled[\"runnable\"].with_config(\n                {\n                    \"metadata\": {\"lc_agent_name\": spec[\"name\"]},\n                    \"run_name\": spec[\"name\"],\n                }\n            )\n            return {\n                \"name\": spec[\"name\"],\n                \"description\": spec[\"description\"],\n                \"runnable\": runnable,\n            }\n        return {\n            \"name\": spec[\"name\"],\n            \"description\": spec[\"description\"],","sourceCodeStart":416,"sourceCodeEnd":452,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/middleware/subagents.py#L416-L452","documentation":"`_compile_spec` accepts either a raw declarative `SubAgent` spec or an already-compiled runnable (`CompiledSubAgent` with a `runnable` key). Structured-output `response_schema` can only be injected while compiling a raw spec; passing it alongside a pre-compiled subagent raises `ValueError` because the runnable is already built.","triggerScenarios":"Calling `task`/`SubAgentMiddleware` machinery with both a subagent entry whose dict contains `\"runnable\"` and a non-None `response_schema` argument.","commonSituations":"Mixing declarative and pre-compiled subagent registrations in one config; adding structured output support to an existing compiled-graph registration without converting it back to a raw spec.","solutions":["Remove `response_schema` for subagents registered as compiled runnables","Convert the entry to a raw declarative spec (model/tools/...) so `response_schema` can be applied at compile time","Bake structured output into the runnable itself (e.g. `with_structured_output`) before registering it"],"exampleFix":"// before\nmiddleware.task(response_schema=MySchema, subagents=[{\"name\": \"a\", \"runnable\": compiled}])\n// after\nsubagents=[{\"name\": \"a\", \"model\": \"openai:gpt-4.1\", \"tools\": [], \"response_schema\": MySchema}]","handlingStrategy":"validation","validationCode":"if response_schema is not None and \"runnable\" in spec:\n    raise TypeError(\"response_schema requires a raw SubAgent spec, not a compiled runnable\")","typeGuard":"def is_raw_spec(spec: dict) -> bool:\n    return \"runnable\" not in spec","tryCatchPattern":"try:\n    compile_spec(spec, response_format=schema)\nexcept ValueError as e:\n    logger.error(\"%s — convert to a raw spec or drop response_schema\", e)\n    raise","preventionTips":["Keep compiled and declarative subagent registrations in separate typed fields","Document that structured output only applies to raw specs","Prefer raw specs when structured output may be needed later"],"tags":["python","subagents","structured-output","incompatible-args"],"backgroundTag":"incompatible-parameter-combination","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}