langchain-ai/deepagents · error · ValueError

Invalid agent name: {agent_name!r} is reserved for dcode's o

Error message

Invalid agent name: {agent_name!r} is reserved for dcode's own state.

What it means

After the character check, _validate_agent_name rejects agent names that collide with names dcode reserves for its own internal state (via is_reserved_agent_dir_name). These names cannot be used as agent profile directories because they would be ambiguous with dcode's own storage.

Source

Thrown at libs/code/deepagents_code/_paths.py:267

    Raises:
        ValueError: If the name is empty, unsafe, or reserved by dcode.
    """
    if (
        not agent_name
        or not agent_name.strip()
        or not re.fullmatch(r"[a-zA-Z0-9_\-\s]+", agent_name)
    ):
        msg = (
            f"Invalid agent name: {agent_name!r}. Agent names can only "
            "contain letters, numbers, hyphens, underscores, and spaces."
        )
        raise ValueError(msg)
    from deepagents_code._reserved_names import is_reserved_agent_dir_name

    if is_reserved_agent_dir_name(agent_name):
        msg = f"Invalid agent name: {agent_name!r} is reserved for dcode's own state."
        raise ValueError(msg)


def get_agent_dir(agent_name: str) -> Path:
    """Return the validated profile directory for an agent name.

    Args:
        agent_name: Agent profile name.

    Returns:
        Path to the agent's profile directory.

    """
    _validate_agent_name(agent_name)
    return PATHS.profile.agent_dir(agent_name)


def ensure_agent_dir(agent_name: str) -> Path:
    """Create the validated profile directory for an agent.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rename the agent to a non-reserved name.
2. Check deepagents_code._reserved_names.is_reserved_agent_dir_name before creating agents to pre-filter names.
3. If migrating configs, prefix reserved-looking names (e.g. 'my-state').

Example fix

// before
get_agent_dir("cache")  // reserved
// after
get_agent_dir("my-cache")

from deepagents_code._reserved_names import is_reserved_agent_dir_name
def name_available(name: str) -> bool:
    return not is_reserved_agent_dir_name(name)

try:
    agent_dir = get_agent_dir(name)
except ValueError as exc:
    if 'reserved' in str(exc):
        name = f"agent-{name}"
        agent_dir = get_agent_dir(name)
    else:
        raise

When it happens

Trigger: Calling get_agent_dir(name) where name is a reserved directory name (e.g. internal dcode state directories) — check the returned message for the specific reserved name.

Common situations: Creating an agent literally named after an internal directory like 'state' or a reserved keyword; importing shared agent configs that happen to use a reserved word.

Related errors

• trusted_ask_user_tool must be named ask_user
• trusted_compaction_tool must be named compact_conversation
• Invalid server name {server_name!r}: server names must conta
• Invalid plugin name: {name!r}
• Invalid plugin name: {name!r}

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