langchain-ai/deepagents · error · TalonConfigError

assistant id must be 1-128 characters and contain only lette

Error message

assistant id must be 1-128 characters and contain only letters, numbers, underscore, hyphen, or dot

What it means

After resolving the assistant id, `_validate_assistant_id` enforces a format contract: 1–128 characters drawn only from letters, digits, underscore, hyphen, and dot (`_ASSISTANT_ID_PATTERN.fullmatch`). Ids used as filesystem/path or identifier components must be safe, so anything else raises `TalonConfigError`.

Source

Thrown at libs/talon/deepagents_talon/config.py:155

    default: str | None,
) -> str | None:
    for key in keys:
        if key in env:
            return env[key]
    return default


def _validate_assistant_id(assistant_id: str | None) -> None:
    if (
        not assistant_id
        or assistant_id in {".", ".."}
        or not _ASSISTANT_ID_PATTERN.fullmatch(assistant_id)
    ):
        msg = (
            "assistant id must be 1-128 characters and contain only letters, numbers, "
            "underscore, hyphen, or dot"
        )
        raise TalonConfigError(msg)


def _is_runtime_env(key: str) -> bool:
    return key in _RUNTIME_ENV_KEYS or key.startswith(_RUNTIME_ENV_PREFIXES)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Set the assistant id to a value matching ^[A-Za-z0-9._-]{1,128}$ (e.g. my-assistant.v2).
2. Trim whitespace and remove quoting artifacts from your .env or shell export.
3. If the id comes from another system, sanitize/slugify it before passing it into Talon.

Example fix

// before
export DEEPAGENTS_TALON_ASSISTANT_ID='my agent/prod!'
// after
export DEEPAGENTS_TALON_ASSISTANT_ID=my-agent-prod

import re
_ASSISTANT_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
def valid_assistant_id(value: str) -> bool:
    return bool(_ASSISTANT_ID_RE.fullmatch(value))

from typing import TypeGuard
def is_safe_assistant_id(value: str | None) -> TypeGuard[str]:
    return value is not None and bool(_ASSISTANT_ID_RE.fullmatch(value))

try:
    config = TalonConfig.from_env(os.environ)
except TalonConfigError as exc:
    logging.error("assistant id rejected: %s", exc)
    raise SystemExit(1)

When it happens

Trigger: `from_env` reads `DEEPAGENTS_TALON_ASSISTANT_ID` (or `AGENT_ASSISTANT_ID`) containing whitespace, slashes, unicode, an empty string, or a value longer than 128 chars; `_validate_assistant_id` then rejects it.

Common situations: Quoted values with stray spaces in .env files (`ASSISTANT_ID="my agent"`); ids containing `/` or `:` copied from URLs or ARN-like strings; shell interpolation injecting extra characters; overlong generated ids from other systems.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {what} must be absolute: {path}
• Home directory is not absolute: {launch_home}. Set $HOME to
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown fil
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex
• shell_allow_list must be None or non-empty

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