From 6b3fdfc47296564045a0021e2858f3bc170eb5cf Mon Sep 17 00:00:00 2001 From: tang-ontheway Date: Sun, 15 Nov 2026 00:30:37 +0800 Subject: [PATCH 1/2] Python: fix(devui): validate conversation metadata at the route boundary --- .../agent_framework_devui/_conversations.py | 60 ++++++++- .../devui/agent_framework_devui/_server.py | 7 +- .../tests/devui/test_conversation_metadata.py | 120 ++++++++++++++++++ 3 files changed, 181 insertions(+), 6 deletions(-) create mode 100644 python/packages/devui/tests/devui/test_conversation_metadata.py diff --git a/python/packages/devui/agent_framework_devui/_conversations.py b/python/packages/devui/agent_framework_devui/_conversations.py index 0977aaed7d7..5870bc89097 100644 --- a/python/packages/devui/agent_framework_devui/_conversations.py +++ b/python/packages/devui/agent_framework_devui/_conversations.py @@ -43,6 +43,54 @@ class ConversationItemValidationError(ValueError): """ +class ConversationMetadataValidationError(ValueError): + """The metadata of a conversation is not a map of string keys to string values. + + Raised instead of a plain ValueError so routes can answer with a client + error for malformed metadata while a missing conversation stays 404. + """ + + +def validate_conversation_metadata(metadata: Any) -> dict[str, str]: + """Validate conversation metadata against the Conversations API contract. + + Metadata is a map of string keys to string values. An explicit ``None`` is + accepted and normalized to an empty map, the same as a missing field. + + Args: + metadata: The metadata value taken from a request body. + + Returns: + The validated metadata map. + + Raises: + ConversationMetadataValidationError: If the metadata is not a map of + string keys to string values. + """ + if metadata is None: + return {} + if not isinstance(metadata, dict): + raise ConversationMetadataValidationError("metadata must be an object mapping string keys to string values") + invalid_values = [key for key, value in metadata.items() if not isinstance(value, str)] + if invalid_values: + raise ConversationMetadataValidationError( + "metadata values must be strings; invalid keys: " + ", ".join(sorted(str(key) for key in invalid_values)) + ) + return {str(key): value for key, value in metadata.items()} + + +def _stored_metadata(metadata: Any) -> dict[str, str]: + """Return the stored metadata as a map, ignoring a value that is not one. + + Metadata written before it was validated at the route boundary can be any + JSON value. Readers must not fail on it, so a value that is not a map is + reported as no metadata at all. + """ + if not isinstance(metadata, dict): + return {} + return {str(key): value for key, value in metadata.items() if isinstance(value, str)} + + def _refusal_additional_properties() -> dict[str, Any]: return { "core": {_MODEL_OUTPUT_KIND_KEY: _MODEL_OUTPUT_REFUSAL}, @@ -255,6 +303,7 @@ def create_conversation( """Create a new conversation with message storage and checkpoint storage.""" conv_id = conversation_id or f"conv_{uuid.uuid4().hex}" created_at = int(time.time()) + metadata = validate_conversation_metadata(metadata) # Create message list for internal storage and AgentSession for execution messages: list[Message] = [] @@ -268,7 +317,7 @@ def create_conversation( "messages": messages, "session": session, "checkpoint_storage": checkpoint_storage, - "metadata": metadata or {}, + "metadata": metadata, "created_at": created_at, "items": [], "traces": [], # Trace events for context inspection (token usage, timing, etc.) @@ -289,7 +338,7 @@ def get_conversation(self, conversation_id: str) -> Conversation | None: id=conv_data["id"], object="conversation", created_at=conv_data["created_at"], - metadata=conv_data.get("metadata"), + metadata=_stored_metadata(conv_data.get("metadata")), ) def update_conversation(self, conversation_id: str, metadata: dict[str, str]) -> Conversation: @@ -298,13 +347,14 @@ def update_conversation(self, conversation_id: str, metadata: dict[str, str]) -> if not conv_data: raise ValueError(f"Conversation {conversation_id} not found") - conv_data["metadata"] = metadata + validated = validate_conversation_metadata(metadata) + conv_data["metadata"] = validated return Conversation( id=conv_data["id"], object="conversation", created_at=conv_data["created_at"], - metadata=metadata, + metadata=validated, ) def delete_conversation(self, conversation_id: str) -> ConversationDeletedResource: @@ -844,7 +894,7 @@ async def list_conversations_by_metadata(self, metadata_filter: dict[str, str]) """Filter conversations by metadata (e.g., agent_id).""" results: list[Conversation] = [] for conv_data in self._conversations.values(): - conv_meta = conv_data.get("metadata", {}).copy() # Copy to avoid mutating original + conv_meta = _stored_metadata(conv_data.get("metadata")) # Copy to avoid mutating original # Check if all filter items match if all(conv_meta.get(k) == v for k, v in metadata_filter.items()): diff --git a/python/packages/devui/agent_framework_devui/_server.py b/python/packages/devui/agent_framework_devui/_server.py index 41c85b3d9fc..8325e93e0de 100644 --- a/python/packages/devui/agent_framework_devui/_server.py +++ b/python/packages/devui/agent_framework_devui/_server.py @@ -21,7 +21,7 @@ from fastapi.responses import JSONResponse, StreamingResponse from fastapi.staticfiles import StaticFiles -from ._conversations import ConversationItemValidationError +from ._conversations import ConversationItemValidationError, ConversationMetadataValidationError from ._deployment import DeploymentManager from ._discovery import EntityDiscovery from ._executor import AgentFrameworkExecutor @@ -1007,6 +1007,9 @@ async def create_conversation(raw_request: Request) -> dict[str, Any] | JSONResp executor = await self._ensure_executor() conversation = executor.conversation_store.create_conversation(metadata=metadata) return conversation.model_dump() + except ConversationMetadataValidationError as e: + error = OpenAIError.create(str(e), type="invalid_request_error", code="invalid_metadata") + return JSONResponse(status_code=400, content=error.to_dict()) except HTTPException: raise except Exception as e: @@ -1078,6 +1081,8 @@ async def update_conversation(conversation_id: str, request_data: dict[str, Any] metadata = request_data.get("metadata", {}) conversation = executor.conversation_store.update_conversation(conversation_id, metadata=metadata) return conversation.model_dump() + except ConversationMetadataValidationError as e: + raise HTTPException(status_code=400, detail=str(e)) from e except ValueError as e: raise HTTPException(status_code=404, detail=str(e)) from e except HTTPException: diff --git a/python/packages/devui/tests/devui/test_conversation_metadata.py b/python/packages/devui/tests/devui/test_conversation_metadata.py new file mode 100644 index 00000000000..3ad74699881 --- /dev/null +++ b/python/packages/devui/tests/devui/test_conversation_metadata.py @@ -0,0 +1,120 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Tests for conversation metadata validation in the DevUI conversation store and routes.""" + +import pytest +from fastapi.testclient import TestClient + +from agent_framework_devui import DevServer +from agent_framework_devui._conversations import ( + ConversationMetadataValidationError, + InMemoryConversationStore, +) + + +def test_create_conversation_rejects_non_map_metadata(): + """Metadata must be a map of string keys to string values.""" + store = InMemoryConversationStore() + + with pytest.raises(ConversationMetadataValidationError): + store.create_conversation(metadata="oops-not-a-dict") + + +def test_create_conversation_rejects_non_string_metadata_values(): + """A metadata value that is not a string is rejected.""" + store = InMemoryConversationStore() + + with pytest.raises(ConversationMetadataValidationError): + store.create_conversation(metadata={"agent_id": 7}) + + +def test_create_conversation_accepts_none_metadata(): + """An explicit ``None`` is normalized to an empty map.""" + store = InMemoryConversationStore() + + conversation = store.create_conversation(metadata=None) + + assert conversation.metadata == {} + + +def test_update_conversation_rejects_invalid_metadata_and_keeps_previous_value(): + """A rejected update leaves the stored metadata untouched.""" + store = InMemoryConversationStore() + created = store.create_conversation(metadata={"agent_id": "test_agent"}) + + with pytest.raises(ConversationMetadataValidationError): + store.update_conversation(created.id, metadata=["not", "a", "map"]) + + assert store.get_conversation(created.id).metadata == {"agent_id": "test_agent"} + + +def test_update_conversation_normalizes_none_metadata(): + """An explicit ``None`` clears the metadata instead of storing it.""" + store = InMemoryConversationStore() + created = store.create_conversation(metadata={"agent_id": "test_agent"}) + + updated = store.update_conversation(created.id, metadata=None) + + assert updated.metadata == {} + + +@pytest.mark.asyncio +async def test_list_conversations_survives_legacy_invalid_metadata(): + """Metadata stored before validation existed must not break the list endpoint.""" + store = InMemoryConversationStore() + created = store.create_conversation(metadata={"agent_id": "test_agent"}) + + # Simulate a conversation written before the metadata was validated. + store._conversations[created.id]["metadata"] = None + + listed = await store.list_conversations_by_metadata({}) + + assert [conv.id for conv in listed] == [created.id] + assert listed[0].metadata == {} + + +def test_create_conversation_route_rejects_invalid_metadata(): + """A create request with malformed metadata is a client error.""" + server = DevServer(mode="developer", auth_enabled=False) + app = server.get_app() + + with TestClient(app, base_url="http://127.0.0.1") as client: + response = client.post("/v1/conversations", json={"metadata": "oops-not-a-dict"}) + + assert response.status_code == 400 + + listing = client.get("/v1/conversations") + assert listing.status_code == 200 + + +def test_update_conversation_route_rejects_invalid_metadata(): + """An update request with malformed metadata is a client error, not a 404.""" + server = DevServer(mode="developer", auth_enabled=False) + app = server.get_app() + + with TestClient(app, base_url="http://127.0.0.1") as client: + created = client.post("/v1/conversations", json={"metadata": {"agent_id": "test_agent"}}) + assert created.status_code == 200 + conversation_id = created.json()["id"] + + response = client.post(f"/v1/conversations/{conversation_id}", json={"metadata": None}) + assert response.status_code == 200 + assert response.json()["metadata"] == {} + + invalid = client.post(f"/v1/conversations/{conversation_id}", json={"metadata": 5}) + assert invalid.status_code == 400 + + listing = client.get("/v1/conversations") + assert listing.status_code == 200 + assert [conv["id"] for conv in listing.json()["data"]] == [conversation_id] + + +def test_update_conversation_route_keeps_404_for_missing_conversation(): + """A missing conversation still answers with 404.""" + server = DevServer(mode="developer", auth_enabled=False) + app = server.get_app() + + with TestClient(app, base_url="http://127.0.0.1") as client: + response = client.post("/v1/conversations/does-not-exist", json={"metadata": {"agent_id": "a"}}) + + assert response.status_code == 404 From 8673f98a3f17d1102b5324927a198ce4154eb79a Mon Sep 17 00:00:00 2001 From: yifei tang Date: Mon, 16 Nov 2026 10:59:17 +0800 Subject: [PATCH 2/2] fix(devui): reject non-string metadata keys instead of coercing --- .../devui/agent_framework_devui/_conversations.py | 9 +++++++-- .../devui/tests/devui/test_conversation_metadata.py | 8 ++++++++ 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/python/packages/devui/agent_framework_devui/_conversations.py b/python/packages/devui/agent_framework_devui/_conversations.py index 5870bc89097..1af51ff414b 100644 --- a/python/packages/devui/agent_framework_devui/_conversations.py +++ b/python/packages/devui/agent_framework_devui/_conversations.py @@ -71,12 +71,17 @@ def validate_conversation_metadata(metadata: Any) -> dict[str, str]: return {} if not isinstance(metadata, dict): raise ConversationMetadataValidationError("metadata must be an object mapping string keys to string values") + invalid_keys = [key for key in metadata if not isinstance(key, str)] + if invalid_keys: + raise ConversationMetadataValidationError( + "metadata keys must be strings; invalid keys: " + ", ".join(sorted(repr(key) for key in invalid_keys)) + ) invalid_values = [key for key, value in metadata.items() if not isinstance(value, str)] if invalid_values: raise ConversationMetadataValidationError( - "metadata values must be strings; invalid keys: " + ", ".join(sorted(str(key) for key in invalid_values)) + "metadata values must be strings; invalid keys: " + ", ".join(sorted(invalid_values)) ) - return {str(key): value for key, value in metadata.items()} + return dict(metadata) def _stored_metadata(metadata: Any) -> dict[str, str]: diff --git a/python/packages/devui/tests/devui/test_conversation_metadata.py b/python/packages/devui/tests/devui/test_conversation_metadata.py index 3ad74699881..6462d8d007b 100644 --- a/python/packages/devui/tests/devui/test_conversation_metadata.py +++ b/python/packages/devui/tests/devui/test_conversation_metadata.py @@ -28,6 +28,14 @@ def test_create_conversation_rejects_non_string_metadata_values(): store.create_conversation(metadata={"agent_id": 7}) +def test_create_conversation_rejects_non_string_metadata_keys(): + """A metadata key that is not a string is rejected instead of coerced.""" + store = InMemoryConversationStore() + + with pytest.raises(ConversationMetadataValidationError): + store.create_conversation(metadata={1: "first", "1": "second"}) # type: ignore[dict-item] + + def test_create_conversation_accepts_none_metadata(): """An explicit ``None`` is normalized to an empty map.""" store = InMemoryConversationStore()