[azure.ai.agents] agent_yaml: name the unresolved placeholders in the post-substitution warning

The post-`init` warning at parameters.go:248 was just:

  Warning: Template contains unresolved placeholders.

…with no indication of WHICH placeholders. A user with multiple
unresolved entries had to read the new (4.6/4.7) `Next:` block to
find out, or open agent.yaml and grep for `{{` themselves. The
warning was strictly less useful than the structured guidance it
was meant to flag.

This commit:

1. Promotes the placeholder regex into the agent_yaml package as
   `PlaceholderPattern` (exported) and adds an
   `ExtractUnresolvedPlaceholders(template string) []string`
   helper that returns the deduplicated, sorted list of names.
   The regex was previously a private var in
   internal/cmd/nextstep/state.go. agent_yaml is the right home
   because parameters.go is what DOES the substitution — owning
   the placeholder syntax is the same package as owning the
   substitution semantics.

2. Updates parameters.go's `injectParameterValues` warning to use
   the helper:

     Warning: agent.yaml has 3 unresolved placeholder(s):
     APP_INSIGHTS_ENDPOINT, TOOLBOX_ENDPOINT,
     TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT. Edit agent.yaml and
     replace each `{{NAME}}` with the actual value before
     deploying.

   The names are sorted alphabetically (stable across runs;
   matches the helper's contract). The numeric prefix lets the
   user sanity-check that the count matches what they see in the
   Next: block.

3. Refactors `nextstep/state.go` to alias `agent_yaml.PlaceholderPattern`
   instead of duplicating the regex. The two call sites (warning +
   Next: guidance) MUST agree on what counts as a placeholder, and
   a single source-of-truth makes that drift-proof.

The shared regex (`\{\{\s*([^\s{}][^{}]*?)\s*\}\}`) matches everything
the 4.7 nextstep regex matched and nothing more — this is a
zero-behavior-change refactor of nextstep. The visible UX change
is in parameters.go's printed warning only.

Tests:
- `placeholders_test.go` (new) covers 12 cases on
  `ExtractUnresolvedPlaceholders`: empty, fully-substituted,
  single placeholder, multiple distinct (sorted), duplicates
  collapsed, hyphenated/dotted names, whitespace tolerated
  inside braces, empty `{{}}` rejected, whitespace-only
  `{{   }}` rejected, spaced + unspaced forms of the same name
  collapsed, mixed real values and placeholders.
- All pre-existing `injectParameterValues` tests still pass
  (substitution logic unchanged).
- All pre-existing nextstep `extractAgentYamlEnvRefs` tests
  still pass (regex is byte-for-byte identical to 4.7's via
  the alias).

Pre-flight: gofmt clean, vet clean, build clean, full extension
test suite green (cmd 17.4s, doctor 7.6s, nextstep 5.7s,
agent_yaml 6.6s, etc.), golangci-lint 0 issues on the whole
extension, cspell 0 on the 3 production files touched.

Files: 5 changed.
- agent_yaml/placeholders.go (new) — regex + ExtractUnresolved
  Placeholders helper.
- agent_yaml/placeholders_test.go (new) — 12 sub-cases.
- agent_yaml/parameters.go — warning now names placeholders.
- nextstep/state.go — placeholderPattern aliased to shared
  regex (no other change).

Refs PR Azure#8057. Direct follow-on to 4.6 (placeholder detection)
and 4.7 (multi-category rendering + regex broadening). Closes the
toolbox-sample multi-env-var UX gap end-to-end: the warning names
the placeholders, the Next: block surfaces every fix-up category,
and the user has actionable guidance at both layers.

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

Author: Antriksh Jain

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

@@ -55,25 +55,15 @@ const (
 // underscore, then alphanumeric or underscore.
 var envVarRefPattern = regexp.MustCompile(`\$\{([A-Za-z_][A-Za-z0-9_]*)(:-[^}]*)?\}`)
 
-// placeholderPattern captures {{NAME}} Mustache-style placeholders that
-// agent.manifest.yaml's parameter substitution (parameters.go's
-// injectParameterValues) is supposed to replace before producing the
-// final agent.yaml. Surviving placeholders in agent.yaml's
-// environment_variables values are deploy-time landmines: the value will
-// land in the container literally as `{{NAME}}`, breaking the agent.
-//
-// The capture group accepts any run of non-brace characters (allowing
-// internal whitespace as long as the name starts with a non-whitespace,
-// non-brace char) because parameters.go substitutes the raw manifest
-// parameter key without validating its shape (`strings.ReplaceAll` of
-// `{{<paramName>}}` and `{{ <paramName> }}`). A legitimate manifest
-// parameter named `toolbox-endpoint` (hyphen), `my.param` (dot), or
-// even `"my key"` (quoted YAML key with whitespace) would otherwise
-// slip past detection. Allows optional surrounding whitespace inside
-// the braces — matches both `{{NAME}}` and `{{ NAME }}` (the two
-// forms parameters.go knows how to substitute) plus more liberal
-// spacing for forgiving detection.
-var placeholderPattern = regexp.MustCompile(`\{\{\s*([^\s{}][^{}]*?)\s*\}\}`)
+// placeholderPattern aliases agent_yaml.PlaceholderPattern. nextstep
+// surfaces the same placeholders that agent_yaml's
+// injectParameterValues warns about, so the two MUST stay in lockstep.
+// Keeping a single shared regex (defined in agent_yaml, where the
+// substitution logic lives) makes that constraint explicit and avoids
+// drift if the placeholder syntax is ever broadened again. See
+// agent_yaml/placeholders.go for the full rationale on the regex
+// shape (hyphens, dots, whitespace in capture group).
+var placeholderPattern = agent_yaml.PlaceholderPattern
 
 // Source is the read-only view of azd that AssembleState needs.
 //

cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/parameters.go

@@ -231,9 +231,16 @@ func promptForTextValue(
 	return resp.Value, nil
 }
 
-// injectParameterValues replaces parameter placeholders in the template with actual values
+// injectParameterValues replaces parameter placeholders in the template with actual values.
+//
+// Any placeholders that remain after substitution are surfaced via a
+// stdout warning that names them, plus the nextstep guidance system
+// surfaces a concrete `edit agent.yaml: replace {{NAME}} with the
+// actual value` line in the post-init `Next:` block. The warning and
+// the next-step guidance use the same `PlaceholderPattern` so the two
+// stay aligned (a placeholder reported in the warning must show up
+// in the Next: block, and vice versa).
 func injectParameterValues(template string, paramValues ParameterValues) ([]byte, error) {
-	// Replace each parameter placeholder with its value
 	for paramName, paramValue := range paramValues {
 		placeholder := fmt.Sprintf("{{%s}}", paramName)
 		valueStr := fmt.Sprintf("%v", paramValue)
@@ -243,9 +250,13 @@ func injectParameterValues(template string, paramValues ParameterValues) ([]byte
 		template = strings.ReplaceAll(template, placeholder, valueStr)
 	}
 
-	// Check for any remaining unreplaced placeholders
-	if strings.Contains(template, "{{") && strings.Contains(template, "}}") {
-		fmt.Println("Warning: Template contains unresolved placeholders.")
+	if remaining := ExtractUnresolvedPlaceholders(template); len(remaining) > 0 {
+		fmt.Printf(
+			"Warning: agent.yaml has %d unresolved placeholder(s): %s. "+
+				"Edit agent.yaml and replace each `{{NAME}}` with the actual value before deploying.\n",
+			len(remaining),
+			strings.Join(remaining, ", "),
+		)
 	}
 
 	return []byte(template), nil

cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/placeholders.go

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package agent_yaml
+
+import (
+	"regexp"
+	"slices"
+)
+
+// PlaceholderPattern captures {{NAME}} Mustache-style placeholders that
+// injectParameterValues is supposed to replace before producing the
+// final agent.yaml. Surviving placeholders are deploy-time landmines:
+// the value lands in the container literally as `{{NAME}}`, breaking
+// the agent.
+//
+// The capture group accepts any run of non-brace characters (allowing
+// internal whitespace as long as the name starts with a non-whitespace,
+// non-brace char) because injectParameterValues substitutes the raw
+// manifest parameter key without validating its shape
+// (`strings.ReplaceAll` of `{{<paramName>}}` and `{{ <paramName> }}`),
+// and the YAML decoder assigns the raw key to Property.Name without
+// validation either. A legitimate manifest parameter named
+// `toolbox-endpoint` (hyphen), `my.param` (dot), or `"my key"` (quoted
+// YAML key with whitespace) would otherwise slip past detection.
+// Allows optional surrounding whitespace inside the braces — matches
+// both `{{NAME}}` and `{{ NAME }}` (the two forms
+// injectParameterValues knows how to substitute) plus more liberal
+// spacing for forgiving detection.
+//
+// Shared between this package's post-substitution warning and the
+// nextstep `Next:` guidance so the two stay in lockstep.
+var PlaceholderPattern = regexp.MustCompile(`\{\{\s*([^\s{}][^{}]*?)\s*\}\}`)
+
+// ExtractUnresolvedPlaceholders returns the deduplicated, sorted list
+// of placeholder NAMES (i.e. the inside of `{{...}}`) that remain in
+// template. An empty slice means the template is fully substituted.
+//
+// Used by both injectParameterValues (to surface a specific warning
+// naming the unresolved placeholders) and by nextstep's fix-up
+// generator (to surface the same names in the `Next:` block as a
+// concrete "edit agent.yaml" hint). The two call sites must agree
+// on what counts as a placeholder, hence the shared helper.
+func ExtractUnresolvedPlaceholders(template string) []string {
+	matches := PlaceholderPattern.FindAllStringSubmatch(template, -1)
+	if len(matches) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(matches))
+	out := make([]string, 0, len(matches))
+	for _, m := range matches {
+		if len(m) < 2 {
+			continue
+		}
+		name := m[1]
+		if _, ok := seen[name]; ok {
+			continue
+		}
+		seen[name] = struct{}{}
+		out = append(out, name)
+	}
+	slices.Sort(out)
+	return out
+}

cli/azd/extensions/azure.ai.agents/internal/pkg/agents/agent_yaml/placeholders_test.go

@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package agent_yaml
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestExtractUnresolvedPlaceholders(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		input    string
+		expected []string
+	}{
+		{
+			name:     "empty template returns nil",
+			input:    "",
+			expected: nil,
+		},
+		{
+			name:     "fully substituted template returns nil",
+			input:    "key: real-value\nother: another-real-value\n",
+			expected: nil,
+		},
+		{
+			name:     "single placeholder",
+			input:    "endpoint: {{TOOLBOX_ENDPOINT}}\n",
+			expected: []string{"TOOLBOX_ENDPOINT"},
+		},
+		{
+			name:     "multiple distinct placeholders sorted alphabetically",
+			input:    "a: {{ZEBRA}}\nb: {{APPLE}}\nc: {{MANGO}}\n",
+			expected: []string{"APPLE", "MANGO", "ZEBRA"},
+		},
+		{
+			name:     "duplicate placeholders deduplicated",
+			input:    "a: {{NAME}}-{{NAME}}\nb: {{NAME}}\n",
+			expected: []string{"NAME"},
+		},
+		{
+			name:     "hyphenated paramName captured",
+			input:    "endpoint: {{toolbox-endpoint}}\n",
+			expected: []string{"toolbox-endpoint"},
+		},
+		{
+			name:     "dotted paramName captured",
+			input:    "component: {{my.component.id}}\n",
+			expected: []string{"my.component.id"},
+		},
+		{
+			name:     "whitespace inside braces tolerated and stripped",
+			input:    "a: {{ FOO }}\nb: {{  BAR  }}\n",
+			expected: []string{"BAR", "FOO"},
+		},
+		{
+			name:     "empty braces do not match",
+			input:    "a: {{}}\nb: real-value\n",
+			expected: nil,
+		},
+		{
+			name:     "whitespace-only braces do not match",
+			input:    "a: {{   }}\nb: real-value\n",
+			expected: nil,
+		},
+		{
+			name:     "spaced and unspaced forms of the same name deduplicated",
+			input:    "a: {{NAME}}\nb: {{ NAME }}\n",
+			expected: []string{"NAME"},
+		},
+		{
+			name:     "mixed real values and placeholders",
+			input:    "a: actual\nb: {{MISSING_ONE}}\nc: actual\nd: {{MISSING_TWO}}\n",
+			expected: []string{"MISSING_ONE", "MISSING_TWO"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := ExtractUnresolvedPlaceholders(tt.input)
+			assert.Equal(t, tt.expected, got)
+		})
+	}
+}