langchain-ai/deepagents · error · ValueError

HarnessProfileConfig.from_harness_profile() cannot serialize

Error message

HarnessProfileConfig.from_harness_profile() cannot serialize `excluded_middleware` class {entry.__name__!r}: it has no public `serialized_name` alias, and arbitrary class-path serialization is not currently supported. Either add a `serialized_name: ClassVar[str]` to the class for stable round-trips, or exclude it by `.name` instead.

What it means

When serializing a runtime `HarnessProfile` back to config form via `from_harness_profile()`, an `excluded_middleware` entry that is a middleware class must declare a `serialized_name: ClassVar[str]` for a stable round-trip. Arbitrary class-path serialization is intentionally unsupported, so anonymous or alias-less classes cannot be written to config.

Source

Thrown at libs/deepagents/deepagents/profiles/harness/harness_profiles.py:937

    Class entries are only serializable when the class advertises a public
    `serialized_name` alias; arbitrary class-path serialization is not
    currently supported.
    """
    if isinstance(entry, str):
        return entry

    alias = getattr(entry, "serialized_name", None)
    if isinstance(alias, str) and alias:
        return alias

    msg = (
        "HarnessProfileConfig.from_harness_profile() cannot serialize "
        f"`excluded_middleware` class {entry.__name__!r}: it has no public "
        "`serialized_name` alias, and arbitrary class-path serialization is "
        "not currently supported. Either add a `serialized_name: ClassVar[str]` "
        "to the class for stable round-trips, or exclude it by `.name` instead."
    )
    raise ValueError(msg)


_HARNESS_PROFILES: dict[str, HarnessProfile] = {}
"""Internal registry mapping harness-profile keys to `HarnessProfile` instances.

Keys are either a full `provider:model` spec for per-model overrides or a
bare provider name for provider-wide defaults. Lookup order is exact spec,
then provider prefix, then no match (returns `None`).
"""


def _ensure_harness_profiles_loaded() -> None:
    """Ensure the lazy built-in/profile-plugin bootstrap has completed."""
    from deepagents.profiles._builtin_profiles import _ensure_builtin_profiles_loaded  # noqa: PLC0415

    _ensure_builtin_profiles_loaded()

View on GitHub (pinned to a1af029e6e)

Solutions

Add `serialized_name: ClassVar[str] = "my_middleware"` to the middleware class
Exclude the middleware by its `.name` string instead of the class object
Exclude it after deserialization in code rather than round-tripping it through config

Example fix

# before
class MyMiddleware(AgentMiddleware):
    ...
# after
class MyMiddleware(AgentMiddleware):
    serialized_name: ClassVar[str] = "my_middleware"
    ...

Defensive patterns

Strategy: try-catch

Validate before calling

missing = [c for c in profile.excluded_middleware
           if isinstance(c, type) and not hasattr(c, "serialized_name")]
if missing:
    raise ValueError(f"middleware classes lack serialized_name: {missing}")

Type guard

def has_serialized_name(cls: type) -> TypeGuard[type[AgentMiddleware]]:
    return issubclass(cls, AgentMiddleware) and hasattr(cls, "serialized_name")

Try / catch

try:
    cfg = HarnessProfileConfig.from_harness_profile(profile)
except ValueError as e:
    if "serialized_name" in str(e):
        profile.excluded_middleware = [
            c.serialized_name if isinstance(c, type) and hasattr(c, "serialized_name") else c
            for c in profile.excluded_middleware
        ]
        cfg = HarnessProfileConfig.from_harness_profile(profile)
    else:
        raise

Prevention

Always declare `serialized_name: ClassVar[str]` on custom middleware classes
Exclude middleware by `.name` string when round-tripping through config is expected
Test serialize/deserialize round-trips for profiles containing custom middleware

When it happens

Trigger: Calling `HarnessProfileConfig.from_harness_profile(profile)` where `profile.excluded_middleware` contains a custom `AgentMiddleware` subclass without `serialized_name`.

Common situations: Excluding a locally defined custom middleware class and then attempting to persist/export the profile; third-party middleware classes that never defined `serialized_name`.

Related errors

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