[azure.ai.agents] Support azd environment variable expansion for agent names

[jayzhang]

Feature request

Reusable azure.ai.agents samples should be able to choose the deployed Foundry Agent name from the active azd environment so that the same sample can be deployed by multiple users with azd up.

Today, an Agent service definition such as:

name: foundry-agent-sample

services:
  agent:
    host: azure.ai.agent
    name: ${AGENT_NAME}

cannot be used with:

azd env set AGENT_NAME my-agent
azd up

The extension validates the literal string ${AGENT_NAME} as the Agent name before expanding it. Validation then fails because the value does not start with an alphanumeric character. The only first-class way to select the name today is to materialize it when running azd ai agent init --agent-name, which prevents a checked-in sample from being parameterized per azd environment.

Expected behavior

For services using host: azure.ai.agent, the extension should resolve azd environment expressions in extension-owned Agent identity fields before validating or using them in Foundry API requests.

For example, this should deploy or update the Agent named by AGENT_NAME:

name: foundry-agent-sample

services:
  agent:
    host: azure.ai.agent
    name: ${AGENT_NAME}

A related extension-owned display field should support the same behavior where applicable:

services:
  agent:
    host: azure.ai.agent
    name: ${AGENT_NAME}
    activity:
      publish:
        agentDisplayName: ${AGENT_DISPLAY_NAME}

Why this matters

Sample authors need stable checked-in project and service identifiers while allowing each user or environment to choose a unique remote Agent name. Requiring every user to edit or regenerate the sample makes the normal azd up path less reusable and is especially inconvenient for workshops, demos, CI, and multi-environment deployments.

Proposed scope

This can be implemented in the azure.ai.agents extension without adding generic interpolation to all azure.yaml fields:

• Keep the top-level azd project name as a stable literal.
• Keep the services map key (for example, agent) as a stable literal.
• Expand the extension-owned remote Agent name using the selected azd environment before Agent-name validation and before lookup/create/update operations.
• Apply the same expansion behavior to extension-owned Agent display-name fields where supported.
• Return a clear error identifying any referenced environment variable that is missing or empty.

Acceptance criteria

• services.<service-key>.name: ${AGENT_NAME} resolves from the active azd environment for host: azure.ai.agent.
• The resolved value, rather than the placeholder, is passed through existing Agent-name validation.
• Deploy lookup, create, and update operations consistently use the resolved Agent name.
• Missing or empty referenced variables produce an actionable error.
• Literal Agent names remain backward compatible.
• Tests cover successful expansion, missing variables, invalid resolved names, and literal names.
• Documentation includes a reusable-sample example using azd env set AGENT_NAME ... followed by azd up.

Non-goals

This request does not require environment expansion for the top-level azd project name or YAML map keys under services. Those values represent azd project/service identity and can remain stable while the remote Foundry Agent name varies by environment.