chore: import upstream snapshot with attribution

dotnet/src/Aspire.Hosting.AgentFramework.DevUI/AgentServiceAnnotation.cs

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using Aspire.Hosting.AgentFramework;
+
+namespace Aspire.Hosting.ApplicationModel;
+
+/// <summary>
+/// An annotation that tracks an agent service backend referenced by a DevUI resource.
+/// </summary>
+/// <remarks>
+/// This annotation is used to configure DevUI to aggregate entities from multiple
+/// agent service backends. Each annotation represents one backend that DevUI should
+/// connect to for entity discovery and request routing.
+/// </remarks>
+public class AgentServiceAnnotation : IResourceAnnotation
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentServiceAnnotation"/> class.
+    /// </summary>
+    /// <param name="agentService">The agent service resource.</param>
+    /// <param name="entityIdPrefix">
+    /// An optional prefix to add to entity IDs from this backend to avoid conflicts.
+    /// If not specified, the resource name will be used as the prefix.
+    /// </param>
+    /// <param name="agents">
+    /// Optional list of agents declared by this backend. When provided, the aggregator builds the entity
+    /// listing directly from these declarations instead of querying the backend's <c>/v1/entities</c> endpoint.
+    /// </param>
+    public AgentServiceAnnotation(IResource agentService, string? entityIdPrefix = null, IReadOnlyList<AgentEntityInfo>? agents = null)
+    {
+        ArgumentNullException.ThrowIfNull(agentService);
+
+        this.AgentService = agentService;
+        this.EntityIdPrefix = entityIdPrefix;
+        this.Agents = agents ?? [];
+    }
+
+    /// <summary>
+    /// Gets the agent service resource that exposes AI agents.
+    /// </summary>
+    public IResource AgentService { get; }
+
+    /// <summary>
+    /// Gets the prefix to use for entity IDs from this backend.
+    /// </summary>
+    /// <remarks>
+    /// When <c>null</c>, the resource name will be used as the prefix.
+    /// Entity IDs will be formatted as "{prefix}/{entityId}" to ensure uniqueness
+    /// across multiple agent backends.
+    /// </remarks>
+    public string? EntityIdPrefix { get; }
+
+    /// <summary>
+    /// Gets the list of agents declared by this backend.
+    /// </summary>
+    /// <remarks>
+    /// When non-empty, the DevUI aggregator uses these declarations to build the entity listing
+    /// without querying the backend. When empty, the aggregator falls back to calling
+    /// <c>GET /v1/entities</c> on the backend for discovery.
+    /// </remarks>
+    public IReadOnlyList<AgentEntityInfo> Agents { get; }
+}