feat(agents): support Foundry ${{...}} server-side expressions in env expansion (#8602)

* fix(agents): preserve Foundry ${{...}} through ${VAR} expansion

Add a shared ExpandEnv helper in the azure.ai.agents extension that expands
azd ${VAR} references while leaving Foundry server-side ${{...}} expressions
untouched, and route the existing env-expansion call sites through it.

drone/envsubst cannot parse ${{...}} and returns the whole string unexpanded,
so any ${VAR} appearing alongside a ${{...}} span was silently dropped.
ExpandEnv splits on ${{...}} spans, expands only the gaps, and reattaches the
spans verbatim. This is the single shared expander Foundry fields will use as
part of unifying Foundry config in azure.yaml (design spec section 2.5).

Refactors resolveEnvironmentVariables (service_target_agent.go), resolveEnvValue
(listen.go), and resolveAgentDefinitionEnvVars (run.go) to use it.

* refactor(agents): address ExpandEnv review feedback

- Document that a ${VAR} inside a ${{...}} span is preserved verbatim, and
  add a test asserting it.
- Drop the now-redundant error fallback in resolveAgentDefinitionEnvVars;
  ExpandEnv already returns the original value on error.

* fix(agents): mask ${{...}} spans so ${VAR:-default} still expands

Switch ExpandEnv from splitting on ${{...}} spans to masking each span with
a sentinel placeholder, running a single envsubst pass, then restoring the
spans. The split approach failed when a ${{...}} expression was the default
of a ${VAR:-default} construct (e.g. ${MISSING:-${{event.body}}}), leaving an
unterminated "${MISSING:-" fragment that envsubst could not parse, so the
whole value was returned unexpanded. The sentinel contains no $, { or }, so
envsubst leaves it untouched even after a literal $. Adds tests for the
default-value cases and a leading-$ case.

Addresses review comment on internal/project/templating.go.

Author: huimiu

cli/azd/extensions/azure.ai.agents/internal/cmd/listen.go

@@ -24,7 +24,6 @@ import (
 	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
 	"github.com/braydonk/yaml"
-	"github.com/drone/envsubst"
 	"google.golang.org/protobuf/types/known/structpb"
 )
 
@@ -930,9 +929,10 @@ func resolveTemplateRef(s string) string {
 	return s
 }
 
-// resolveEnvValue resolves ${VAR} references in a string using envsubst.
+// resolveEnvValue resolves ${VAR} references in a string against the azd environment while
+// leaving Foundry server-side ${{...}} expressions untouched. See [project.ExpandEnv].
 func resolveEnvValue(value string, azdEnv map[string]string) string {
-	resolved, err := envsubst.Eval(value, func(varName string) string {
+	resolved, err := project.ExpandEnv(value, func(varName string) string {
 		return azdEnv[varName]
 	})
 	if err != nil {

cli/azd/extensions/azure.ai.agents/internal/cmd/run.go

@@ -25,9 +25,9 @@ import (
 
 	"azureaiagent/internal/cmd/nextstep"
 	"azureaiagent/internal/pkg/agents/agent_yaml"
+	"azureaiagent/internal/project"
 
 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
-	"github.com/drone/envsubst"
 	"github.com/spf13/cobra"
 	"go.yaml.in/yaml/v3"
 	"google.golang.org/grpc/codes"
@@ -514,10 +514,8 @@ func resolveAgentDefinitionEnvVars(
 		if _, isConn := connRefEnvNames[ev.Name]; isConn {
 			continue
 		}
-		resolved, evalErr := envsubst.Eval(ev.Value, lookup)
-		if evalErr != nil {
-			resolved = ev.Value
-		}
+		// ExpandEnv returns the original value on error, so a failed expansion is a no-op.
+		resolved, _ := project.ExpandEnv(ev.Value, lookup)
 		result = append(result, fmt.Sprintf("%s=%s", ev.Name, resolved))
 	}
 

cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent.go

@@ -40,7 +40,6 @@ import (
 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
 	"github.com/azure/azure-dev/cli/azd/pkg/output"
 	"github.com/braydonk/yaml"
-	"github.com/drone/envsubst"
 	"github.com/fatih/color"
 	"github.com/google/uuid"
 	"google.golang.org/protobuf/types/known/structpb"
@@ -2272,7 +2271,7 @@ func (p *AgentServiceTargetProvider) registerAgentEnvironmentVariables(
 // resolveEnvironmentVariables resolves ${ENV_VAR} style references in value using azd environment variables.
 // Supports default values (e.g., "${VAR:-default}") and multiple expressions (e.g., "${VAR1}-${VAR2}").
 func (p *AgentServiceTargetProvider) resolveEnvironmentVariables(value string, azdEnv map[string]string) string {
-	resolved, err := envsubst.Eval(value, func(varName string) string {
+	resolved, err := ExpandEnv(value, func(varName string) string {
 		return azdEnv[varName]
 	})
 	if err != nil {

cli/azd/extensions/azure.ai.agents/internal/project/templating.go

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package project
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/drone/envsubst"
+)
+
+// foundryTemplatePattern matches Foundry server-side ${{...}} expressions. These are resolved
+// by Foundry at runtime (for example ${{connections.x.credentials.key}} or ${{event.body}})
+// and must survive azd's client-side ${VAR} expansion untouched. The (?s) flag lets the span
+// cross newlines; the lazy quantifier stops at the first closing }}.
+var foundryTemplatePattern = regexp.MustCompile(`(?s)\$\{\{.*?\}\}`)
+
+// foundrySentinelBase is the prefix for placeholders that temporarily replace ${{...}} spans
+// while ${VAR} expansion runs. It contains no '$', '{', or '}', so drone/envsubst (which only
+// expands the braced ${...} form) copies it through untouched, even when a literal '$' precedes
+// it.
+const foundrySentinelBase = "azdFoundryTemplateSpan_"
+
+// ExpandEnv expands ${VAR} references in value against the azd environment (via mapping) while
+// preserving Foundry server-side ${{...}} expressions verbatim. It supports default values
+// (${VAR:-default}) and multiple expressions, matching drone/envsubst semantics for the ${VAR}
+// portion. On expansion error the original value is returned unchanged alongside the error.
+//
+// This is the single shared expander every Foundry field should route through so ${VAR} and
+// ${{...}} are handled consistently. drone/envsubst cannot parse ${{...}}, so each span is
+// masked with a sentinel placeholder, a single Eval expands the ${VAR} references, then the
+// spans are restored. Masking rather than splitting preserves full ${VAR:-default} semantics
+// even when a ${{...}} expression is the default value (e.g. ${MISSING:-${{event.body}}}).
+// A ${VAR} inside a ${{...}} span is left as-is, since the span is reserved for Foundry.
+func ExpandEnv(value string, mapping func(string) string) (string, error) {
+	spans := foundryTemplatePattern.FindAllString(value, -1)
+	if len(spans) == 0 {
+		expanded, err := envsubst.Eval(value, mapping)
+		if err != nil {
+			return value, err
+		}
+		return expanded, nil
+	}
+
+	// Choose a sentinel that does not already occur in the input so restoration is exact.
+	sentinel := foundrySentinelBase
+	for strings.Contains(value, sentinel) {
+		sentinel += "_"
+	}
+
+	index := 0
+	masked := foundryTemplatePattern.ReplaceAllStringFunc(value, func(string) string {
+		placeholder := fmt.Sprintf("%s%d_", sentinel, index)
+		index++
+		return placeholder
+	})
+
+	expanded, err := envsubst.Eval(masked, mapping)
+	if err != nil {
+		return value, err
+	}
+
+	for i, span := range spans {
+		expanded = strings.Replace(expanded, fmt.Sprintf("%s%d_", sentinel, i), span, 1)
+	}
+	return expanded, nil
+}

cli/azd/extensions/azure.ai.agents/internal/project/templating_test.go

@@ -0,0 +1,109 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package project
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestExpandEnv(t *testing.T) {
+	env := map[string]string{
+		"FOO":      "bar",
+		"ENDPOINT": "https://example.com",
+	}
+	mapping := func(name string) string { return env[name] }
+
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{name: "plain var", input: "${FOO}", want: "bar"},
+		{name: "var with default present", input: "${FOO:-fallback}", want: "bar"},
+		{name: "var with default absent", input: "${MISSING:-fallback}", want: "fallback"},
+		{name: "missing var no default", input: "${MISSING}", want: ""},
+		{name: "no templating", input: "plain text", want: "plain text"},
+		{name: "empty string", input: "", want: ""},
+		{name: "embedded var", input: "url=${ENDPOINT}/api", want: "url=https://example.com/api"},
+		{
+			name:  "foundry expression preserved",
+			input: "${{connections.x.credentials.key}}",
+			want:  "${{connections.x.credentials.key}}",
+		},
+		{
+			name:  "mixed var and foundry expression",
+			input: "prefix ${FOO} ${{event.body}} suffix",
+			want:  "prefix bar ${{event.body}} suffix",
+		},
+		{
+			name:  "adjacent foundry and var spans",
+			input: "${{a}}${FOO}${{b}}",
+			want:  "${{a}}bar${{b}}",
+		},
+		{
+			name:  "multiple foundry expressions only",
+			input: "${{a}} and ${{b}}",
+			want:  "${{a}} and ${{b}}",
+		},
+		{
+			name:  "var inside foundry span not expanded",
+			input: "${{ outer ${FOO} }}",
+			want:  "${{ outer ${FOO} }}",
+		},
+		{
+			name:  "foundry expression as default value, var unset",
+			input: "${MISSING:-${{event.body}}}",
+			want:  "${{event.body}}",
+		},
+		{
+			name:  "foundry expression as default value, var set",
+			input: "${FOO:-${{event.body}}}",
+			want:  "bar",
+		},
+		{
+			name:  "literal dollar before foundry span",
+			input: "$${{event.body}}",
+			want:  "$${{event.body}}",
+		},
+		{
+			name:  "foundry span across newline with var",
+			input: "${{first\nsecond}}\n${FOO}",
+			want:  "${{first\nsecond}}\nbar",
+		},
+		{
+			name:    "malformed unterminated expression returns original",
+			input:   "${{ unterminated",
+			want:    "${{ unterminated",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ExpandEnv(tt.input, mapping)
+			if tt.wantErr {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+			}
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+// TestExpandEnvNeverCorruptsFoundryExpressions guards the core invariant: a ${{...}} span is
+// always returned byte-for-byte, regardless of what surrounds it.
+func TestExpandEnvNeverCorruptsFoundryExpressions(t *testing.T) {
+	mapping := func(name string) string { return map[string]string{"TOKEN": "secret"}[name] }
+
+	const foundry = "${{connections.github-mcp-conn.credentials.x-api-key}}"
+	got, err := ExpandEnv("Authorization: ${TOKEN}; key: "+foundry, mapping)
+	require.NoError(t, err)
+	assert.Equal(t, "Authorization: secret; key: "+foundry, got)
+	assert.Contains(t, got, foundry)
+}