Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 60 additions & 5 deletions python/packages/devui/agent_framework_devui/_conversations.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,59 @@ 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_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(invalid_values))
)
return dict(metadata)


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},
Expand Down Expand Up @@ -255,6 +308,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] = []
Expand All @@ -268,7 +322,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.)
Expand All @@ -289,7 +343,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:
Expand All @@ -298,13 +352,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:
Expand Down Expand Up @@ -844,7 +899,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()):
Expand Down
7 changes: 6 additions & 1 deletion python/packages/devui/agent_framework_devui/_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
128 changes: 128 additions & 0 deletions python/packages/devui/tests/devui/test_conversation_metadata.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# 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_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()

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
Loading