Python: DevUI - Internal Refactor, Conversations API support, and per…

python/packages/devui/README.md

@@ -78,21 +78,65 @@ devui ./agents --tracing framework
 
 ## OpenAI-Compatible API
 
-For convenience, you can interact with the agents/workflows using the standard OpenAI API format. Just specify the `entity_id` in the `extra_body` field. This can be an `agent_id` or `workflow_id`.
+For convenience, DevUI provides an OpenAI Responses backend API. This means you can run the backend and also use the OpenAI client sdk to connect to it. Use **agent/workflow name as the model**, and set streaming to `True` as needed.
 
 ```bash
-# Standard OpenAI format
+# Simple - use your entity name as the model
 curl -X POST http://localhost:8080/v1/responses \
   -H "Content-Type: application/json" \
   -d @- << 'EOF'
 {
-  "model": "agent-framework",
-  "input": "Hello world",
-  "extra_body": {"entity_id": "weather_agent"}
+  "model": "weather_agent",
+  "input": "Hello world"
 }
+```
+
+Or use the OpenAI Python SDK:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:8080/v1",
+    api_key="not-needed"  # API key not required for local DevUI
+)
+
+response = client.responses.create(
+    model="weather_agent",  # Your agent/workflow name
+    input="What's the weather in Seattle?"
+)
+
+# Extract text from response
+print(response.output[0].content[0].text)
+# Supports streaming with stream=True
+```
+
+### Multi-turn Conversations
+
+Use the standard OpenAI `conversation` parameter for multi-turn conversations:
 
+```python
+# Create a conversation
+conversation = client.conversations.create(
+    metadata={"agent_id": "weather_agent"}
+)
+
+# Use it across multiple turns
+response1 = client.responses.create(
+    model="weather_agent",
+    input="What's the weather in Seattle?",
+    conversation=conversation.id
+)
+
+response2 = client.responses.create(
+    model="weather_agent",
+    input="How about tomorrow?",
+    conversation=conversation.id  # Continues the conversation!
+)
 ```
 
+**How it works:** DevUI automatically retrieves the conversation's message history from the stored thread and passes it to the agent. You don't need to manually manage message history - just provide the same `conversation` ID for follow-up requests.
+
 ## CLI Options
 
 ```bash
@@ -109,30 +153,79 @@ Options:
 
 ## Key Endpoints
 
+## API Mapping
+
+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:
+
+| Agent Framework Content         | OpenAI Event/Type                        | Status   |
+| ------------------------------- | ---------------------------------------- | -------- |
+| `TextContent`                   | `response.output_text.delta`             | Standard |
+| `TextReasoningContent`          | `response.reasoning.delta`               | Standard |
+| `FunctionCallContent` (initial) | `response.output_item.added`             | Standard |
+| `FunctionCallContent` (args)    | `response.function_call_arguments.delta` | Standard |
+| `FunctionResultContent`         | `response.function_result.complete`      | DevUI    |
+| `ErrorContent`                  | `response.error`                         | Standard |
+| `UsageContent`                  | Final `Response.usage` field (not streamed) | Standard |
+| `WorkflowEvent`                 | `response.workflow_event.complete`       | DevUI    |
+| `DataContent`, `UriContent`     | `response.trace.complete`                | DevUI    |
+
+- **Standard** = OpenAI Responses API spec
+- **DevUI** = Custom extensions for Agent Framework features (workflows, traces, function results)
+
+### OpenAI Responses API Compliance
+
+DevUI follows the OpenAI Responses API specification for maximum compatibility:
+
+**Standard OpenAI Types Used:**
+- `ResponseOutputItemAddedEvent` - Output item notifications (function calls)
+- `Response.usage` - Token usage (in final response, not streamed)
+- All standard text, reasoning, and function call events
+
+**Custom DevUI Extensions:**
+- `response.function_result.complete` - Function execution results (DevUI executes functions, OpenAI doesn't)
+- `response.workflow_event.complete` - Agent Framework workflow events
+- `response.trace.complete` - Execution traces for debugging
+
+These custom extensions are clearly namespaced and can be safely ignored by standard OpenAI clients.
+
+### Entity Management
+
 - `GET /v1/entities` - List discovered agents/workflows
 - `GET /v1/entities/{entity_id}/info` - Get detailed entity information
 - `POST /v1/entities/add` - Add entity from URL (for gallery samples)
 - `DELETE /v1/entities/{entity_id}` - Remove remote entity
+
+### Execution (OpenAI Responses API)
+
 - `POST /v1/responses` - Execute agent/workflow (streaming or sync)
+
+### Conversations (OpenAI Standard)
+
+- `POST /v1/conversations` - Create conversation
+- `GET /v1/conversations/{id}` - Get conversation
+- `POST /v1/conversations/{id}` - Update conversation metadata
+- `DELETE /v1/conversations/{id}` - Delete conversation
+- `GET /v1/conversations?agent_id={id}` - List conversations _(DevUI extension)_
+- `POST /v1/conversations/{id}/items` - Add items to conversation
+- `GET /v1/conversations/{id}/items` - List conversation items
+- `GET /v1/conversations/{id}/items/{item_id}` - Get conversation item
+
+### Health
+
 - `GET /health` - Health check
-- `POST /v1/threads` - Create thread for agent (optional)
-- `GET /v1/threads?agent_id={id}` - List threads for agent
-- `GET /v1/threads/{thread_id}` - Get thread info
-- `DELETE /v1/threads/{thread_id}` - Delete thread
-- `GET /v1/threads/{thread_id}/messages` - Get thread messages
 
 ## Implementation
 
 - **Discovery**: `agent_framework_devui/_discovery.py`
 - **Execution**: `agent_framework_devui/_executor.py`
 - **Message Mapping**: `agent_framework_devui/_mapper.py`
-- **Session Management**: `agent_framework_devui/_session.py`
+- **Conversations**: `agent_framework_devui/_conversations.py`
 - **API Server**: `agent_framework_devui/_server.py`
 - **CLI**: `agent_framework_devui/_cli.py`
 
 ## Examples
 
-See `samples/` for working agent and workflow implementations.
+See working implementations in `python/samples/getting_started/devui/`
 
 ## License