DevUI: Use metadata.entity_id for agent/workflow name instead of model field

Author: ReubenBond

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/AgentRunResponseExtensions.cs

@@ -56,7 +56,7 @@ public static Response ToResponse(
             MaxOutputTokens = request.MaxOutputTokens,
             MaxToolCalls = request.MaxToolCalls,
             Metadata = request.Metadata is IReadOnlyDictionary<string, string> metadata ? new Dictionary<string, string>(metadata) : [],
-            Model = request.Agent?.Name ?? request.Model,
+            Model = request.Model,
             Output = output,
             ParallelToolCalls = request.ParallelToolCalls ?? true,
             PreviousResponseId = request.PreviousResponseId,

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/AgentRunResponseUpdateExtensions.cs

@@ -165,7 +165,7 @@ Response CreateResponse(ResponseStatus status = ResponseStatus.Completed, IEnume
                 MaxOutputTokens = request.MaxOutputTokens,
                 MaxToolCalls = request.MaxToolCalls,
                 Metadata = request.Metadata != null ? new Dictionary<string, string>(request.Metadata) : [],
-                Model = request.Agent?.Name ?? request.Model,
+                Model = request.Model,
                 Output = outputs?.ToList() ?? [],
                 ParallelToolCalls = request.ParallelToolCalls ?? true,
                 PreviousResponseId = request.PreviousResponseId,

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/HostedAgentResponseExecutor.cs

@@ -13,8 +13,9 @@
 namespace Microsoft.Agents.AI.Hosting.OpenAI.Responses;
 
 /// <summary>
-/// Response executor that routes requests to hosted AIAgent services based on the model or agent.name parameter.
+/// Response executor that routes requests to hosted AIAgent services based on agent.name or metadata["entity_id"].
 /// This executor resolves agents from keyed services registered via AddAIAgent().
+/// The model field is reserved for actual model names and is never used for entity/agent identification.
 /// </summary>
 internal sealed class HostedAgentResponseExecutor : IResponseExecutor
 {
@@ -76,17 +77,26 @@ public async IAsyncEnumerable<StreamingResponseEvent> ExecuteAsync(
 
     /// <summary>
     /// Resolves an agent from the service provider based on the request.
+    /// Checks agent.name first, then metadata["entity_id"].
     /// </summary>
     /// <param name="request">The create response request.</param>
     /// <returns>The resolved AIAgent instance.</returns>
     /// <exception cref="InvalidOperationException">Thrown when the agent cannot be resolved.</exception>
     private AIAgent ResolveAgent(CreateResponse request)
     {
-        // Extract agent name from agent.name or model parameter
-        var agentName = request.Agent?.Name ?? request.Model;
+        // Extract agent name from agent.name first (highest priority)
+        string? agentName = request.Agent?.Name;
+
+        // Fall back to metadata["entity_id"] if agent.name is not present
+        if (string.IsNullOrEmpty(agentName) && request.Metadata?.TryGetValue("entity_id", out string? entityId) == true)
+        {
+            agentName = entityId;
+        }
+
+        // Never use model field for entity ID - it's for the actual model name
         if (string.IsNullOrEmpty(agentName))
         {
-            throw new InvalidOperationException("No 'agent.name' or 'model' specified in the request.");
+            throw new InvalidOperationException("No 'agent.name' or 'metadata.entity_id' specified in the request.");
         }
 
         // Resolve the keyed agent service

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/InMemoryResponsesService.cs

@@ -371,7 +371,7 @@ private ResponseState InitializeResponse(string responseId, CreateResponse reque
             MaxOutputTokens = request.MaxOutputTokens,
             MaxToolCalls = request.MaxToolCalls,
             Metadata = metadata,
-            Model = request.Model ?? "default",
+            Model = request.Model,
             Output = [],
             ParallelToolCalls = request.ParallelToolCalls ?? true,
             PreviousResponseId = request.PreviousResponseId,

dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/ResponsesHttpHandler.cs

@@ -82,7 +82,7 @@ public async Task<IResult> CreateResponseAsync(
                 }
             });
         }
-        catch (InvalidOperationException ex) when (ex.Message.Contains("No 'agent.name' or 'model' specified"))
+        catch (InvalidOperationException ex) when (ex.Message.Contains("No 'agent.name'"))
         {
             // Return OpenAI-style error for missing required parameters
             return Results.BadRequest(new ErrorResponse

dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIHttpApiIntegrationTests.cs

@@ -45,7 +45,7 @@ public async Task CreateConversationAndResponse_NonStreaming_NonBackground_Updat
         // Act - Create response (non-streaming, non-background)
         var createResponseRequest = new
         {
-            model = AgentName,
+            metadata = new { entity_id = AgentName },
             conversation = conversationId,
             input = UserMessage,
             stream = false
@@ -122,7 +122,7 @@ public async Task CreateConversationAndResponse_Streaming_NonBackground_UpdatesC
         // Act - Create response (streaming, non-background)
         var createResponseRequest = new
         {
-            model = AgentName,
+            metadata = new { entity_id = AgentName },
             conversation = conversationId,
             input = UserMessage,
             stream = true
@@ -196,7 +196,7 @@ public async Task CreateConversationAndResponse_NonStreaming_Background_UpdatesC
         // Act - Create response (non-streaming, background)
         var createResponseRequest = new
         {
-            model = AgentName,
+            metadata = new { entity_id = AgentName },
             conversation = conversationId,
             input = UserMessage,
             stream = false,

dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIResponsesAgentResolutionIntegrationTests.cs

@@ -168,23 +168,23 @@ public async Task CreateResponse_WithMultipleAgents_ResolvesCorrectAgentAsync()
     }
 
     /// <summary>
-    /// Verifies that agent resolution using the model property works correctly.
+    /// Verifies that agent resolution using the metadata.entity_id property works correctly.
     /// </summary>
     [Fact]
-    public async Task CreateResponse_WithModelProperty_ResolvesCorrectAgentAsync()
+    public async Task CreateResponse_WithMetadataEntityId_ResolvesCorrectAgentAsync()
     {
         // Arrange
-        const string AgentName = "model-agent";
+        const string AgentName = "metadata-agent";
         const string Instructions = "You are a helpful assistant.";
-        const string ExpectedResponse = "Response via model property";
+        const string ExpectedResponse = "Response via metadata.entity_id";
 
         this._httpClient = await this.CreateTestServerWithAgentResolutionAsync(
             (AgentName, Instructions, ExpectedResponse));
 
-        // Act - Use raw HTTP request to control the model property
+        // Act - Use raw HTTP request with metadata.entity_id
         using StringContent requestContent = new(JsonSerializer.Serialize(new
         {
-            model = AgentName,
+            metadata = new { entity_id = AgentName },
             input = new[]
             {
                 new { type = "message", role = "user", content = "Test message" }
@@ -268,7 +268,6 @@ public async Task CreateResponse_WithoutAgentOrModel_ReturnsBadRequestAsync()
 
         string responseJson = await httpResponse.Content.ReadAsStringAsync();
         Assert.Contains("agent.name", responseJson, StringComparison.OrdinalIgnoreCase);
-        Assert.Contains("model", responseJson, StringComparison.OrdinalIgnoreCase);
     }
 
     /// <summary>

python/packages/devui/README.md

@@ -91,15 +91,15 @@ devui ./agents --tracing framework
 
 ## OpenAI-Compatible API
 
-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.
+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 entity_id in metadata**, and set streaming to `True` as needed.
 
 ```bash
-# Simple - use your entity name as the model
+# Simple - use your entity name as the entity_id in metadata
 curl -X POST http://localhost:8080/v1/responses \
   -H "Content-Type: application/json" \
   -d @- << 'EOF'
 {
-  "model": "weather_agent",
+  "metadata": {"entity_id": "weather_agent"},
   "input": "Hello world"
 }
 ```
@@ -115,7 +115,7 @@ client = OpenAI(
 )
 
 response = client.responses.create(
-    model="weather_agent",  # Your agent/workflow name
+    metadata={"entity_id": "weather_agent"},  # Your agent/workflow name
     input="What's the weather in Seattle?"
 )
 
@@ -136,13 +136,13 @@ conversation = client.conversations.create(
 
 # Use it across multiple turns
 response1 = client.responses.create(
-    model="weather_agent",
+    metadata={"entity_id": "weather_agent"},
     input="What's the weather in Seattle?",
     conversation=conversation.id
 )
 
 response2 = client.responses.create(
-    model="weather_agent",
+    metadata={"entity_id": "weather_agent"},
     input="How about tomorrow?",
     conversation=conversation.id  # Continues the conversation!
 )

python/packages/devui/agent_framework_devui/_mapper.py

@@ -273,7 +273,7 @@ async def aggregate_to_response(self, events: Sequence[Any], request: AgentFrame
                 id=f"resp_{uuid.uuid4().hex[:12]}",
                 object="response",
                 created_at=datetime.now().timestamp(),
-                model=request.model,
+                model=request.model or "devui",
                 output=[response_output_message],
                 usage=usage,
                 parallel_tool_calls=False,
@@ -495,8 +495,9 @@ async def _convert_agent_lifecycle_event(self, event: Any, context: dict[str, An
         from .models._openai_custom import AgentCompletedEvent, AgentFailedEvent, AgentStartedEvent
 
         try:
-            # Get model name from context (the agent name)
-            model_name = context.get("request", {}).model if context.get("request") else "agent"
+            # Get model name from request or use 'devui' as default
+            request_obj = context.get("request")
+            model_name = request_obj.model if request_obj and request_obj.model else "devui"
 
             if isinstance(event, AgentStartedEvent):
                 execution_id = f"agent_{uuid4().hex[:12]}"
@@ -603,16 +604,16 @@ async def _convert_workflow_event(self, event: Any, context: dict[str, Any]) ->
                 # Return proper OpenAI event objects
                 events: list[Any] = []
 
-                # Determine the model name - use request model or default to "workflow"
-                # The request model will be the agent name for agents, workflow name for workflows
-                model_name = context.get("request", {}).model if context.get("request") else "workflow"
+                # Get model name from request or use 'devui' as default
+                request_obj = context.get("request")
+                model_name = request_obj.model if request_obj and request_obj.model else "devui"
 
                 # Create a full Response object with all required fields
                 response_obj = Response(
                     id=f"resp_{workflow_id}",
                     object="response",
                     created_at=float(time.time()),
-                    model=model_name,  # Use the actual model/agent name
+                    model=model_name,
                     output=[],  # Empty output list initially
                     status="in_progress",
                     # Required fields with safe defaults
@@ -643,8 +644,9 @@ async def _convert_workflow_event(self, event: Any, context: dict[str, Any]) ->
                 # Import Response type for proper construction
                 from openai.types.responses import Response
 
-                # Get model name from context
-                model_name = context.get("request", {}).model if context.get("request") else "workflow"
+                # Get model name from request or use 'devui' as default
+                request_obj = context.get("request")
+                model_name = request_obj.model if request_obj and request_obj.model else "devui"
 
                 # Create a full Response object for completed state
                 response_obj = Response(
@@ -672,8 +674,9 @@ async def _convert_workflow_event(self, event: Any, context: dict[str, Any]) ->
                 # Import Response and ResponseError types
                 from openai.types.responses import Response, ResponseError
 
-                # Get model name from context
-                model_name = context.get("request", {}).model if context.get("request") else "workflow"
+                # Get model name from request or use 'devui' as default
+                request_obj = context.get("request")
+                model_name = request_obj.model if request_obj and request_obj.model else "devui"
 
                 # Create error object
                 error_message = str(error_info) if error_info else "Unknown error"
@@ -1208,7 +1211,7 @@ async def _create_error_response(self, error_message: str, request: AgentFramewo
             id=f"resp_{uuid.uuid4().hex[:12]}",
             object="response",
             created_at=datetime.now().timestamp(),
-            model=request.model,
+            model=request.model or "devui",
             output=[response_output_message],
             usage=usage,
             parallel_tool_calls=False,

python/packages/devui/agent_framework_devui/_server.py

@@ -359,14 +359,14 @@ async def create_response(request: AgentFrameworkRequest, raw_request: Request)
             try:
                 raw_body = await raw_request.body()
                 logger.info(f"Raw request body: {raw_body.decode()}")
-                logger.info(f"Parsed request: model={request.model}, extra_body={request.extra_body}")
+                logger.info(f"Parsed request: metadata={request.metadata}")
 
-                # Get entity_id using the new method
+                # Get entity_id from metadata
                 entity_id = request.get_entity_id()
                 logger.info(f"Extracted entity_id: {entity_id}")
 
                 if not entity_id:
-                    error = OpenAIError.create(f"Missing entity_id. Request extra_body: {request.extra_body}")
+                    error = OpenAIError.create("Missing entity_id in metadata. Provide metadata.entity_id in request.")
                     return JSONResponse(status_code=400, content=error.to_dict())
 
                 # Get executor and validate entity exists