fix: align agent workflows with unified azure.yaml

[huimiu]

Summary

Migrate azd ai agent doctor and next-step guidance to the effective configuration in azure.yaml (#8710).

This PR is the diagnostics layer in a stacked change. It keeps doctor, next-step guidance, and the runtime behavior aligned when agent configuration is inline, uses the deprecated config: block, or is provided through a local $ref. Existing agent.yaml and agent.manifest.yaml projects remain supported.

Stacked on #9149. Review #9149 first for the shared configuration and runtime read path. This PR targets hui/unified-config-runtime, not main.

Scope

Doctor

• Read the effective unified, legacy, or referenced agent definition.
• Validate models, connections, local resources, and manual environment requirements.
• Accept supported workflow kinds and provide source-appropriate remediation.
• Keep connection ownership and provisioning checks consistent with the runtime configuration.

Next-step guidance

• Build state from the normalized azure.yaml service configuration.
• Resolve local $ref configuration before generating guidance.
• Normalize typed YAML environment values to strings.
• Preserve referenced Foundry expressions and report incomplete resource state clearly.

Out of scope

• Runtime, deploy, provision, and synthesis changes are in prerequisite PR fix: read unified azure.yaml in agent run and deploy #9149.
• azure.ai.toolboxes $ref support is independent PR fix: resolve toolbox $ref config before deploy #9148.
• This PR does not change connection ownership behavior introduced by feat(agents): create Foundry connections at provision time #9046.

Review order

1. internal/pkg/projectconfig and internal/project in fix: read unified azure.yaml in agent run and deploy #9149 for the shared effective-configuration contract.
2. internal/cmd/doctor for validation and remediation behavior.
3. internal/cmd/nextstep for normalized state and guidance generation.

Validation

• go build ./...
• Targeted doctor, next-step, and command tests

Closes #8710

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Thank you for logging this issue; our team is reviewing it. If you need urgent prioritization, tag @RickWinter and @kristenwomack to let us know.

[Copilot]

Pull request overview

Aligns agent workflows and related Foundry resource extensions with unified azure.yaml, including $ref resolution and legacy fallbacks.

Changes:

• Resolves unified and referenced agent, connection, toolbox, and deployment configurations.
• Updates local run, deployment, guidance, and doctor behavior.
• Adds regression tests and changelog entries.

Reviewed changes

Copilot reviewed 44 out of 44 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
azure.ai.toolboxes/internal/cmd/service_target.go	Resolves toolbox $ref files.
azure.ai.toolboxes/internal/cmd/service_target_test.go	Tests referenced toolbox config.
azure.ai.toolboxes/CHANGELOG.md	Documents toolbox fix.
azure.ai.connections/internal/cmd/service_target.go	Resolves connection $ref files.
azure.ai.connections/internal/cmd/service_target_test.go	Tests referenced connection config.
azure.ai.connections/CHANGELOG.md	Documents connection fix.
azure.ai.agents/internal/synthesis/synthesizer.go	Resolves referenced provisioning inputs.
azure.ai.agents/internal/synthesis/synthesizer_test.go	Tests referenced deployments and agents.
azure.ai.agents/internal/project/service_update.go	Serializes project service writes.
azure.ai.agents/internal/project/service_target_agent.go	Resolves and deploys unified agent config.
azure.ai.agents/internal/project/service_target_agent_test.go	Tests references and environment merging.
azure.ai.agents/internal/project/foundry_provisioning_provider.go	Resolves referenced brownfield config.
azure.ai.agents/internal/project/foundry_provisioning_provider_test.go	Tests referenced project endpoints.
azure.ai.agents/internal/project/config.go	Accepts split toolbox names.
azure.ai.agents/internal/project/agent_definition.go	Adds unified $ref resolution helpers.
azure.ai.agents/internal/project/agent_definition_test.go	Tests unified and legacy definitions.
azure.ai.agents/internal/cmd/run.go	Merges service environment values locally.
azure.ai.agents/internal/cmd/run_test.go	Tests local environment resolution.
azure.ai.agents/internal/cmd/resource_services.go	Resolves split Foundry resources.
azure.ai.agents/internal/cmd/resource_services_test.go	Tests referenced resource collection.
azure.ai.agents/internal/cmd/nextstep/types.go	Extends guidance state metadata.
azure.ai.agents/internal/cmd/nextstep/state.go	Reads effective unified agent config.
azure.ai.agents/internal/cmd/nextstep/state_test.go	Tests unified guidance state.
azure.ai.agents/internal/cmd/nextstep/resolver.go	Selects deploy or provision guidance.
azure.ai.agents/internal/cmd/nextstep/resolver_test.go	Tests split-resource guidance.
azure.ai.agents/internal/cmd/nextstep/manifest.go	Collects unified and legacy resources.
azure.ai.agents/internal/cmd/nextstep/manifest_test.go	Tests resource collection and errors.
azure.ai.agents/internal/cmd/nextstep/format.go	Updates guidance documentation.
azure.ai.agents/internal/cmd/nextstep/config.go	Loads effective guidance configuration.
azure.ai.agents/internal/cmd/listen.go	Resolves config during lifecycle events.
azure.ai.agents/internal/cmd/listen_test.go	Tests referenced container settings.
azure.ai.agents/internal/cmd/helpers.go	Adds environment to local run context.
azure.ai.agents/internal/cmd/doctor/checks_toolboxes.go	Updates toolbox diagnostics.
azure.ai.agents/internal/cmd/doctor/checks_toolboxes_test.go	Tests toolbox ownership guidance.
azure.ai.agents/internal/cmd/doctor/checks_remote_test.go	Updates remote check expectations.
azure.ai.agents/internal/cmd/doctor/checks_project.go	Validates unified agent definitions.
azure.ai.agents/internal/cmd/doctor/checks_project_test.go	Tests unified definition diagnostics.
azure.ai.agents/internal/cmd/doctor/checks_manual_env.go	Updates environment diagnostics.
azure.ai.agents/internal/cmd/doctor/checks_manual_env_test.go	Updates diagnostic assertions.
azure.ai.agents/internal/cmd/doctor/checks_local.go	Updates local-check documentation.
azure.ai.agents/internal/cmd/doctor/checks_local_test.go	Updates local-check expectations.
azure.ai.agents/internal/cmd/doctor/checks_connections.go	Updates connection diagnostics.
azure.ai.agents/internal/cmd/doctor/checks_connections_test.go	Tests connection ownership guidance.
azure.ai.agents/CHANGELOG.md	Documents unified configuration fixes.

[jongio]

I looked into the two $ref overlay comments already on this PR and the mechanism holds up. foundry.ResolveFileRefs overlays a directive's sibling keys on top of the referenced file wholesale (the sibling loop in resolveRef), so any field persisted next to $ref wins over that same field in the referenced file on every later run.

One thing worth adding beyond what's already noted: in prepareContainerSettings, SetAgentContainerSettings writes container onto the original $ref-bearing properties and fills in DefaultMemory/DefaultCpu whenever they're unset. populateContainerSettings runs for every agent service, not just ones that actually set resources. So after the first preprovision run a $ref-backed service ends up with a container block (often just the injected defaults) pinned beside $ref, and later edits to container in the referenced agent file stop taking effect. The resolved project/RelativePath write in persistBuildService has the same shape.

For $ref-backed services, persisting only the fields the user authored inline, or writing derived defaults into the referenced file through the ref-aware editor, would avoid pinning values that silently override the source file.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum diff size. Try reducing the number of changed files and lines, and requesting a review from Copilot again.

[Copilot]

Pull request overview

Copilot reviewed 71 out of 72 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• .github/scripts/package-lock.json: Generated file

[jongio]

I re-checked the new commit against the $ref pinning I raised earlier. The persist-then-restore path plus not persisting resolved container settings for $ref-backed services closes that gap, and the added tests cover both the restore and the package-level revert.

I'm not approving yet because of a separate, unresolved issue in the connection templates. In main.bicep (and brownfield.bicep), connections is an ordinary array parameter:

param connections connectionsType = []

and connectionType carries credentials: object?. Non-secure deployment parameters are stored in the ARM deployment history in plaintext, so anyone with reader access on the deployment can recover those credentials. Moving the secret values into a @secure() object parameter, keeping only non-secret metadata in the array, and regenerating main.arm.json / brownfield.arm.json would close that off.

Worth also confirming the two related points already raised on this PR: the connection decoder in synthesizer.go dropping advanced auth properties (OAuth URLs/scopes, sharing, managed-identity), and the doctor check in checks_connections.go still pointing at azd deploy for split connections that are now provision-managed.

Once the credential handling is sorted this is good to approve.

[trangevi]

I think there was maybe a bad merge here, I'm seeing a number of changes that I believe I've reviewed elsewhere and should already be in main.

[jongio]

Following up on @trangevi's bad-merge note, since it checks out and I can pin down what happened.

The merge-base between this branch and main is 105d7e9f, and the branch is 2 commits behind main (missing #9007 and #9103, including the pin to the released azd module). The resolve unified workflow conflicts merge (18dd0d2e) pulled in changes from other in-flight PRs that have nothing to do with aligning agent workflows to unified azure.yaml.

The clearest example is an entire PR-registry-check tooling subsystem from #9042 that isn't in main and isn't part of this change:

• .github/scripts/src/ext-registry-check.js (+807), .github/scripts/test/ext-registry-check.test.js (+1089)
• .github/scripts/package.json, package-lock.json, jsconfig.json
• .github/workflows/ext-registry-check.yml, .github/workflows/scripts-ci.yml

None of those exist in main, so they're riding in from #9042 rather than belonging here. They account for a large chunk of the +8920/72-file size and make the actual unified-azure.yaml changes hard to isolate.

Rebasing onto current main (or dropping the merge and re-merging cleanly) so the diff only contains the agent-workflow work would resolve this and give the substantive changes a clean review. Worth a second pass over the merged-in toolbox commits (#9046, the toolbox-branch fix) to confirm which of those are genuinely part of this PR versus riding in from elsewhere.

This is separate from the credential-handling issue I raised earlier, which is still open.

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved — the merge commit (merge: resolve conflicts with main) integrates feat(toolboxes): reuse existing toolbox via endpoint in azure.yaml (#9024) from main into this branch. The two conflicts were both in azure.ai.toolboxes/internal/cmd/:

• service_target.go: combined our "slices" import (needed for containsToolboxFileRef) with main's "strings" import (needed for resolveReuseEndpoint), kept all our $ref support functions, and added main's Endpoint field + deployReuse/publishReuseEndpoint/resolveReuseEndpoint functions.
• service_target_test.go: kept our TestParseToolboxServiceConfig_FileRef test and added all the new endpoint/reuse tests from main.

All tests pass.

[Copilot]

Pull request overview

Copilot reviewed 49 out of 49 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 49 out of 49 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 46 out of 46 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.

[jongio]

Reviewed the doctor and next-step migration onto the unified azure.yaml. I traced the tiered resource resolution (split services, then bundled config, then the legacy manifest fallback), the env-variable precedence in the config merge, and the Foundry ${{...}} handling in extractEnvironmentRefs where the $-prefix guard correctly keeps those expressions out of both the missing-var and placeholder detectors. Build, vet, and the doctor and nextstep test suites pass locally. Moving config load and parse failures from silent skips to actionable doctor failures reads as a deliberate change, and the updated tests pin that behavior.

[microsoft-github-policy-service]

Hi @@huimiu. Thank you for your interest in helping to improve the Azure Developer CLI experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.