langchain-ai/deepagents · error · ValueError

SubAgent '{spec['name']}' must specify 'model'

Error message

SubAgent '{spec['name']}' must specify 'model'

What it means

`create_sub_agent` builds a runnable subagent from a declarative `SubAgent` dict spec. A spec must declare at least a `model` and `tools`; if the `model` key is absent the function raises `ValueError` immediately, because there is no way to construct the underlying agent LLM without it.

Source

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

    raw subagent specs. Pre-compiled `CompiledSubAgent` runnables are already
    created by the caller and are handled separately by `SubAgentMiddleware`.

    Args:
        spec: Subagent spec to compile. Must specify `model` and `tools`.
        state_schema: Base graph state schema forwarded to `create_agent` for
            the subagent.
        response_format: Optional response format override for this compiled
            subagent instance.

    Returns:
        Runnable agent ready for task-tool invocation.

    Raises:
        ValueError: If `spec` is missing `model` or `tools`.
    """
    if "model" not in spec:
        msg = f"SubAgent '{spec['name']}' must specify 'model'"
        raise ValueError(msg)
    if "tools" not in spec:
        msg = f"SubAgent '{spec['name']}' must specify 'tools'"
        raise ValueError(msg)

    from deepagents._models import resolve_model  # noqa: PLC0415

    model = resolve_model(spec["model"])
    middleware: list[AgentMiddleware] = list(spec.get("middleware", []))

    interrupt_on = spec.get("interrupt_on")
    if interrupt_on:
        middleware.append(HumanInTheLoopMiddleware(interrupt_on=interrupt_on))

    selected_response_format = response_format if response_format is not None else spec.get("response_format")
    create_agent_kwargs: dict[str, Any] = {
        "system_prompt": spec["system_prompt"],
        "tools": spec["tools"],
        "middleware": middleware,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Add a `model` key to the spec dict, e.g. `"model": "anthropic:claude-sonnet-4-5"` or a `BaseChatModel` instance
2. If the subagent should use the parent's model, copy it into the spec explicitly before calling
3. Validate required keys (`name`, `model`, `tools`) at spec-construction time

Example fix

// before
{"name": "researcher", "tools": [search_tool]}
// after
{"name": "researcher", "model": "anthropic:claude-sonnet-4-5", "tools": [search_tool]}

required = {"name", "model", "tools"}
missing = required - spec.keys()
if missing:
    raise ValueError(f"SubAgent spec missing: {sorted(missing)}")

def has_model(spec: dict) -> bool:
    return "model" in spec

try:
    agent = create_sub_agent(spec=spec)
except ValueError as e:
    logger.error("Bad subagent spec %r: %s", spec.get("name"), e)
    raise

When it happens

Trigger: Calling `create_sub_agent(spec=...)` (directly or via `_compile_spec` from `_build_task_tool`/`_select_subagent`) with a dict that has a `name` but no `model` key.

Common situations: Hand-writing subagent dicts and forgetting `model`; building specs programmatically from config files where the model field is optional/missing; migrating code that previously inherited the parent agent's default model.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• SubAgent '{spec['name']}' must specify 'tools'
• Invalid interpreter_ptc string {ptc!r}; expected 'safe', 'al
• interpreter_ptc list entries cannot include 'all'; use 'all'
• Tool call ID is required for subagent invocation
• timeout must be non-negative, got {timeout}

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