[azure.ai.agents] Support --preview / dry-run for hosted agent deploy
- Dominant language
- Go
- Stars
- 569
- Forks
- 364
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 136
Description
## Is your feature request related to a problem?
`azd provision --preview` only shows a Bicep what-if, and hosted agents (`host: azure.ai.agent`) are intentionally not Bicep resources (see #8065). `azd deploy --preview` exits with code 1 because the `azure.ai.agents` extension doesn't implement a preview/dry-run mode. As a result, there is no way to see what will change in the deployed agent before running `azd deploy` — changes to `agent.yaml` / `agent.manifest.yaml` (resources, env vars, protocols, model deployment binding, container image tag) are invisible until after the fact.
## Describe the solution you'd like
Implement a dry-run path in the `azure.ai.agents` extension, surfaced either as:
- `azd deploy --preview` (preferred — consistent with `azd provision --preview`), and/or
- `azd ai agent deploy --dry-run`
The preview should fetch the currently deployed agent from the Foundry data plane and diff it against the local `agent.yaml` / `agent.manifest.yaml`, reporting changes grouped by:
- Metadata (name, description, tags)
- Protocols
- Resources (cpu / memory)
- Environment variables
- Model deployment reference
- Container image (would a new image be built/pushed?)
Exit non-zero only on error, not on "no changes".
## Describe alternatives you've considered
- Manually `GET` the agent from the Foundry data plane and diff in a script. Works, but every team has to reinvent it and it's not wired into the standard `azd` flow.
- `azd provision --preview` — by design, doesn't and won't cover agents (#8065).
## Additional context
- Related: #7962 (Unify Foundry agent configuration in azure.yaml) — a preview feature naturally hangs off the unified config model.
- Related: #8065 (Bicep-less agent init) — makes this gap more visible, since users no longer have any IaC-level diff to fall back on.
Repro:
```
azd deploy --preview
# exits 1; no diff for agent.yaml changes
```
## Reference implementation sketch
The diff can be produced today using `az rest` against the Foundry agents data plane. This is the minimal shape an in-extension preview would need to formalize:
```powershell
# Inputs from azd env
$projectEndpoint = $env:FOUNDRY_PROJECT_ENDPOINT
$agentName = 'agent-framework-agent-basic-responses' # from azure.yaml service key
$localAgentYaml = 'src/agent-framework-agent-basic-responses/agent.yaml'
# 1. Fetch currently deployed agent
$token = az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv
$deployed = Invoke-RestMethod ``
-Uri "$projectEndpoint/agents/$agentName?api-version=2025-05-01" ``
-Headers @{ Authorization = "Bearer $token" }
# 2. Load local desired state
$local = Get-Content $localAgentYaml -Raw | ConvertFrom-Yaml # or yq / python yaml
# 3. Normalize both sides to the same shape (subset comparable to API)
function Normalize($a) {
[pscustomobject]@{
name = $a.name
description = $a.description
protocols = $a.protocols | Sort-Object protocol
resources = $a.resources
environment_variables = $a.environment_variables | Sort-Object name
model_deployment = ($a.environment_variables | Where-Object name -eq 'AZURE_AI_MODEL_DEPLOYMENT_NAME').value
}
}
# 4. Emit diff
Compare-Object ``
(Normalize $deployed | ConvertTo-Json -Depth 10) ``
(Normalize $local | ConvertTo-Json -Depth 10)
```
Behavior the extension should add on top of this:
- Handle 404 → "agent does not exist; would be created".
- Compute the would-be container image tag from `git rev-parse HEAD` (or whatever tagging strategy the extension uses today) and compare against the deployed image reference.
- Exit 0 with "No changes" when normalized objects match.
- Honor `--output json` for CI consumption.
Contributor guide
Assessment
This issue has not been assessed yet.