Skip to content

normalize_role

autogen.llm_clients.models.unified_message.normalize_role #

normalize_role(role)

Normalize role string to UserRoleEnum for known roles, or return as-is for unknown roles.

This function converts standard role strings to type-safe UserRoleEnum values while preserving unknown/custom roles as plain strings for forward compatibility.

PARAMETER DESCRIPTION
role

Role string from API response (e.g., "user", "assistant", "system", "tool")

TYPE: str | None

RETURNS DESCRIPTION
UserRoleType

UserRoleEnum for known roles, or original string for unknown/custom roles

Examples:

>>> normalize_role("user")
UserRoleEnum.USER
>>> normalize_role("assistant")
UserRoleEnum.ASSISTANT
>>> normalize_role("custom_role")
"custom_role"
Source code in autogen/llm_clients/models/unified_message.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def normalize_role(role: str | None) -> UserRoleType:
    """
    Normalize role string to UserRoleEnum for known roles, or return as-is for unknown roles.

    This function converts standard role strings to type-safe UserRoleEnum values while
    preserving unknown/custom roles as plain strings for forward compatibility.

    Args:
        role: Role string from API response (e.g., "user", "assistant", "system", "tool")

    Returns:
        UserRoleEnum for known roles, or original string for unknown/custom roles

    Examples:
        >>> normalize_role("user")
        UserRoleEnum.USER
        >>> normalize_role("assistant")
        UserRoleEnum.ASSISTANT
        >>> normalize_role("custom_role")
        "custom_role"
    """
    if not role:
        return UserRoleEnum.ASSISTANT  # Default fallback

    # Map string roles to enum values
    role_mapping = {
        "user": UserRoleEnum.USER,
        "assistant": UserRoleEnum.ASSISTANT,
        "system": UserRoleEnum.SYSTEM,
        "tool": UserRoleEnum.TOOL,
    }

    # Return enum for known roles, original string for unknown roles
    return role_mapping.get(role.lower(), role)