[Hui Miao (huimiu)]

Summary

Add azd ai agent list-alpha to show every declared agents preview feature and its effective status, using the same Name, Description, and Status: On/Off layout as the default azd config list-alpha output.

This layer builds on #10640 and preserves its simplified feature checks and current opt-in behavior.

Changes

• Add descriptions alongside the three existing declarations and a sorted catalog accessor. Include disabled features; exclude the discarded agents.hosted flag and core-only features.
• Reuse the existing evaluator with selected --environment, optional project/default-environment scopes, and source-error propagation. User config enables features only through case-insensitive string on at each alpha.<ID>; alpha.all is ignored. Other enablement behavior and the direct-endpoint limitation are unchanged.
• Keep listing always available. Resolve all statuses before writing to the command's injected writer, and reject unsupported explicit output formats, including empty values, before source reads.
• Register help and metadata, provide per-feature azd config set / azd env set examples, and update extension-local documentation and help snapshots.
• Add catalog, exact-output, independent-status, ignored-global-config, environment-selection, optional-scope, source-error/no-partial-output, writer-error, help, and metadata regressions using the existing gRPC test server.
• Add the offline tier0/0.32-list-alpha.yaml scenario and update root-help discovery coverage. No Azure scenarios were executed.

The command adds no authentication, cloud requests, prompts, configuration writes, or feature-specific telemetry. Existing host project/environment loaders retain their own behavior; this is not a host-wide no-side-effects guarantee. The published azd SDK remains pinned to v1.35.1, without replacements or dependency-manifest changes. All changes relative to the parent PR stay within the agents extension.

Validation

Using Go 1.26.4:

• go test .\internal\featureflags -count=1
• go test .\internal\cmd -run 'Test(ListAlpha|AgentHelp|RootCommand_PublicPreviewCommandsVisible|IndependentPreviewGates|GlobalConfigCannotUnlockPreviewGates|Preview)' -count=1
• go test .\internal\project -run '^Test(DocExamplesAreValid|Preview)' -count=1
• Extension build; built-binary root help, list-alpha help, and metadata checks.
• Scoped go vet, golangci-lint (zero issues), gofmt, go fix -diff (empty), cspell, changed-line/comment-length checks, and git diff --check.
• New and updated scenarios passed static validation. The cli-interactive-tester MCP server was unavailable, so list_scenarios and interactive scenario execution were not run.

No user authentication/configuration or Azure resources were modified.

Closes: #10656

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
25 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[github-actions]

🔗 Linked Issue Required

Thanks for the contribution! Please link a GitHub issue to this PR by adding Fixes #123 to the description or using the sidebar.
No issue yet? Feel free to create one!

[Copilot]

🟢 Approval recommended

The reviewed changes have complete regression coverage and no unresolved blocking issues.

No open issues 🎉

What changed in this PR

Adds azd ai agent list-alpha to display agent preview features and effective statuses.

Changes:

• Adds sorted feature catalog and command implementation.
• Reuses existing flag evaluation with validation and buffered output.
• Updates help, metadata, documentation, tests, snapshots, and offline scenarios.

File	Summary
cli/​azd/​extensions/​azure.ai.agents/​tests/​cli-interactive-tester-scenarios/​tier0/​0.32-list-alpha.yaml	Adds offline scenario coverage.
cli/​azd/​extensions/​azure.ai.agents/​tests/​cli-interactive-tester-scenarios/​tier0/​0.02-help-root.yaml	Updates root-help expectations.
cli/​azd/​extensions/​azure.ai.agents/​tests/​cli-interactive-tester-scenarios/​README.md	Registers scenario and tag.
cli/​azd/​extensions/​azure.ai.agents/​README.md	Documents listing and opt-in usage.
cli/​azd/​extensions/​azure.ai.agents/​internal/​featureflags/​featureflags.go	Adds feature descriptions.
cli/​azd/​extensions/​azure.ai.agents/​internal/​featureflags/​agents.go	Adds sorted feature catalog.
cli/​azd/​extensions/​azure.ai.agents/​internal/​featureflags/​agents_test.go	Tests catalog behavior.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​testdata/​TestAgentHelp-root.snap	Updates root help snapshot.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​testdata/​TestAgentHelp-list-alpha.snap	Adds command help snapshot.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​root.go	Registers the command and metadata.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​root_test.go	Covers command visibility.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​preview_features_test.go	Supports configurable test servers.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​list_alpha.go	Implements the listing command.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​list_alpha_test.go	Tests command behavior and failures.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​help_test.go	Covers command help styling.
cli/​azd/​extensions/​azure.ai.agents/​docs/​specs/​preview-feature-flags.md	Documents the command contract.

_{Review effort: Lite}

[azure-sdk-automation]

azure.ai.agents PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10655/azure-ai-agents.zip"

• Version: 1.0.0-beta.21.pr.10655.6983572
• Merge commit: ced6c2f