improve the azd tools experience

[therealjohn]

The azd tool experience appears at unexpected times, and recommends tools in a way that is too general. We can improve this with a different experience that isn't focused on an all-in-one Azure install experience and instead focused on the scenario.

On first turn, azd shows this experience:

Let's get your development environment ready.

Discover and install Azure development tools such as Azure CLI, GitHub Copilot CLI, and Azure AI extensions.
To skip this check, set AZD_SKIP_FIRST_RUN=true or run azd config set tool.firstRunCompleted true.

? Would you like to check your Azure development tools?: [Y/n] Yes

Here are the tools it checks:

  ✓ Azure CLI (2.83.0)
  ✓ GitHub Copilot CLI (1.0.66)
  ✓ Azure Tools VS Code Extension (0.12.4)
  ✓ Bicep VS Code Extension (0.41.2)
  ○ GitHub Copilot Chat VS Code Extension — not installed
  ○ Azure MCP Server — not installed
  ✓ azd AI Agent Extensions (0.1.42-preview-foundrytest.1)

All recommended tools are installed. You're all set!

There are these problems:
When starting with AZD AI, devs use azd ai agent init which doesn't show this (only triggers on azd init). So it appears during the next azd provision or deploy which is a disruptive time to ask about this.
It's installing things that are not needed for Foundry development - Azure Tools, Bicep VSC, Azure MCP, etc.
GitHub Copilot Chat VS Code Extension is not an extension anymore, it's included in VSC now.

[RickWinter]

Framing the problem

The three problems raised here are all real, and they share one root cause: the first-run experience is built around a single flat "all Azure tools" registry that fires on a global trigger, with no notion of scenario.

Concretely, in the current code:

• Trigger is command-blind. ToolFirstRunMiddleware (cli/azd/cmd/middleware/tool_first_run.go) runs on the first non-workflow command and gates only on tool.firstRunCompleted. It has no idea what the user is doing. That is why it surfaces at a disruptive moment (the next provision/deploy) for AI users who entered through azd ai agent init instead of azd init.
• Recommendation set is global, not scenario-scoped. builtInTools (pkg/tool/manifest.go) is one list, and "recommended" is a static Priority field on each tool. Foundry users get Azure Tools VSC, Bicep VSC, and Azure MCP recommended at them regardless of relevance.
• One stale entry. GitHub Copilot Chat VS Code Extension is modeled as a separately installable extension; it now ships inside VS Code, so that detection/offer is misleading.

So the fix splits into two largely independent changes:

1. Make the trigger scenario-aware so the entry command (and the extension that invoked it) can declare its own toolset and own the timing.
2. Make the recommendation set a function of scenario, not a global priority flag, and prune/correct the manifest.

Current flow

flowchart TD
    A[azd command starts] --> B{ToolFirstRunMiddleware}
    B -->|IsChildAction / workflow| Z[run command]
    B --> C{shouldSkip?}
    C -->|env var / --no-prompt / CI / non-interactive / already completed| Z
    C -->|no| D[Banner: Let's get your dev env ready]
    D --> E{Confirm: check tools?}
    E -->|no| M[mark firstRunCompleted] --> Z
    E -->|yes| F[DetectAll over global builtInTools]
    F --> G[Show check / circle for every Azure tool]
    G --> H{missing recommended<br/>by static Priority?}
    H -->|yes| I[MultiSelect install] --> M
    H -->|no| J[All set!] --> M

Loading

The weak points: B ignores which command, and F/H operate on one global list keyed off a static Priority.

Proposed scenario-scoped flow

flowchart TD
    subgraph entry [Entry points declare a scenario]
      A1[azd init] -->|scenario: core| K
      A2[azd ai agent init] -->|scenario: ai-foundry| K
      A3[other extension init] -->|scenario: extension-provided| K
    end

    K[Scenario resolved for this run] --> B{ToolFirstRun: run now?}
    B -->|scenario has no toolset<br/>or already completed for scenario| Z[run command]
    B -->|scenario opted in at a good moment| D[Banner scoped to scenario]
    D --> E{Confirm: set up TOOLSET for SCENARIO?}
    E -->|no| M[mark scenario completed] --> Z
    E -->|yes| F[DetectAll over scenario toolset only]
    F --> G[Show only scenario-relevant tools]
    G --> H{missing required-for-scenario?}
    H -->|yes| I[MultiSelect install] --> M
    H -->|no| J[All set for SCENARIO] --> M

Loading

Key design shifts:

• Scenario as a first-class concept. Tools belong to one or more scenarios (e.g. core, ai-foundry) instead of carrying a single global recommended/optional flag. "Recommended" becomes recommended for scenario X.
• Entry command owns the trigger. azd ai agent init declares the ai-foundry scenario and can run its setup at init time, so it never leaks into a later provision/deploy. The completion key likely becomes per-scenario (tool.firstRun.<scenario>.completed) rather than one global boolean.
• Manifest cleanup. Drop the standalone GitHub.copilot-chat VSC entry (now bundled in VS Code), and keep Azure Tools / Bicep / Azure MCP out of the ai-foundry toolset.

Open questions

• Should extensions be able to contribute their own scenario + toolset (so azure.ai.* owns its list rather than core hard-coding it)?
• Do we want per-scenario completion state, or a single "I have seen this once" with scenario-aware re-prompting?

[JeffreyCA]

Building on @RickWinter's ideas, one thing I'd add is how to handle the case where someone runs azd ai agent init and then azd up, since keying off the command name alone might not be sufficient.

up/provision/deploy are scenario-agnostic: the same azd up runs whether you've got a web app or a Foundry agent, so there isn't really a signal in the command itself that tells you which experience is relevant. The project does, though. I think we could resolve the scenario two different ways depending on where you are in the flow.

Before a project exists (azd init, or an extension's own init-style verb), we could use the command. Once a project exists, we could read azure.yaml and map each service's host: to a scenario. So azd up after ai agent init would read the project, see the agent host, resolve to the Foundry scenario, and stay quiet because that scenario was already handled at init time.

On the two open questions:

Extensions should probably own their own scenario and toolset, and declaring it in extension.yaml seems better than going over a gRPC call, since there's not much point spawning the extension just to ask what tools it wants. In practice that's a toolScenarios block (scenario id, the verbs that trigger it, the tool list) plus a scenario field on providers[] for the host mapping above. Core wouldn't hardcode anything except core; everything else would live with the extension that owns it.

For completion state, I'd lean toward per-scenario rather than a single flag. Each scenario would track its own tool.firstRun.<scenario>.completed, and the old global flag would migrate to mean "core is done" only, so nobody who has already seen the check gets re-prompted for core, but they stay eligible for a Foundry-specific check the first time they open a Foundry project.

One caveat: the host-to-scenario mapping comes entirely from installed extension metadata, with no fallback baked into core, so the Foundry improvement only kicks in once azure.ai.agents ships the new extension.yaml fields and people update. It won't retroactively fix existing installs.

Rough phasing:

1. Scenario data model, core-command resolution, and dropping the Copilot Chat VS Code entry (it ships inside VS Code now)
2. Extension-contributed scenarios end to end, covering both the init trigger and the project-content path
3. Flip the flag once it's validated against a real azure.ai.agents build