feat(nextstep): surface {{NAME}} placeholders left over in agent.yaml

Phase 2 commit 4.6 (MVP follow-up to 4.5). The toolbox sample exposes a
second MVP-level next-step bug: after `azd ai agent init` selects "Use
existing model deployment(s) from a Foundry project", the processed
`agent.yaml` retains a literal Mustache-style placeholder
`'{{TOOLBOX_ENDPOINT}}'` inside `environment_variables`. The current
Next: block flags only the sibling `${TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT}`
ref, leaving the user with the impression that one `azd env set` line
is the entire fix-up — when in reality the literal `{{TOOLBOX_ENDPOINT}}`
would land in the container as-is and break the agent on deploy.

Root cause: agent.manifest.yaml's parameter-substitution step
(`pkg/agents/agent_yaml/parameters.go:injectParameterValues`) is supposed
to replace every `{{NAME}}` and `{{ NAME }}` token with its parameter
value during init. When the manifest declares the placeholder but no
matching `parameters:` entry exists (or the user opts out at the
prompt), init prints a weak `Warning: Template contains unresolved
placeholders.` line at parameters.go:248 and moves on — the literal
`{{NAME}}` carries forward into the final agent.yaml. The nextstep
resolver had no concept of these placeholders: `extractAgentYamlEnvRefs`
matched only `${VAR}` refs, so the `{{NAME}}` was invisible.

Fix (resolver-side surfacing, as confirmed with user):

1. `types.go` — new `State.UnresolvedPlaceholders []string` field with
   a doc-comment that explicitly contrasts placeholders against
   Missing*Vars (cannot be supplied via `azd env set`; the literal lives
   in agent.yaml itself).

2. `state.go` — new `placeholderPattern` regex
   `\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}`. Allows optional internal
   whitespace because `injectParameterValues` substitutes both
   `{{NAME}}` and `{{ NAME }}` forms (parameters.go:238,242).
   `extractAgentYamlEnvRefs` signature changes from `[]string` to
   `(refs, placeholders []string)`. `detectMissingVars` signature
   extends from two return values to three (infra, manual,
   placeholders). `assembleState` callsite captures the third slice
   into `state.UnresolvedPlaceholders`. Read errors stay silent
   (same best-effort contract as before).

3. `resolver.go` — `ResolveAfterInit` decision tree extended:

   * Placeholder fix-ups ALWAYS come first when present, regardless of
     other branches. One `edit agent.yaml: replace {{NAME}} with the
     actual value` line per placeholder, capped at maxFixupLines (3),
     sorted ascending. Rationale: deploy-time landmines that block both
     `run` (literal `{{NAME}}` in container env) and `deploy`. They
     never reach `azd env set`.
   * Existing provision branch unchanged (still wins for
     `!HasProjectEndpoint || MissingInfraVars`).
   * Existing manual-vars branch unchanged.
   * New `case hasPlaceholders` (sentinel) deliberately suppresses
     `azd ai agent run` when only placeholders remain — running locally
     with literal `{{NAME}}` values produces a broken agent, so we don't
     suggest a path we know will fail.

   The constant `maxManualVarLines` renames to `maxFixupLines` (now
   shared between manual-vars and placeholder caps; same value = 3).

Decision scenarios validated (each covered by a new test case):

* Fresh init + Deploy new models           → `azd provision` + deploy.
* Fresh init + Use existing + bare ${VAR}  → `azd env set VAR` + deploy.
* Toolbox bug                              → `edit agent.yaml: replace {{X}}` +
                                              `azd env set Y` + deploy.
* Placeholders only                        → `edit agent.yaml: replace {{X}}` +
                                              deploy (NO run).
* Placeholders + no project endpoint       → `edit agent.yaml: replace {{X}}` +
                                              `azd provision` + deploy.
* Happy post-provision (no missing)        → `azd ai agent run` + deploy.

Tests:

* `state_test.go` — extended `TestExtractAgentYamlEnvRefs` table to a
  two-output schema (`wantRefs`, `wantPlaceholders`); 4 new table cases
  cover placeholders alone, internal-whitespace form, dedup, and
  ref+placeholder coexistence. New
  `TestAssembleState_PopulatesUnresolvedPlaceholders` reproduces the
  toolbox sample directly. New `TestAssembleState_PlaceholdersDeduped
  AcrossServices` locks cross-service dedup.

* `resolver_test.go` — new `TestResolveAfterInit_UnresolvedPlaceholders`
  table with 5 cases covering placeholders-alone, placeholders+manual,
  placeholders+missing-endpoint, sort-ascending, and >3 cap.

Preflight clean (gofmt, vet, build, full extension test suite green,
golangci-lint 0 issues, cspell 0 issues on the 3 production files).

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

Author: Antriksh Jain

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

@@ -23,16 +23,23 @@ const (
 	invokeInvocationsPayload = `'{"message": "Hello!"}'`
 	invokeResponsesPayload   = `"Hello!"`
 
-	// maxManualVarLines caps the number of `azd env set` hints emitted by
-	// ResolveAfterInit so the block stays scannable even when an agent
-	// declares many manual variables.
-	maxManualVarLines = 3
+	// maxFixupLines caps the number of `azd env set` / `edit agent.yaml`
+	// hints emitted by ResolveAfterInit per missing-input category so the
+	// block stays scannable even when an agent declares many manual
+	// variables or unresolved placeholders.
+	maxFixupLines = 3
 )
 
 // ResolveAfterInit produces the Next: block printed at the end of a
 // successful `azd ai agent init`. Pure function over *State.
 //
 // Decision tree:
+//   - UnresolvedPlaceholders (always shown first when present, regardless
+//     of other branches) → one "edit agent.yaml: replace {{NAME}}" line
+//     per unresolved Mustache placeholder (up to maxFixupLines). These
+//     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`
 //     The project endpoint is the canonical "provision finished"
 //     marker — it is set by `azd provision` as a Bicep output, or by
@@ -46,8 +53,10 @@ const (
 //     (a new ${AZURE_*} reference was added to agent.yaml after the
 //     last provision run).
 //   - MissingManualVars  → one `azd env set <KEY> <value>` per missing var
-//     (up to maxManualVarLines)
+//     (up to maxFixupLines)
 //   - Otherwise          → `azd ai agent run`
+//     Skipped when only UnresolvedPlaceholders are present, because
+//     running locally with literal `{{NAME}}` values is broken too.
 //
 // All paths append the static "When ready to deploy to Azure…" tail.
 func ResolveAfterInit(state *State) []Suggestion {
@@ -56,30 +65,56 @@ func ResolveAfterInit(state *State) []Suggestion {
 	}
 
 	out := make([]Suggestion, 0, 4)
+	priority := 5
+
+	// Placeholder fix-ups always come first when present: they are broken
+	// state in agent.yaml itself and block both `run` and `deploy`. The
+	// user has to edit agent.yaml (or define a matching parameter in
+	// agent.manifest.yaml) — `azd env set` cannot reach them.
+	hasPlaceholders := len(state.UnresolvedPlaceholders) > 0
+	if hasPlaceholders {
+		placeholders := slices.Clone(state.UnresolvedPlaceholders)
+		slices.Sort(placeholders)
+		limit := min(len(placeholders), maxFixupLines)
+		for _, name := range placeholders[:limit] {
+			out = append(out, Suggestion{
+				Command:     fmt.Sprintf("edit agent.yaml: replace {{%s}} with the actual value", name),
+				Description: "agent.yaml has unresolved manifest placeholders",
+				Priority:    priority,
+			})
+			priority++
+		}
+	}
 
 	switch {
 	case !state.HasProjectEndpoint || len(state.MissingInfraVars) > 0:
 		out = append(out, Suggestion{
 			Command:     "azd provision",
 			Description: "set up your Foundry project, models, and connections",
-			Priority:    10,
+			Priority:    priority,
 		})
 	case len(state.MissingManualVars) > 0:
 		manual := slices.Clone(state.MissingManualVars)
 		slices.Sort(manual)
-		limit := min(len(manual), maxManualVarLines)
-		for i, key := range manual[:limit] {
+		limit := min(len(manual), maxFixupLines)
+		for _, key := range manual[:limit] {
 			out = append(out, Suggestion{
 				Command:     fmt.Sprintf("azd env set %s <value>", key),
 				Description: "supply the agent.yaml variable",
-				Priority:    20 + i,
+				Priority:    priority,
 			})
+			priority++
 		}
+	case hasPlaceholders:
+		// Only unresolved placeholders remain — do not emit
+		// `azd ai agent run` because running locally with literal
+		// `{{NAME}}` values produces a broken agent. The placeholder
+		// fix-ups above already tell the user what to do.
 	default:
 		out = append(out, Suggestion{
 			Command:     "azd ai agent run",
 			Description: "start the agent locally",
-			Priority:    10,
+			Priority:    priority,
 		})
 	}
 

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

@@ -107,6 +107,120 @@ func TestResolveAfterInit_NilState(t *testing.T) {
 	assert.Nil(t, ResolveAfterInit(nil))
 }
 
+func TestResolveAfterInit_UnresolvedPlaceholders(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name             string
+		state            *State
+		wantPlaceholders []string // expected `{{NAME}}` names in order
+		wantMiddle       string   // expected non-trailing, non-placeholder primary (e.g., "azd provision", "azd env set FOO", or "" if none)
+		wantHasRun       bool     // expect `azd ai agent run` to appear?
+		wantHasDeploy    bool     // expect `azd deploy` trailing?
+	}{
+		{
+			name: "placeholders alone → edit lines + deploy, no run",
+			state: &State{
+				HasProjectEndpoint:     true,
+				UnresolvedPlaceholders: []string{"TOOLBOX_ENDPOINT"},
+			},
+			wantPlaceholders: []string{"TOOLBOX_ENDPOINT"},
+			wantHasRun:       false,
+			wantHasDeploy:    true,
+		},
+		{
+			name: "placeholders + missing manual vars → both surfaced, no run",
+			state: &State{
+				HasProjectEndpoint:     true,
+				UnresolvedPlaceholders: []string{"TOOLBOX_ENDPOINT"},
+				MissingManualVars:      []string{"TOOLBOX_MCP_ENDPOINT"},
+			},
+			wantPlaceholders: []string{"TOOLBOX_ENDPOINT"},
+			wantMiddle:       "azd env set TOOLBOX_MCP_ENDPOINT",
+			wantHasRun:       false,
+			wantHasDeploy:    true,
+		},
+		{
+			name: "placeholders + project endpoint missing → placeholders + provision",
+			state: &State{
+				HasProjectEndpoint:     false,
+				UnresolvedPlaceholders: []string{"TOOLBOX_ENDPOINT"},
+			},
+			wantPlaceholders: []string{"TOOLBOX_ENDPOINT"},
+			wantMiddle:       "azd provision",
+			wantHasRun:       false,
+			wantHasDeploy:    true,
+		},
+		{
+			name: "multiple placeholders sorted ascending",
+			state: &State{
+				HasProjectEndpoint:     true,
+				UnresolvedPlaceholders: []string{"CHARLIE", "ALPHA", "BRAVO"},
+			},
+			wantPlaceholders: []string{"ALPHA", "BRAVO", "CHARLIE"},
+			wantHasRun:       false,
+			wantHasDeploy:    true,
+		},
+		{
+			name: "more than three placeholders capped at three",
+			state: &State{
+				HasProjectEndpoint:     true,
+				UnresolvedPlaceholders: []string{"P1", "P2", "P3", "P4", "P5"},
+			},
+			wantPlaceholders: []string{"P1", "P2", "P3"},
+			wantHasRun:       false,
+			wantHasDeploy:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			out := ResolveAfterInit(tt.state)
+			require.NotEmpty(t, out)
+
+			// Walk the output:
+			//   1. leading run of placeholder fix-ups (one per wantPlaceholders[i])
+			//   2. optional middle command (provision / env set)
+			//   3. optional `azd ai agent run`
+			//   4. trailing `azd deploy`
+			for i, name := range tt.wantPlaceholders {
+				require.Less(t, i, len(out))
+				assert.Equal(t,
+					"edit agent.yaml: replace {{"+name+"}} with the actual value",
+					out[i].Command,
+				)
+			}
+
+			// The middle (if any) sits just past the placeholders.
+			if tt.wantMiddle != "" {
+				idx := len(tt.wantPlaceholders)
+				require.Less(t, idx, len(out))
+				assert.True(t,
+					strings.HasPrefix(out[idx].Command, tt.wantMiddle),
+					"middle suggestion %q does not have prefix %q",
+					out[idx].Command, tt.wantMiddle,
+				)
+			}
+
+			hasRun := false
+			hasDeploy := false
+			for _, s := range out {
+				switch {
+				case s.Command == "azd ai agent run":
+					hasRun = true
+				case s.Command == "azd deploy" && s.Trailing:
+					hasDeploy = true
+				}
+			}
+			assert.Equal(t, tt.wantHasRun, hasRun,
+				"presence of `azd ai agent run` mismatched")
+			assert.Equal(t, tt.wantHasDeploy, hasDeploy,
+				"presence of trailing `azd deploy` mismatched")
+		})
+	}
+}
+
 func TestResolveAfterRun(t *testing.T) {
 	t.Parallel()