Skip to content

Commit fef846c

Browse files
committed
fix(devui): resolve timestamp overwriting and Content serialization errors
- Fix tool call timestamps being overwritten on each render (microsoft#1483) - Add recursive Content serialization to handle ChatMessage and nested objects (microsoft#1548) - Implement proper MCP tool cleanup on server shutdown - Add timestamp field to function_result.complete events - Enhance credential and client resource cleanup Fixes microsoft#1483, microsoft#1548 Partial improvements for microsoft#1476
1 parent 0de0e29 commit fef846c

11 files changed

Lines changed: 483 additions & 143 deletions

File tree

‎python/packages/devui/README.md‎

Lines changed: 56 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,19 @@ devui ./agents --port 8080
4949

5050
When DevUI starts with no discovered entities, it displays a **sample entity gallery** with curated examples from the Agent Framework repository. You can download these samples, review them, and run them locally to get started quickly.
5151

52+
## Using MCP Tools
53+
54+
**Important:** Don't use `async with` context managers when creating agents with MCP tools for DevUI - connections will close before execution.
55+
56+
```python
57+
# ✅ Correct - DevUI handles cleanup automatically
58+
mcp_tool = MCPStreamableHTTPTool(url="http://localhost:8011/mcp", chat_client=chat_client)
59+
agent = ChatAgent(tools=mcp_tool)
60+
serve(entities=[agent])
61+
```
62+
63+
MCP tools use lazy initialization and connect automatically on first use. DevUI attempts to clean up connections on shutdown
64+
5265
## Directory Structure
5366

5467
For your agents to be discovered by the DevUI, they must be organized in a directory structure like below. Each agent/workflow must have an `__init__.py` that exports the required variable (`agent` or `workflow`).
@@ -157,57 +170,62 @@ Options:
157170
158171
Given that DevUI offers an OpenAI Responses API, it internally maps messages and events from Agent Framework to OpenAI Responses API events (in `_mapper.py`). For transparency, this mapping is shown below:
159172
160-
| Agent Framework Content | OpenAI Event/Type | Status |
161-
| ------------------------------- | ---------------------------------------- | -------- |
162-
| **Lifecycle Events** | | |
163-
| `AgentStartedEvent` | `response.created` + `response.in_progress` | Standard |
164-
| `AgentCompletedEvent` | `response.completed` | Standard |
165-
| `AgentFailedEvent` | `response.failed` | Standard |
166-
| `WorkflowStartedEvent` | `response.created` + `response.in_progress` | Standard |
167-
| `WorkflowCompletedEvent` | `response.completed` | Standard |
168-
| `WorkflowFailedEvent` | `response.failed` | Standard |
169-
| **Content Types** | | |
170-
| `TextContent` | `response.content_part.added` + `response.output_text.delta` | Standard |
171-
| `TextReasoningContent` | `response.reasoning_text.delta` | Standard |
172-
| `FunctionCallContent` (initial) | `response.output_item.added` | Standard |
173-
| `FunctionCallContent` (args) | `response.function_call_arguments.delta` | Standard |
174-
| `FunctionResultContent` | `response.function_result.complete` | DevUI |
175-
| `FunctionApprovalRequestContent`| `response.function_approval.requested` | DevUI |
176-
| `FunctionApprovalResponseContent`| `response.function_approval.responded` | DevUI |
177-
| `ErrorContent` | `error` | Standard |
178-
| `UsageContent` | Final `Response.usage` field (not streamed) | Standard |
179-
| **Workflow Events** | | |
180-
| `ExecutorInvokedEvent` | `response.output_item.added` (ExecutorActionItem) | DevUI |
181-
| `ExecutorCompletedEvent` | `response.output_item.done` (ExecutorActionItem) | DevUI |
182-
| `ExecutorFailedEvent` | `response.output_item.done` (ExecutorActionItem with error) | DevUI |
183-
| `WorkflowEvent` (other) | `response.workflow_event.complete` | DevUI |
184-
| `WorkflowStatusEvent` | `response.trace.complete` | DevUI |
185-
| `WorkflowWarningEvent` | `response.trace.complete` | DevUI |
186-
| **Trace Content** | | |
187-
| `DataContent` | `response.trace.complete` | DevUI |
188-
| `UriContent` | `response.trace.complete` | DevUI |
189-
| `HostedFileContent` | `response.trace.complete` | DevUI |
190-
| `HostedVectorStoreContent` | `response.trace.complete` | DevUI |
191-
192-
- **Standard** = OpenAI Responses API spec
193-
- **DevUI** = Custom extensions for Agent Framework features (workflows, traces, function approvals)
173+
| OpenAI Event/Type | Agent Framework Content | Status |
174+
| ------------------------------------------------------------ | --------------------------------- | -------- |
175+
| | **Lifecycle Events** | |
176+
| `response.created` + `response.in_progress` | `AgentStartedEvent` | OpenAI |
177+
| `response.completed` | `AgentCompletedEvent` | OpenAI |
178+
| `response.failed` | `AgentFailedEvent` | OpenAI |
179+
| `response.created` + `response.in_progress` | `WorkflowStartedEvent` | OpenAI |
180+
| `response.completed` | `WorkflowCompletedEvent` | OpenAI |
181+
| `response.failed` | `WorkflowFailedEvent` | OpenAI |
182+
| | **Content Types** | |
183+
| `response.content_part.added` + `response.output_text.delta` | `TextContent` | OpenAI |
184+
| `response.reasoning_text.delta` | `TextReasoningContent` | OpenAI |
185+
| `response.output_item.added` | `FunctionCallContent` (initial) | OpenAI |
186+
| `response.function_call_arguments.delta` | `FunctionCallContent` (args) | OpenAI |
187+
| `response.function_result.complete` | `FunctionResultContent` | DevUI |
188+
| `response.function_approval.requested` | `FunctionApprovalRequestContent` | DevUI |
189+
| `response.function_approval.responded` | `FunctionApprovalResponseContent` | DevUI |
190+
| `error` | `ErrorContent` | OpenAI |
191+
| Final `Response.usage` field (not streamed) | `UsageContent` | OpenAI |
192+
| | **Workflow Events** | |
193+
| `response.output_item.added` (ExecutorActionItem)* | `ExecutorInvokedEvent` | OpenAI |
194+
| `response.output_item.done` (ExecutorActionItem)* | `ExecutorCompletedEvent` | OpenAI |
195+
| `response.output_item.done` (ExecutorActionItem with error)* | `ExecutorFailedEvent` | OpenAI |
196+
| `response.workflow_event.complete` | `WorkflowEvent` (other) | DevUI |
197+
| `response.trace.complete` | `WorkflowStatusEvent` | DevUI |
198+
| `response.trace.complete` | `WorkflowWarningEvent` | DevUI |
199+
| | **Trace Content** | |
200+
| `response.trace.complete` | `DataContent` | DevUI |
201+
| `response.trace.complete` | `UriContent` | DevUI |
202+
| `response.trace.complete` | `HostedFileContent` | DevUI |
203+
| `response.trace.complete` | `HostedVectorStoreContent` | DevUI |
204+
205+
\*Uses standard OpenAI event structure but carries DevUI-specific `ExecutorActionItem` payload
206+
207+
- **OpenAI** = Standard OpenAI Responses API event types
208+
- **DevUI** = Custom event types specific to Agent Framework (e.g., workflows, traces, function approvals)
194209
195210
### OpenAI Responses API Compliance
196211
197212
DevUI follows the OpenAI Responses API specification for maximum compatibility:
198213
199-
**Standard OpenAI Types Used:**
214+
**OpenAI Standard Event Types Used:**
215+
200216
- `ResponseOutputItemAddedEvent` - Output item notifications (function calls and results)
217+
- `ResponseOutputItemDoneEvent` - Output item completion notifications
201218
- `Response.usage` - Token usage (in final response, not streamed)
202219
- All standard text, reasoning, and function call events
203220
204221
**Custom DevUI Extensions:**
222+
205223
- `response.function_approval.requested` - Function approval requests (for interactive approval workflows)
206224
- `response.function_approval.responded` - Function approval responses (user approval/rejection)
207225
- `response.workflow_event.complete` - Agent Framework workflow events
208226
- `response.trace.complete` - Execution traces and internal content (DataContent, UriContent, hosted files/stores)
209227
210-
These custom extensions are clearly namespaced and can be safely ignored by standard OpenAI clients.
228+
These custom extensions are clearly namespaced and can be safely ignored by standard OpenAI clients. Note that DevUI also uses standard OpenAI events with custom payloads (e.g., `ExecutorActionItem` within `response.output_item.added`).
211229
212230
### Entity Management
213231
@@ -239,12 +257,14 @@ These custom extensions are clearly namespaced and can be safely ignored by stan
239257
DevUI is designed as a **sample application for local development** and should not be exposed to untrusted networks or used in production environments.
240258
241259
**Security features:**
260+
242261
- Only loads entities from local directories or in-memory registration
243262
- No remote code execution capabilities
244263
- Binds to localhost (127.0.0.1) by default
245264
- All samples must be manually downloaded and reviewed before running
246265
247266
**Best practices:**
267+
248268
- Never expose DevUI to the internet
249269
- Review all agent/workflow code before running
250270
- Only load entities from trusted sources

‎python/packages/devui/agent_framework_devui/_mapper.py‎

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,56 @@
5656
]
5757

5858

59+
def _serialize_content_recursive(value: Any) -> Any:
60+
"""Recursively serialize Agent Framework Content objects to JSON-compatible values.
61+
62+
This handles nested Content objects (like TextContent inside FunctionResultContent.result)
63+
that can't be directly serialized by json.dumps().
64+
65+
Args:
66+
value: Value to serialize (can be Content object, dict, list, primitive, etc.)
67+
68+
Returns:
69+
JSON-serializable version with all Content objects converted to dicts/primitives
70+
"""
71+
# Handle None and basic JSON-serializable types
72+
if value is None or isinstance(value, (str, int, float, bool)):
73+
return value
74+
75+
# Check if it's a SerializationMixin (includes all Content types)
76+
# Content objects have to_dict() method
77+
if hasattr(value, "to_dict") and callable(getattr(value, "to_dict", None)):
78+
try:
79+
return value.to_dict()
80+
except Exception as e:
81+
# If to_dict() fails, fall through to other methods
82+
logger.debug(f"Failed to serialize with to_dict(): {e}")
83+
84+
# Handle dictionaries - recursively process values
85+
if isinstance(value, dict):
86+
return {key: _serialize_content_recursive(val) for key, val in value.items()}
87+
88+
# Handle lists and tuples - recursively process elements
89+
if isinstance(value, (list, tuple)):
90+
serialized = [_serialize_content_recursive(item) for item in value]
91+
# For single-item lists containing text Content, extract just the text
92+
# This handles the MCP case where result = [TextContent(text="Hello")]
93+
# and we want output = "Hello" not output = '[{"type": "text", "text": "Hello"}]'
94+
if len(serialized) == 1 and isinstance(serialized[0], dict) and serialized[0].get("type") == "text":
95+
return serialized[0].get("text", "")
96+
return serialized
97+
98+
# For other objects with model_dump(), try that
99+
if hasattr(value, "model_dump") and callable(getattr(value, "model_dump", None)):
100+
try:
101+
return value.model_dump()
102+
except Exception as e:
103+
logger.debug(f"Failed to serialize with model_dump(): {e}")
104+
105+
# Return as-is and let json.dumps handle it (may raise TypeError for non-serializable types)
106+
return value
107+
108+
59109
class MessageMapper:
60110
"""Maps Agent Framework messages/responses to OpenAI format."""
61111

@@ -935,8 +985,16 @@ async def _map_function_result_content(
935985
result = getattr(content, "result", None)
936986
exception = getattr(content, "exception", None)
937987

938-
# Convert result to string
939-
output = result if isinstance(result, str) else json.dumps(result) if result is not None else ""
988+
# Convert result to string, handling nested Content objects from MCP tools
989+
if isinstance(result, str):
990+
output = result
991+
elif result is not None:
992+
# Recursively serialize any nested Content objects (e.g., from MCP tools)
993+
serialized = _serialize_content_recursive(result)
994+
# Convert to JSON string if still not a string
995+
output = serialized if isinstance(serialized, str) else json.dumps(serialized)
996+
else:
997+
output = ""
940998

941999
# Determine status based on exception
9421000
status = "incomplete" if exception else "completed"
@@ -953,6 +1011,7 @@ async def _map_function_result_content(
9531011
item_id=item_id,
9541012
output_index=context["output_index"],
9551013
sequence_number=self._next_sequence(context),
1014+
timestamp=datetime.now().isoformat(),
9561015
)
9571016

9581017
async def _map_error_content(self, content: Any, context: dict[str, Any]) -> ResponseErrorEvent:

‎python/packages/devui/agent_framework_devui/_server.py‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,31 +85,73 @@ async def _ensure_executor(self) -> AgentFrameworkExecutor:
8585
return self.executor
8686

8787
async def _cleanup_entities(self) -> None:
88-
"""Cleanup entity resources (close clients, credentials, etc.)."""
88+
"""Cleanup entity resources (close clients, MCP tools, credentials, etc.)."""
8989
if not self.executor:
9090
return
9191

9292
logger.info("Cleaning up entity resources...")
9393
entities = self.executor.entity_discovery.list_entities()
9494
closed_count = 0
95+
mcp_tools_closed = 0
96+
credentials_closed = 0
9597

9698
for entity_info in entities:
9799
try:
98100
entity_obj = self.executor.entity_discovery.get_entity_object(entity_info.id)
101+
102+
# Close chat clients and their credentials
99103
if entity_obj and hasattr(entity_obj, "chat_client"):
100104
client = entity_obj.chat_client
105+
106+
# Close the chat client itself
101107
if hasattr(client, "close") and callable(client.close):
102108
if inspect.iscoroutinefunction(client.close):
103109
await client.close()
104110
else:
105111
client.close()
106112
closed_count += 1
107113
logger.debug(f"Closed client for entity: {entity_info.id}")
114+
115+
# Close credentials attached to chat clients (e.g., AzureCliCredential)
116+
credential_attrs = ["credential", "async_credential", "_credential", "_async_credential"]
117+
for attr in credential_attrs:
118+
if hasattr(client, attr):
119+
cred = getattr(client, attr)
120+
if cred and hasattr(cred, "close") and callable(cred.close):
121+
try:
122+
if inspect.iscoroutinefunction(cred.close):
123+
await cred.close()
124+
else:
125+
cred.close()
126+
credentials_closed += 1
127+
logger.debug(f"Closed credential for entity: {entity_info.id}")
128+
except Exception as e:
129+
logger.warning(f"Error closing credential for {entity_info.id}: {e}")
130+
131+
# Close MCP tools (framework tracks them in _local_mcp_tools)
132+
if entity_obj and hasattr(entity_obj, "_local_mcp_tools"):
133+
for mcp_tool in entity_obj._local_mcp_tools:
134+
if hasattr(mcp_tool, "close") and callable(mcp_tool.close):
135+
try:
136+
if inspect.iscoroutinefunction(mcp_tool.close):
137+
await mcp_tool.close()
138+
else:
139+
mcp_tool.close()
140+
mcp_tools_closed += 1
141+
tool_name = getattr(mcp_tool, "name", "unknown")
142+
logger.debug(f"Closed MCP tool '{tool_name}' for entity: {entity_info.id}")
143+
except Exception as e:
144+
logger.warning(f"Error closing MCP tool for {entity_info.id}: {e}")
145+
108146
except Exception as e:
109147
logger.warning(f"Error closing entity {entity_info.id}: {e}")
110148

111149
if closed_count > 0:
112150
logger.info(f"Closed {closed_count} entity client(s)")
151+
if credentials_closed > 0:
152+
logger.info(f"Closed {credentials_closed} credential(s)")
153+
if mcp_tools_closed > 0:
154+
logger.info(f"Closed {mcp_tools_closed} MCP tool(s)")
113155

114156
def create_app(self) -> FastAPI:
115157
"""Create the FastAPI application."""

‎python/packages/devui/agent_framework_devui/models/_openai_custom.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,7 @@ class ResponseFunctionResultComplete(BaseModel):
121121
item_id: str
122122
output_index: int = 0
123123
sequence_number: int
124+
timestamp: str | None = None # Optional timestamp for UI display
124125

125126

126127
# Agent Framework extension fields

0 commit comments

Comments
 (0)