[azure.ai.agents] Support azd environment variable expansion for agent names
- Dominant language
- Go
- Stars
- 569
- Forks
- 364
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 136
Description
### 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:
```yaml
name: foundry-agent-sample
services:
agent:
host: azure.ai.agent
name: ${AGENT_NAME}
```
cannot be used with:
```text
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`:
```yaml
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:
```yaml
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..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.
Contributor guide
Research direction
Start at the azure.ai.agents extension path exercised by azd up, and compare it with azd ai agent init --agent-name. Trace Agent-name validation and the deploy lookup, create, and update operations, then run the relevant extension tests. Done means environment-based names and display names expand before validation, missing variables fail clearly, and literal names remain compatible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, go
- Domain
- ai, cli, cloud
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100