{"record":{"id":"7828043f1775c961","repo":"langchain-ai/deepagents","slug":"invalid-agent-name-agent-name-r-is-reserved-for","errorCode":null,"errorMessage":"Invalid agent name: {agent_name!r} is reserved for dcode's own state.","messagePattern":"Invalid agent name: (.+?) is reserved for dcode's own state\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_paths.py","lineNumber":267,"sourceCode":"\n    Raises:\n        ValueError: If the name is empty, unsafe, or reserved by dcode.\n    \"\"\"\n    if (\n        not agent_name\n        or not agent_name.strip()\n        or not re.fullmatch(r\"[a-zA-Z0-9_\\-\\s]+\", agent_name)\n    ):\n        msg = (\n            f\"Invalid agent name: {agent_name!r}. Agent names can only \"\n            \"contain letters, numbers, hyphens, underscores, and spaces.\"\n        )\n        raise ValueError(msg)\n    from deepagents_code._reserved_names import is_reserved_agent_dir_name\n\n    if is_reserved_agent_dir_name(agent_name):\n        msg = f\"Invalid agent name: {agent_name!r} is reserved for dcode's own state.\"\n        raise ValueError(msg)\n\n\ndef get_agent_dir(agent_name: str) -> Path:\n    \"\"\"Return the validated profile directory for an agent name.\n\n    Args:\n        agent_name: Agent profile name.\n\n    Returns:\n        Path to the agent's profile directory.\n\n    \"\"\"\n    _validate_agent_name(agent_name)\n    return PATHS.profile.agent_dir(agent_name)\n\n\ndef ensure_agent_dir(agent_name: str) -> Path:\n    \"\"\"Create the validated profile directory for an agent.","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_paths.py#L249-L285","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rename the agent to a non-reserved name.","Check deepagents_code._reserved_names.is_reserved_agent_dir_name before creating agents to pre-filter names.","If migrating configs, prefix reserved-looking names (e.g. 'my-state')."],"exampleFix":"// before\nget_agent_dir(\"cache\")  // reserved\n// after\nget_agent_dir(\"my-cache\")","handlingStrategy":"validation","validationCode":"from deepagents_code._reserved_names import is_reserved_agent_dir_name\ndef name_available(name: str) -> bool:\n    return not is_reserved_agent_dir_name(name)","typeGuard":null,"tryCatchPattern":"try:\n    agent_dir = get_agent_dir(name)\nexcept ValueError as exc:\n    if 'reserved' in str(exc):\n        name = f\"agent-{name}\"\n        agent_dir = get_agent_dir(name)\n    else:\n        raise","preventionTips":["Check is_reserved_agent_dir_name during agent onboarding/rename UX.","Maintain a deny-list test in CI for agent-name fixtures.","Prefix programmatically generated names to avoid collisions."],"tags":["validation","naming","reserved-names"],"backgroundTag":"reserved-name-conflict","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}