.NET: Add feature-usage bitmask

.github/workflows/dotnet-build-and-test.yml

@@ -184,6 +184,7 @@ jobs:
               .
               .github
               dotnet
+              docs/specs
               python
               declarative-agents
 

dotnet/README.md

@@ -26,11 +26,40 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 - [Agent Provider Samples](./samples/02-agents/AgentProviders): samples showing different agent providers
 - [Workflow Samples](./samples/03-workflows): advanced multi-agent patterns and workflow orchestration
 
+## Feature-usage telemetry
+
+Agent Framework records coarse, process-lifetime feature usage in a transparent
+128-bit mask. On eligible Foundry and Azure OpenAI requests made through Agent
+Framework wrappers, the current mask is appended to the existing User-Agent as
+`(feat=v1.<hex>)`.
+
+- A bit means that a registered feature was observed at least once in the
+  process. Repeated requests are not additional feature uses and must not be
+  interpreted as request, agent, user, tenant, or invocation counts.
+- No prompts, payloads, model/deployment names, URLs, identifiers, arguments, or
+  customer-defined names are encoded.
+- Caller-owned Foundry `AIProjectClient` instances and custom transports are
+  stamped only when the request URI visible to the policy is an approved Foundry
+  HTTPS origin.
+- Azure OpenAI Chat and Responses clients adapted with `AsAIAgent` add the
+  `agent-framework-dotnet/<version>` User-Agent segment and stamp the feature
+  token for HTTPS endpoints under `cognitiveservices.azure.com`,
+  `openai.azure.com`, or `services.ai.azure.com`.
+- Direct OpenAI, custom OpenAI-compatible endpoints, and other third-party
+  clients remain unstamped.
+- Set `AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true` (or `1`) before process
+  startup to disable feature collection and the feature comment while retaining
+  the base `agent-framework-dotnet/{version}` User-Agent.
+
+See [ADR-0033](../docs/decisions/0033-feature-usage-bitmask-user-agent.md),
+[SPEC-004](../docs/specs/004-feature-usage-telemetry.md), and the
+[public bit registry](../docs/specs/feature-usage-bit-registry.md) for the
+interpretation and allocation contract.
+
 ## Agent Framework Documentation
 
 - [Documentation](https://learn.microsoft.com/agent-framework/)
 - [Agent Framework Repository](https://github.com/microsoft/agent-framework)
 - [Design Documents](../docs/design)
 - [Architectural Decision Records](../docs/decisions)
 - [MSFT Learn Docs](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)
-

dotnet/agent-framework-dotnet.slnx

@@ -648,6 +648,9 @@
     <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.FeatureRegistry.UnitTests/Microsoft.Agents.AI.FeatureRegistry.UnitTests.csproj">
+      <Build Solution="Debug|*" Project="false" />
+    </Project>
     <Project Path="tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
@@ -671,4 +674,3 @@
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
   </Folder>
 </Solution>
-

dotnet/eng/MSBuild/Shared.props

@@ -32,4 +32,7 @@
   <ItemGroup Condition="'$(InjectSharedRedaction)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Redaction\*.cs" LinkBase="Shared\Redaction" />
   </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedFeatureUsageUserAgent)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\FeatureUsage\*.cs" LinkBase="Shared\FeatureUsage" />
+  </ItemGroup>
 </Project>

dotnet/src/Microsoft.Agents.AI.A2A/A2AAgent.cs

@@ -114,6 +114,7 @@ protected override async Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessag
         var inputMessages = Throw.IfNull(messages) as IReadOnlyCollection<ChatMessage> ?? messages.ToList();
 
         A2AAgentSession typedSession = await this.GetA2ASessionAsync(session, options, cancellationToken).ConfigureAwait(false);
+        FeatureUsageMarker.MarkUsed();
 
         this._logger.LogA2AAgentInvokingAgent(nameof(RunAsync), this.Id, this.Name);
 
@@ -166,6 +167,7 @@ protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingA
         var inputMessages = Throw.IfNull(messages) as IReadOnlyCollection<ChatMessage> ?? messages.ToList();
 
         A2AAgentSession typedSession = await this.GetA2ASessionAsync(session, options, cancellationToken).ConfigureAwait(false);
+        FeatureUsageMarker.MarkUsed();
 
         this._logger.LogA2AAgentInvokingAgent(nameof(RunStreamingAsync), this.Id, this.Name);
 

dotnet/src/Microsoft.Agents.AI.A2A/FeatureIndex.cs

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.A2A;
+
+internal enum FeatureIndex
+{
+    A2A = 62,
+}
+
+internal static class FeatureUsageMarker
+{
+    public static void MarkUsed()
+    {
+#pragma warning disable MAAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+        FeatureUsage.MarkUsed((int)FeatureIndex.A2A);
+#pragma warning restore MAAI001
+    }
+}

dotnet/src/Microsoft.Agents.AI.Abstractions/FeatureIndex.cs

@@ -0,0 +1,8 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI;
+
+internal enum FeatureIndex
+{
+    CoreInMemoryHistoryProvider = 13,
+}