From e4605c4fb80023d84406e802e27b7b892abda46e Mon Sep 17 00:00:00 2001
From: John CSA <103165870+jluocsa@users.noreply.github.com>
Date: Sun, 17 May 2026 10:11:50 -0700
Subject: [PATCH] .NET: docs(aspire-devui): align README usage example with
 WithAgentService semantics

The Usage example in dotnet/src/Aspire.Hosting.AgentFramework.DevUI/README.md
contained an AppHost.cs snippet that registered Aspire project resources as
"writer-agent" / "editor-agent" and called WithAgentService(writerAgent) with
no explicit agents argument. WithAgentService defaults to a single agent named
after the Aspire resource, so the aggregator advertised entities
"writer-agent/writer-agent" and "editor-agent/editor-agent". The companion
Program.cs snippet registered the agent inside the service as just "writer"
via AddAIAgent, so DevUI requests against the advertised entity failed with
`CLIENT_ERROR: Agent 'writer-agent' not found.`.

This change updates the Usage example to pass the explicit `agents:` argument
that the reporter (#5781) confirmed works, matching the example already shown
in the XmlDoc for WithAgentService. It also adds a short sentence explaining
the relationship between Aspire resource names and AgentEntityInfo Ids, and
links readers to the Agent discovery section for the default case.

The Agent discovery section's example is updated so it no longer duplicates
the Usage example: it now shows (a) the convenient default when resource name
matches agent name, and (b) the multi-agent-per-service shape that benefits
from explicit metadata.

No source code changes; documentation only.

Fixes #5781
---
 .../README.md                                 | 25 +++++++++++++++----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/dotnet/src/Aspire.Hosting.AgentFramework.DevUI/README.md b/dotnet/src/Aspire.Hosting.AgentFramework.DevUI/README.md
index 8dbace2514..b66350fd0b 100644
--- a/dotnet/src/Aspire.Hosting.AgentFramework.DevUI/README.md
+++ b/dotnet/src/Aspire.Hosting.AgentFramework.DevUI/README.md
@@ -28,12 +28,14 @@ var editorAgent = builder.AddProject<Projects.EditorAgent>("editor-agent")
     .WithHttpHealthCheck("/health");
 
 var devui = builder.AddDevUI("devui")
-    .WithAgentService(writerAgent)
-    .WithAgentService(editorAgent)
+    .WithAgentService(writerAgent, agents: [new("writer", "Writes short stories")])
+    .WithAgentService(editorAgent, agents: [new("editor", "Edits and formats stories")])
     .WaitFor(writerAgent)
     .WaitFor(editorAgent);
 ```
 
+Each `AgentEntityInfo` `Id` (e.g. `"writer"`, `"editor"`) must match the name passed to `AddAIAgent` in the corresponding agent service. The Aspire resource name (e.g. `"writer-agent"`) is independent and is used as the entity ID prefix the aggregator routes by. If you omit the `agents:` argument, `WithAgentService` will assume a single agent named after the Aspire resource — see the [Agent discovery](#agent-discovery) section below.
+
 Each agent service only needs to map the standard OpenAI API endpoints — no custom discovery endpoints are required:
 
 ```csharp
@@ -61,12 +63,25 @@ The aggregator publishes its URL to the Aspire dashboard, where it appears as a
 
 ## Agent discovery
 
-By default, `WithAgentService` declares a single agent named after the Aspire resource. You can provide explicit agent metadata when the agent name differs from the resource name, or when a service hosts multiple agents:
+By default, `WithAgentService` declares a single agent named after the Aspire resource. This is convenient when the resource name and the agent name are the same:
 
 ```csharp
+var writerAgent = builder.AddProject<Projects.WriterAgent>("writer")
+    .WithHttpHealthCheck("/health");
+
 builder.AddDevUI("devui")
-    .WithAgentService(writerAgent, agents: [new("writer", "Writes short stories")])
-    .WithAgentService(editorAgent, agents: [new("editor", "Edits and formats stories")]);
+    .WithAgentService(writerAgent); // matches builder.AddAIAgent("writer", ...) in WriterAgent
+```
+
+Provide explicit `agents` metadata when the agent name differs from the resource name (as in the [Usage example](#usage-example) above) or when a single service hosts multiple agents:
+
+```csharp
+builder.AddDevUI("devui")
+    .WithAgentService(multiAgentService, agents:
+    [
+        new("writer", "Writes short stories"),
+        new("editor", "Edits and formats stories"),
+    ]);
 ```
 
 Agent metadata is declared at the AppHost level so the aggregator builds the entity listing directly — agent services don't need a `/v1/entities` endpoint.