Azure / Azure/azure-dev

[azure.ai.agents] Support --preview / dry-run for hosted agent deploy

Open
#8,549 1 comment 0 reactions 0 assignees View on GitHub
customer-reported ext-agents needs-discussion question
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.