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

[rahulbats]

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 (Make azd ai agent init Bicep-less by default; add --infra to eject #8065).

Additional context

• Related: Unify Foundry agent configuration in azure.yaml #7962 (Unify Foundry agent configuration in azure.yaml) — a preview feature naturally hangs off the unified config model.
• Related: Make azd ai agent init Bicep-less by default; add --infra to eject #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:

# 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.