Allow underscores in conversation tag keys

openhands-agent-server/openhands/agent_server/models.py

@@ -410,8 +410,8 @@ class UpdateConversationRequest(BaseModel):
         default=None,
         description=(
             "Key-value tags to set on the conversation. Keys must be lowercase "
-            "alphanumeric. Values are arbitrary strings up to 256 characters. "
-            "Replaces all existing tags when provided."
+            "alphanumeric (underscores allowed). Values are arbitrary strings "
+            "up to 256 characters. Replaces all existing tags when provided."
         ),
     )
 
@@ -432,7 +432,7 @@ class ForkConversationRequest(BaseModel):
         default=None,
         description=(
             "Optional tags for the forked conversation. Keys must be "
-            "lowercase alphanumeric."
+            "lowercase alphanumeric (underscores allowed)."
         ),
     )
     reset_metrics: bool = Field(

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -191,7 +191,8 @@ def __init__(
                    decrypted when loading. If not provided, secrets are redacted
                    (lost) on serialization.
             tags: Optional key-value tags for the conversation. Keys must be
-                  lowercase alphanumeric, values up to 256 characters.
+                  lowercase alphanumeric (underscores allowed),
+                  values up to 256 characters.
             client_tools: Optional list of client-defined tool specs. Each spec
                   is registered and injected into the agent so it can call the
                   tool; the executor returns an acknowledgment and the real

openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py

@@ -700,7 +700,8 @@ def __init__(
                        - None: No visualization
             secrets: Optional secrets to initialize the conversation with
             tags: Optional key-value tags for the conversation. Keys must be
-                  lowercase alphanumeric, values up to 256 characters.
+                  lowercase alphanumeric (underscores allowed),
+                  values up to 256 characters.
             user_id: Optional user ID to associate with observability traces
             client_tools: Optional list of client-defined tool specs. These tools
                       have no server-side executor — when the agent calls them an

openhands-sdk/openhands/sdk/conversation/request.py

@@ -179,7 +179,8 @@ class StartConversationRequest(BaseModel):
         default_factory=dict,
         description=(
             "Key-value tags for the conversation. Keys must be lowercase "
-            "alphanumeric. Values are arbitrary strings up to 256 characters."
+            "alphanumeric (underscores allowed). Values are arbitrary strings "
+            "up to 256 characters."
         ),
     )
     user_id: str | None = Field(

openhands-sdk/openhands/sdk/conversation/state.py

@@ -179,8 +179,8 @@ class ConversationState(OpenHandsModel):
     tags: ConversationTags = Field(
         default_factory=dict,
         description="User-defined key-value tags for the conversation. "
-        "Keys must be lowercase alphanumeric. Values are arbitrary strings "
-        "up to 256 characters.",
+        "Keys must be lowercase alphanumeric (underscores allowed). "
+        "Values are arbitrary strings up to 256 characters.",
     )
 
     # Agent-specific runtime state (simple dict for flexibility)
@@ -380,7 +380,8 @@ def create(
                     saving and decrypted when loading. If not provided, secrets
                     are redacted (lost) on serialization.
             tags: Optional key-value tags for the conversation. Keys must be
-                  lowercase alphanumeric, values up to 256 characters.
+                  lowercase alphanumeric (underscores allowed),
+                  values up to 256 characters.
 
         Returns:
             ConversationState ready for use

openhands-sdk/openhands/sdk/conversation/types.py

@@ -18,7 +18,7 @@
 ConversationID = uuid.UUID
 """Type alias for conversation IDs."""
 
-TAG_KEY_PATTERN = re.compile(r"^[a-z0-9]+$")
+TAG_KEY_PATTERN = re.compile(r"^[a-z0-9_]+$")
 TAG_VALUE_MAX_LENGTH = 256
 
 
@@ -28,7 +28,8 @@ def _validate_tags(v: dict[str, str] | None) -> dict[str, str]:
     for key, value in v.items():
         if not TAG_KEY_PATTERN.match(key):
             raise ValueError(
-                f"Tag key '{key}' is invalid: keys must be lowercase alphanumeric only"
+                f"Tag key '{key}' is invalid: keys must be lowercase alphanumeric "
+                "(underscores allowed)"
             )
         if len(value) > TAG_VALUE_MAX_LENGTH:
             raise ValueError(
@@ -41,7 +42,8 @@ def _validate_tags(v: dict[str, str] | None) -> dict[str, str]:
 ConversationTags = Annotated[dict[str, str], BeforeValidator(_validate_tags)]
 """Validated dict of conversation tags.
 
-Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 chars.
+Keys must be lowercase alphanumeric, with underscores allowed
+(e.g. ``selected_workspace``). Values are arbitrary strings up to 256 chars.
 """
 
 

tests/sdk/conversation/test_tags.py

@@ -34,16 +34,26 @@ def test_validate_tags_invalid_key_with_hyphen():
         _validate_tags({"my-key": "value"})
 
 
-def test_validate_tags_invalid_key_with_underscore():
-    with pytest.raises(ValueError, match="lowercase alphanumeric"):
-        _validate_tags({"my_key": "value"})
+def test_validate_tags_valid_key_with_underscore():
+    """Underscores are allowed so frontends can use snake_case keys like
+    ``selected_workspace`` and ``active_profile`` to attach UI-specific
+    metadata to a conversation without a separate localStorage store."""
+    result = _validate_tags({"my_key": "value", "selected_workspace": "/foo"})
+    assert result == {"my_key": "value", "selected_workspace": "/foo"}
 
 
 def test_validate_tags_invalid_key_with_spaces():
     with pytest.raises(ValueError, match="lowercase alphanumeric"):
         _validate_tags({"my key": "value"})
 
 
+def test_validate_tags_invalid_key_only_underscores():
+    """An underscore-only key is still considered a valid identifier under
+    the relaxed pattern; assert behaviour so future tightening surfaces."""
+    result = _validate_tags({"___": "value"})
+    assert result == {"___": "value"}
+
+
 def test_validate_tags_value_max_length():
     long_value = "x" * TAG_VALUE_MAX_LENGTH
     result = _validate_tags({"key": long_value})