microsoft--agent-framework/docs/specs/feature-usage-bit-registry.md

Feature-usage bit registry (per-language)

Status: draft, accompanies ADR-0033 and SPEC-004. Version: 1 per language · Width: 128-bit

This document is the proposed human-readable registry for the feature-usage mask. Until ADR-0033 is accepted and the index declarations ship, these tables are a candidate mapping, not a stable wire contract. The table is the allocation authority and published decoder contract; package-local private FeatureIndex declarations implement the rows they own. There is no generated artifact.

This telemetry is intentionally transparent: this registry is public, the emitted value is human-decodable, and a dedicated env var disables the mask without removing the base User-Agent. Python's existing whole-User-Agent opt-out also suppresses its mask; see Opt-out.

What is collected

A single 128-bit integer (the feature mask) describing which Agent Framework features were exercised in a process — not which packages are installed. The candidate below uses package-level bits plus selected major capabilities: core agent/workflow/MCP features, stable skill source types, each orchestration pattern, each individual built-in context/history provider, and distinct Foundry surfaces. ADR-0033 still leaves the final v1 granularity open. A feature sets its index at first meaningful activation; the SDK shifts that index, ORs the mask, and emits the value.

No identifiers, arguments, prompts, payloads, or user data are encoded — only the coarse Boolean "this feature was observed at least once in this process" per registered bit. A repeated bit on later requests is the same observation, not another use and not a count.

Allocation tenet

An index represents a stable, framework-owned capability whose adoption answers a concrete product or support question. It has a clear actual-use mark point in a public entry path, and the privacy review covers the resulting distinction.

Keep imports, installation state, aliases, wrappers, internal helpers, and implementation decorators such as caching/filtering/deduplication within their own capability bit. Customer/runtime values — names, prompts, arguments, URLs, identifiers, configuration choices — never become bits. A proposed distinction without a concrete query and named decision owner waits.

Operational clients, tools, providers, and hosts mark on their first real public operation/participation. Constructor marking is reserved for cases where construction itself activates or registers the capability; DI instantiation alone is not usage.

Ids use the package/integration name for a package-level signal and add a capability suffix only when the row tracks a narrower surface. They describe the registered feature, not an inheritance hierarchy: for example, Python hosting is the base agent-framework-hosting package, while hosting.a2a is the separate hosting-A2A integration.

Per-language, not shared

The two tables below are independent. Feature indexes are not shared across languages — Python bit 13 and .NET bit 13 do not mean the same thing. This is deliberate: the User-Agent product token already names the language (agent-framework-python vs agent-framework-dotnet), so a decoder selects the right table from the UA and decodes against it. Each SDK numbers and evolves its features independently — no cross-language synchronization, no null placeholders, no "same bit, same meaning" rule.

Encoding

• Width: 128-bit unsigned integer per language.

• Versioning: the emission carries the version so a decoder knows the bit mapping in effect (version is per language).

• User-Agent: the mask is an RFC 7231 comment (metadata, not a product token), placed after the agent-framework product token:

  agent-framework-python/1.2.3 (feat=v1.<hex_mask>)
  

  where <hex_mask> is lowercase hex, no leading zeros, no 0x prefix. Example for bits 0, 1, 5 set (0b100011 = 0x23):

  agent-framework-python/1.2.3 (feat=v1.23)
  

• Decoding: read the language from the product token, pick that table; read vN, pick that version; test mask & (1 << index) for each row. Unknown indexes (newer SDK than the decoder's copy) are ignored.

Emission scope (where the mask is sent)

• Marking is universal: every feature sets its index at first meaningful activation, regardless of provider.
• User-Agent (feat=...) comment — approved first-party clients only, stamped at request time. Added only when both the Azure / Foundry client/pipeline family and the actual HTTPS origin are approved, re-evaluated on every request and redirect hop. Custom origins are default-deny and an unapproved redirect removes the token. It is never sent to third-party providers — a feature fingerprint must not leak into logs we cannot read. See SPEC-004.
• OpenTelemetry: not in v1. Deferred primarily for privacy (a span attribute would broadcast the fingerprint into the user's general telemetry / third-party APM vendors). Left open behind the version prefix; see ADR-0033.

Index table — Python (agent-framework-python, version 1)

Layout: core features 0–31, orchestration patterns 32–47, and provider/integration packages from 48.

The provider/integration block is intentionally not partitioned by vendor ownership. Some packages span first- and third-party services, ownership can change, and protocols/storage integrations do not fit a stable first/third-party taxonomy. Index ranges are allocation space, not privacy or emission policy; the explicit destination allowlist independently ensures that the mask is sent only to approved first-party endpoints.

Index	Id	Feature	Activated at (representative)
0	core.agent	Agent	agent_framework.Agent
1	core.harness_agent	Harness agent	agent_framework.create_harness_agent
2	core.workflow	Workflow engine (custom graphs)	agent_framework.WorkflowBuilder
3	core.mcp	MCP tool (any transport)	agent_framework.MCPStdioTool
4	core.tool_approval	Tool-approval harness	agent_framework.ToolApprovalMiddleware
5	core.memory_provider	Memory context provider	agent_framework.MemoryContextProvider
6	core.skills_provider	Skills provider	agent_framework.SkillsProvider
7	core.file_access_provider	File-access provider	agent_framework.FileAccessProvider
8	core.compaction_provider	Context compaction provider	agent_framework.CompactionProvider
9	core.todo_provider	Todo provider	agent_framework.TodoProvider
10	core.agent_mode_provider	Agent-mode provider	agent_framework.AgentModeProvider
11	core.background_agents_provider	Background-agents provider	agent_framework.BackgroundAgentsProvider
12	core.in_memory_history_provider	In-memory history provider	agent_framework.InMemoryHistoryProvider
13	core.file_history_provider	File history provider	agent_framework.FileHistoryProvider
14	core.file_skills_source	File-backed skills	agent_framework.FileSkillsSource
15	core.in_memory_skills_source	In-memory / programmatic skills	agent_framework.InMemorySkillsSource
16	core.mcp_skills_source	MCP-backed skills	agent_framework.MCPSkillsSource
17	core.session_store	Agent session store	agent_framework.SessionStore / FileSessionStore
18–31	reserved	core growth	—
32	orchestration.sequential	Sequential orchestration	agent_framework_orchestrations.SequentialBuilder
33	orchestration.concurrent	Concurrent orchestration	agent_framework_orchestrations.ConcurrentBuilder
34	orchestration.group_chat	Group-chat orchestration	agent_framework_orchestrations.GroupChatBuilder
35	orchestration.magentic	Magentic orchestration	agent_framework_orchestrations.MagenticBuilder
36	orchestration.handoff	Handoff orchestration	agent_framework_orchestrations.HandoffBuilder
37–47	reserved	orchestration growth	—
48	foundry.chat_client	Foundry chat client	agent_framework_foundry.RawFoundryChatClient
49	foundry.agent	Foundry agent	agent_framework_foundry.FoundryAgent
50	foundry.memory	Foundry memory provider	agent_framework_foundry.FoundryMemoryProvider
51	foundry.embedding	Foundry embedding client	agent_framework_foundry.RawFoundryEmbeddingClient
52	foundry.evals	Foundry evaluations	agent_framework_foundry.FoundryEvals
53	foundry.toolbox	Foundry Toolbox MCP tool	agent_framework_foundry_hosting.FoundryToolbox
54	foundry_local	Foundry Local client	agent_framework_foundry_local.FoundryLocalClient
55	foundry_hosting	Foundry hosting layer	agent_framework_foundry_hosting.ResponsesHostServer / InvocationsHostServer
56	openai	OpenAI clients	agent_framework_openai
57	anthropic	Anthropic clients	agent_framework_anthropic
58	bedrock	AWS Bedrock clients	agent_framework_bedrock
59	gemini	Gemini chat client	agent_framework_gemini
60	mistral	Mistral embedding client	agent_framework_mistral
61	ollama	Ollama clients	agent_framework_ollama
62	claude	Claude Agent SDK agent	agent_framework_claude
63	copilotstudio	Copilot Studio agent	agent_framework_copilotstudio
64	github_copilot	GitHub Copilot agent	agent_framework_github_copilot
65	azure_ai_search	Azure AI Search context provider	agent_framework_azure_ai_search
66	azure_cosmos	Azure Cosmos history / checkpoint store	agent_framework_azure_cosmos
67	azure_contentunderstanding	Azure Content Understanding context provider	agent_framework_azure_contentunderstanding.ContentUnderstandingContextProvider
68	redis	Redis context / history provider	agent_framework_redis
69	mem0	Mem0 memory provider	agent_framework_mem0.Mem0ContextProvider
70	purview	Purview client	agent_framework_purview.PurviewClient
71	a2a	A2A agent / executor	agent_framework_a2a.A2AAgent / A2AExecutor
72	ag_ui	AG-UI chat client / agent	agent_framework_ag_ui
73	chatkit	ChatKit integration	agent_framework_chatkit
74	devui	DevUI served	agent_framework_devui.serve
75	declarative.agent	Declarative agent definitions	agent_framework_declarative.AgentFactory
76	declarative.workflow	Declarative workflow definitions	agent_framework_declarative.WorkflowFactory
77	durabletask	Durable task runtime	agent_framework_durabletask
78	azurefunctions	Azure Functions agent host	agent_framework_azurefunctions
79	tools.shell	Shell tools	agent_framework_tools.shell.LocalShellTool / DockerShellTool
80	monty	Monty CodeAct provider	agent_framework_monty.MontyCodeActProvider
81	hyperlight	Hyperlight CodeAct provider	agent_framework_hyperlight.HyperlightCodeActProvider
82	azure_cosmos_memory	Azure Cosmos DB semantic-memory provider	agent_framework_azure_cosmos_memory.CosmosMemoryContextProvider
83	hosting	App-owned agent/workflow hosting state	agent_framework_hosting.AgentState / WorkflowState
84	hosting.a2a	A2A hosting converters	agent_framework_hosting_a2a.a2a_to_run / a2a_from_run
85	hosting.mcp	MCP hosting adapters	agent_framework_hosting_mcp.AgentMCPTool / WorkflowMCPTool
86	hosting.responses	OpenAI Responses hosting converters	agent_framework_hosting_responses.responses_to_run
87	hosting.telegram	Telegram hosting converters	agent_framework_hosting_telegram.telegram_to_run
88	lab	Experimental Agent Framework Lab features	agent_framework.lab feature entry points
89–127	reserved	future packages	—

Index table — .NET (agent-framework-dotnet, version 1)

Index	Id	Feature	Activated at (representative)
0	core.agent	Agent	Microsoft.Agents.AI.ChatClientAgent
1	core.harness_agent	Harness agent	Microsoft.Agents.AI.HarnessAgent
2	core.workflow	Workflow engine (custom graphs)	Microsoft.Agents.AI.Workflows.WorkflowBuilder
3	core.tool_approval	Tool-approval agent	Microsoft.Agents.AI.ToolApprovalAgent
4	core.chat_history_memory_provider	Chat-history memory provider	Microsoft.Agents.AI.ChatHistoryMemoryProvider
5	core.file_memory_provider	File memory provider	Microsoft.Agents.AI.FileMemoryProvider
6	core.text_search_provider	Text-search provider	Microsoft.Agents.AI.TextSearchProvider
7	core.file_access_provider	File-access provider	Microsoft.Agents.AI.FileAccessProvider
8	core.skills_provider	Skills provider	Microsoft.Agents.AI.AgentSkillsProviderBuilder
9	core.compaction_provider	Context compaction provider	Microsoft.Agents.AI.Compaction.CompactionProvider
10	core.todo_provider	Todo provider	Microsoft.Agents.AI.TodoProvider
11	core.agent_mode_provider	Agent-mode provider	Microsoft.Agents.AI.AgentModeProvider
12	core.background_agents_provider	Background-agents provider	Microsoft.Agents.AI.BackgroundAgentsProvider
13	core.in_memory_history_provider	In-memory history provider	Microsoft.Agents.AI.InMemoryChatHistoryProvider
14	core.mcp	MCP tasks / skills integration	Microsoft.Agents.AI.Mcp.McpClientTaskExtensions
15	core.file_skills_source	File-backed skills	Microsoft.Agents.AI.AgentFileSkillsSource
16	core.in_memory_skills_source	In-memory skills	Microsoft.Agents.AI.AgentInMemorySkillsSource
17	core.inline_skill	Inline programmatic skill	Microsoft.Agents.AI.AgentInlineSkill
18	core.class_skill	Class-based programmatic skill	Microsoft.Agents.AI.AgentClassSkill
19	core.mcp_skills_source	MCP-backed skills	Microsoft.Agents.AI.AgentSkillsProviderBuilderMcpExtensions.UseMcpSkills
20–31	reserved	core growth	—
32	orchestration.sequential	Sequential orchestration	Microsoft.Agents.AI.Workflows.SequentialWorkflowBuilder
33	orchestration.concurrent	Concurrent orchestration	Microsoft.Agents.AI.Workflows.ConcurrentWorkflowBuilder
34	orchestration.group_chat	Group-chat orchestration	Microsoft.Agents.AI.Workflows.GroupChatWorkflowBuilder
35	orchestration.magentic	Magentic orchestration	Microsoft.Agents.AI.Workflows.MagenticWorkflowBuilder
36	orchestration.handoff	Handoff orchestration	Microsoft.Agents.AI.Workflows.HandoffWorkflowBuilder
37–47	reserved	orchestration growth	—
48	foundry.chat_client	Foundry chat client	Microsoft.Agents.AI.Foundry.FoundryChatClient
49	foundry.agent	Foundry agent	Microsoft.Agents.AI.Foundry.FoundryAgent
50	foundry.memory	Foundry memory provider	Microsoft.Agents.AI.Foundry.FoundryMemoryProvider
51	foundry.evals	Foundry evaluations	Microsoft.Agents.AI.Foundry.FoundryEvals
52	foundry.toolbox	Foundry Toolbox MCP tool	Microsoft.Agents.AI.Foundry.HostedMcpToolboxAITool
53	foundry_hosting	Foundry hosting layer	Microsoft.Agents.AI.Foundry.Hosting.FoundryHostingExtensions.AddFoundryResponses
54	openai	OpenAI integration	Microsoft.Agents.AI.OpenAI
55	anthropic	Anthropic integration	Microsoft.Agents.AI.Anthropic
56	copilotstudio	Copilot Studio agent	Microsoft.Agents.AI.CopilotStudio.CopilotStudioAgent
57	github_copilot	GitHub Copilot agent	Microsoft.Agents.AI.GitHub.Copilot.GitHubCopilotAgent
58	azure_cosmos	Cosmos history / checkpoint store	Microsoft.Agents.AI.CosmosChatHistoryProvider
59	valkey	Valkey chat-history provider	Microsoft.Agents.AI.Valkey.ValkeyChatHistoryProvider
60	mem0	Mem0 memory provider	Microsoft.Agents.AI.Mem0.Mem0Provider
61	purview	Purview integration	Microsoft.Agents.AI.Purview
62	a2a	A2A agent	Microsoft.Agents.AI.A2A.A2AAgent
63	hosting.ag_ui	AG-UI hosting endpoint	Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.AGUIEndpointRouteBuilderExtensions.MapAGUIServer
64	devui	DevUI served	Microsoft.Agents.AI.DevUI
65	declarative.agent	Declarative agent definitions	Microsoft.Agents.AI.PromptAgentFactory.CreateAsync
66	declarative.workflow	Declarative workflow definitions	Microsoft.Agents.AI.Workflows.Declarative.DeclarativeWorkflowBuilder.Build
67	durabletask	Durable task runtime	Microsoft.Agents.AI.DurableTask
68	azurefunctions	Azure Functions agent host	Microsoft.Agents.AI.Hosting.AzureFunctions
69	tools.shell	Shell tools	Microsoft.Agents.AI.Tools.Shell.ShellExecutor
70	hyperlight	Hyperlight CodeAct provider	Microsoft.Agents.AI.Hyperlight.HyperlightCodeActProvider
71	hosting.agent	Hosted AF agent wrapper	Microsoft.Agents.AI.Hosting.AIHostAgent
72	local_codeact	Local Python CodeAct provider	Microsoft.Agents.AI.LocalCodeAct.LocalCodeActProvider
73	hosting.a2a	A2A hosting endpoints	Microsoft.AspNetCore.Builder.A2AEndpointRouteBuilderExtensions.MapA2AJsonRpc
74	hosting.openai	OpenAI-compatible hosting endpoints	Microsoft.AspNetCore.Builder.MicrosoftAgentAIHostingOpenAIEndpointRouteBuilderExtensions.MapOpenAIResponses
75–127	reserved	future packages	—

Opt-out

The dedicated mask-only environment variable is shared by both SDKs:

• AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true|1 — drops only the feature mask; the base agent-framework-<lang>/{version} User-Agent is still sent.

The dedicated flag lets a privacy-conscious user keep contributing SDK identity/version (useful for support and compatibility triage) while withholding the feature-usage signal. Python's existing AGENT_FRAMEWORK_USER_AGENT_DISABLED=true|1 also suppresses its entire Agent Framework User-Agent contribution, mask included. Adding a matching .NET whole-User-Agent opt-out is outside this design.

Governance

1. One index per package/feature, numbered independently per language, in the table for that language. New indexes are added by editing this file in a reviewed PR; indexes are never reused within a (language, version).
2. Each package owns a private FeatureIndex declaration containing only its rows. Core owns the accumulator API and core indexes, but never imports optional packages. Adding a new optional-package index therefore does not require a core release once the marker API exists.
3. Adding a feature: apply the allocation tenet, name the concrete query/decision owner, add the package-local index and table row, and mark the stable public entry point where actual use begins.
4. Widening beyond 128-bit or re-partitioning bumps that language's version; old decoders keep working because the version prefix disambiguates the mapping.
5. A repository validation test gathers all package-local declarations for each (language, version) and asserts exact table parity, complete non-reserved coverage, 0..127 range, and no duplicate/overlapping indexes.

No machine-readable registry file ships today. Nothing consumes one at runtime (packages own private declarations). If/when a programmatic decoder is built, this table is the contract to export to JSON for it then.