feat(extensions/azure.ai.agents): suggest azd provision after init's deploy-new path

User-reported MVP bug: after `azd ai agent init` with "Deploy new
model(s) from the catalog", the trailer says `azd deploy` (or
`azd ai agent run`) instead of `azd provision`. The deploy-new path
needs `azd provision` first to create the Foundry project — running
locally or deploying without it cannot succeed.

Root cause: the post-init resolver uses `AZURE_AI_PROJECT_ENDPOINT`
as a "provision finished" marker. That marker is reliable on a green
field, but a stale endpoint value carried over from a prior init
run (existing-project path), or from a sibling azd environment that
already provisioned, leaves HasProjectEndpoint=true. With no missing
infra vars in the post-init agent.yaml, the resolver hits the default
branch and suggests `azd ai agent run` — misleading the user into
running a local invoke against a project that has not been provisioned.

Fix: add an explicit `NeedsAIProjectProvision` signal to nextstep.State.
The signal is driven by the existing `USE_EXISTING_AI_PROJECT` env var
that init.go already writes:
  - init.go:976  → "false" when user picked "Deploy new model(s)"
  - init.go:943  → "true"  when user picked an existing Foundry project
  - init.go:954, 881, 864  → "false" on existing-path fallbacks (no
    project found, no matching models, etc.) — semantically equivalent
    to "Deploy new" for the resolver's purposes.

assembleState now reads USE_EXISTING_AI_PROJECT alongside
AZURE_AI_PROJECT_ENDPOINT and sets NeedsAIProjectProvision=(value=="false").
Only the literal string "false" enables the flag; an unset variable
(no prior init) or "true" both leave it false, so existing-path
behavior is unchanged.

ResolveAfterInit's case 1 (the `azd provision` primary) now fires on
NeedsAIProjectProvision OR !HasProjectEndpoint OR MissingInfraVars.
This makes the deploy-new override explicit: when the user just
committed to creating a new Foundry project, suggest `azd provision`
regardless of any stale endpoint value lingering in the env.

Trade-off accepted: if the user re-runs `azd ai agent init` AFTER a
successful provision (when USE_EXISTING_AI_PROJECT=false persists in
the env), they'll see `azd provision` suggested again. Provision is
idempotent so this is harmless "false noise" rather than a broken
suggestion. A future refinement could use Bicep-output signatures
to distinguish post-provision from stale-endpoint, but that is out of
scope for the MVP bug fix.

Rejected alternatives:
  - Tristate `*bool` field: gross to use in Go; the boolean default
    correctly handles "unset" and "true" together.
  - Clearing AZURE_AI_PROJECT_ENDPOINT at init.go:976: bigger blast
    radius; affects downstream consumers beyond the resolver.
  - Detecting "provision has run" via secondary Bicep outputs:
    too template-specific.

Tests:
  - state_test.go: 4 new sub-cases in TestAssembleState covering env
    var unset / "true" / "false" / unrecognized value. Existing
    transport-error tests updated for the new env read (errCount
    bumped from 2→3 and 3→4 to match the additional read).
  - resolver_test.go: 2 new sub-cases in TestResolveAfterInit
    covering NeedsAIProjectProvision=true with stale endpoint
    (override fires) and =false with endpoint set (legacy heuristic
    drives — anti-regression case).

Pre-flight clean: gofmt, vet, build, full extension test suite green
(cmd 16.8s, nextstep 5.7s, doctor 4.5s, agent_api 10.8s, agent_yaml
1.5s, etc.), golangci-lint 0 issues, cspell 0 issues.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver.go

@@ -40,7 +40,8 @@ const (
 //     are deploy-time landmines: the literal `{{NAME}}` would otherwise
 //     land in the container. They never reach `azd env set` because the
 //     value lives in agent.yaml itself, not the azd environment.
-//   - !HasProjectEndpoint OR MissingInfraVars → `azd provision`
+//   - NeedsAIProjectProvision OR !HasProjectEndpoint OR MissingInfraVars
+//     → `azd provision`
 //     The project endpoint is the canonical "provision finished"
 //     marker — it is set by `azd provision` as a Bicep output, or by
 //     `azd ai agent init` when the user selects an existing Foundry
@@ -51,7 +52,13 @@ const (
 //     directly references any AZURE_* variables. MissingInfraVars is
 //     still consulted to cover the post-provision re-provision case
 //     (a new ${AZURE_*} reference was added to agent.yaml after the
-//     last provision run).
+//     last provision run). NeedsAIProjectProvision adds an explicit
+//     override for the deploy-new path: USE_EXISTING_AI_PROJECT=false
+//     means the user just committed to creating a new Foundry project
+//     via Bicep, so any AZURE_AI_PROJECT_ENDPOINT carried over from a
+//     prior init or environment is stale and must not let the resolver
+//     mistake the state for "ready to run or deploy". See
+//     state.NeedsAIProjectProvision for the env-var contract.
 //   - MissingManualVars  → one `azd env set <KEY> <value>` per missing var
 //     (up to maxFixupLines)
 //   - Otherwise          → `azd ai agent run`
@@ -87,7 +94,7 @@ func ResolveAfterInit(state *State) []Suggestion {
 	}
 
 	switch {
-	case !state.HasProjectEndpoint || len(state.MissingInfraVars) > 0:
+	case state.NeedsAIProjectProvision || !state.HasProjectEndpoint || len(state.MissingInfraVars) > 0:
 		out = append(out, Suggestion{
 			Command:     "azd provision",
 			Description: "set up your Foundry project, models, and connections",

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver_test.go

@@ -59,6 +59,38 @@ func TestResolveAfterInit(t *testing.T) {
 			wantPrimaryHas: "azd provision",
 			wantTrailing:   "azd deploy",
 		},
+		{
+			// User selected "Deploy new model(s)" in init. The Foundry
+			// project does not exist yet, but a stale
+			// AZURE_AI_PROJECT_ENDPOINT carried over from a prior init
+			// or sibling environment sets HasProjectEndpoint=true.
+			// Without the explicit NeedsAIProjectProvision signal the
+			// resolver would default to `azd ai agent run` and
+			// mislead the user into running a local invoke against a
+			// project that has not been provisioned.
+			name: "deploy-new chosen but stale endpoint → provision (override)",
+			state: &State{
+				HasProjectEndpoint:      true,
+				NeedsAIProjectProvision: true,
+			},
+			wantPrimaryHas: "azd provision",
+			wantTrailing:   "azd deploy",
+		},
+		{
+			// Existing-project init path. USE_EXISTING_AI_PROJECT=true
+			// leaves NeedsAIProjectProvision=false at state assembly,
+			// so the legacy heuristic continues to drive: endpoint
+			// set + no missing vars ⇒ `azd ai agent run`. This case
+			// locks the no-regression contract for the existing
+			// path.
+			name: "existing project chosen, all vars set → run locally (no override)",
+			state: &State{
+				HasProjectEndpoint:      true,
+				NeedsAIProjectProvision: false,
+			},
+			wantPrimaryHas: "azd ai agent run",
+			wantTrailing:   "azd deploy",
+		},
 	}
 
 	for _, tt := range tests {

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/state.go

@@ -35,6 +35,17 @@ const (
 	// endpoint URL produced by `azd ai agent init`.
 	projectEndpointVar = "AZURE_AI_PROJECT_ENDPOINT"
 
+	// useExistingAIProjectVar records the user's choice in the
+	// `azd ai agent init` model-configuration step. "true" means the
+	// user selected an existing Foundry project (init populated
+	// AZURE_AI_PROJECT_ENDPOINT and related vars immediately from that
+	// project); "false" means the user opted to create a new Foundry
+	// project, which requires `azd provision` to run before any
+	// AZURE_AI_PROJECT_ENDPOINT value reflects reality. The variable
+	// also drives Bicep's "skip project creation" branch — see
+	// USE_EXISTING_AI_PROJECT in CHANGELOG.md entry for PR #7843.
+	useExistingAIProjectVar = "USE_EXISTING_AI_PROJECT"
+
 	// azureInfraPrefix tags an env-var name as an azd-infra output rather
 	// than a user-supplied manual variable. Outputs of `azd provision`
 	// in the AI Foundry templates uniformly start with this prefix
@@ -215,6 +226,23 @@ func assembleState(ctx context.Context, src Source, opts ...Option) (*State, []e
 			errs = append(errs, fmt.Errorf("read %s: %w", projectEndpointVar, err))
 		}
 		state.HasProjectEndpoint = endpoint != ""
+
+		// USE_EXISTING_AI_PROJECT is the explicit signal `azd ai agent
+		// init` writes to record the user's deploy-vs-existing choice.
+		// When the user just selected "Deploy new model(s)" (value
+		// "false"), the Foundry project does not exist yet — any
+		// AZURE_AI_PROJECT_ENDPOINT value carried over from a prior
+		// init run or a sibling environment is stale and must not let
+		// the post-init resolver mistake the state for "ready to run
+		// or deploy". The flag is only set for the literal string
+		// "false"; an unset variable (no init yet) or "true" both
+		// leave the flag false so existing resolver heuristics drive
+		// the decision.
+		useExisting, err := src.EnvValue(ctx, envName, useExistingAIProjectVar)
+		if err != nil {
+			errs = append(errs, fmt.Errorf("read %s: %w", useExistingAIProjectVar, err))
+		}
+		state.NeedsAIProjectProvision = useExisting == "false"
 	}
 
 	project, err := src.Project(ctx)

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/state_test.go

@@ -155,9 +155,73 @@ func TestAssembleState(t *testing.T) {
 				require.Len(t, state.Services, 1)
 				assert.False(t, state.Services[0].IsDeployed)
 				assert.False(t, state.HasProjectEndpoint)
+				assert.False(t, state.NeedsAIProjectProvision)
+			},
+			// One error for AZURE_AI_PROJECT_ENDPOINT + one for USE_EXISTING_AI_PROJECT
+			// + one per service lookup (AGENT_ECHO_VERSION) = 3.
+			errCount: 3,
+		},
+		{
+			name: "USE_EXISTING_AI_PROJECT unset: NeedsAIProjectProvision stays false",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values:  map[string]string{"dev/AZURE_AI_PROJECT_ENDPOINT": "https://x.services.ai.azure.com"},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.True(t, state.HasProjectEndpoint)
+				assert.False(t, state.NeedsAIProjectProvision)
+			},
+		},
+		{
+			name: "USE_EXISTING_AI_PROJECT=true: existing-project path, NeedsAIProjectProvision stays false",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values: map[string]string{
+					"dev/AZURE_AI_PROJECT_ENDPOINT": "https://x.services.ai.azure.com",
+					"dev/USE_EXISTING_AI_PROJECT":   "true",
+				},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.True(t, state.HasProjectEndpoint)
+				assert.False(t, state.NeedsAIProjectProvision)
+			},
+		},
+		{
+			name: "USE_EXISTING_AI_PROJECT=false: deploy-new path, NeedsAIProjectProvision is true",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values: map[string]string{
+					// Stale endpoint from a prior init carried over. The
+					// NeedsAIProjectProvision flag is the explicit signal
+					// the resolver needs to suggest `azd provision`
+					// despite the endpoint check independently passing.
+					"dev/AZURE_AI_PROJECT_ENDPOINT": "https://stale.services.ai.azure.com",
+					"dev/USE_EXISTING_AI_PROJECT":   "false",
+				},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.True(t, state.HasProjectEndpoint)
+				assert.True(t, state.NeedsAIProjectProvision)
+			},
+		},
+		{
+			name: "USE_EXISTING_AI_PROJECT unrecognized value: NeedsAIProjectProvision stays false",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values: map[string]string{
+					"dev/AZURE_AI_PROJECT_ENDPOINT": "https://x.services.ai.azure.com",
+					"dev/USE_EXISTING_AI_PROJECT":   "maybe",
+				},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.True(t, state.HasProjectEndpoint)
+				// Only literal "false" enables the flag.
+				assert.False(t, state.NeedsAIProjectProvision)
 			},
-			// One error for AZURE_AI_PROJECT_ENDPOINT + one per service lookup = 2.
-			errCount: 2,
 		},
 	}
 
@@ -834,8 +898,9 @@ environment_variables:
 	}
 
 	state, errs := assembleState(context.Background(), src)
-	// One error for AZURE_AI_PROJECT_ENDPOINT + AGENT_ECHO_VERSION + MY_API_KEY.
-	assert.Len(t, errs, 3)
+	// One error each for AZURE_AI_PROJECT_ENDPOINT + USE_EXISTING_AI_PROJECT
+	// + AGENT_ECHO_VERSION + MY_API_KEY.
+	assert.Len(t, errs, 4)
 	assert.Empty(t, state.MissingInfraVars)
 	assert.Empty(t, state.MissingManualVars)
 }

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/types.go

@@ -65,6 +65,23 @@ type State struct {
 	// (and non-empty) in the active azd environment.
 	HasProjectEndpoint bool
 
+	// NeedsAIProjectProvision is true when `azd ai agent init` recorded
+	// `USE_EXISTING_AI_PROJECT=false` — i.e., the user selected
+	// "Deploy new model(s)" rather than picking an existing Foundry
+	// project. In that mode the Foundry project does not yet exist and
+	// `azd provision` is required before `azd ai agent run` or
+	// `azd deploy` can succeed. The flag exists alongside
+	// HasProjectEndpoint because a stale AZURE_AI_PROJECT_ENDPOINT
+	// from a prior init or a sibling environment can otherwise satisfy
+	// the existing "endpoint set ⇒ provisioned" check and mislead the
+	// post-init trailer into recommending `azd ai agent run`. Treat
+	// this flag as an OR-contributor to "needs provision" in
+	// resolvers: when true, suggest `azd provision` even if the
+	// endpoint check independently passes. The flag is false when the
+	// variable is unset (no prior init) or "true" (existing path) so
+	// the existing heuristic continues to drive those cases.
+	NeedsAIProjectProvision bool
+
 	// MissingInfraVars names ${...} references in agent.yaml that map to
 	// Bicep outputs not yet present in the azd environment (i.e.,
 	// provision is needed or has been skipped). Named so the resolver can