fix: align agent workflows with unified azure.yaml by huimiu · Pull Request #9081 · Azure/azure-dev

huimiu · 2026-07-10T13:44:15Z

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

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

Validation

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

Closes #8710

github-actions · 2026-07-10T13:45:06Z

📋 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

Pull request overview

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

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.

huimiu · 2026-07-14T09:00:51Z

@copilot resolve the merge conflicts in this pull request

Copilot · 2026-07-14T09:07:34Z

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

+	if err := AddServiceSerialized(
+		ctx,
+		p.azdClient,
+		persisted,
+	); err != nil {


+		if projectpkg.ConfigContainsFileRef(svc.GetAdditionalProperties()) ||
+			projectpkg.ConfigContainsFileRef(svc.GetConfig()) {


+	ca, isHosted, found, source, err :=
+		AgentDefinitionFromResolvedService(svc, projectRoot)


Copilot

Pull request overview

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

+	needsModels := len(resources.models) == 0
+	needsToolboxes := len(resources.toolboxes) == 0
+	needsConnections := len(resources.connections) == 0


+	for _, svc := range services {
 		data := readManifestBytes(projectPath, svc.RelativePath)


+			return Result{
+				Status:  StatusPass,
+				Message: "model resource configuration loaded.",


+	suggestion := "Run `azd provision` to create the missing " +
+		"connection(s), or update their azure.yaml service names."


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.

Copilot AI review requested due to automatic review settings July 10, 2026 13:44

huimiu requested review from JeffreyCA, glharper, therealjohn, trangevi and trrwilson as code owners July 10, 2026 13:44

microsoft-github-policy-service Bot assigned huimiu Jul 10, 2026

Copilot started reviewing on behalf of huimiu July 10, 2026 13:45 View session

huimiu marked this pull request as draft July 10, 2026 13:45

github-actions Bot added ext-agents azure.ai.agents extension ext-connections azure.ai.connections extension ext-toolboxes azure.ai.toolboxes extension labels Jul 10, 2026

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent.go Outdated

Comment thread cli/azd/extensions/azure.ai.agents/internal/cmd/listen.go Outdated

huimiu marked this pull request as ready for review July 13, 2026 14:24

Copilot AI review requested due to automatic review settings July 13, 2026 14:39

huimiu requested review from RickWinter, danieljurek, tg-msft and vhvb1989 as code owners July 13, 2026 14:39

Copilot started reviewing on behalf of huimiu July 13, 2026 14:42 View session

jongio reviewed Jul 13, 2026

View reviewed changes

Copilot AI reviewed Jul 13, 2026

Copilot AI review requested due to automatic review settings July 13, 2026 14:53

Copilot started reviewing on behalf of huimiu July 13, 2026 14:56 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

jongio reviewed Jul 13, 2026

View reviewed changes

trangevi requested changes Jul 13, 2026

View reviewed changes

Comment thread .github/scripts/src/ext-registry-check.js

Comment thread cli/azd/extensions/azure.ai.connections/internal/cmd/service_target.go

jongio reviewed Jul 13, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 14, 2026 02:26

Copilot AI review requested due to automatic review settings July 14, 2026 04:49

Copilot started reviewing on behalf of huimiu July 14, 2026 04:50 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 14, 2026 05:48

Copilot started reviewing on behalf of huimiu July 14, 2026 05:49 View session

Copilot AI reviewed Jul 14, 2026

Copilot started work on behalf of huimiu July 14, 2026 09:01 View session

Copilot AI review requested due to automatic review settings July 14, 2026 09:05

huimiu requested a review from hemarina as a code owner July 14, 2026 09:05

Copilot started reviewing on behalf of huimiu July 14, 2026 09:06 View session

Copilot finished work on behalf of huimiu July 14, 2026 09:08

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent.go

Comment thread cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/checks_project.go Outdated

Copilot AI review requested due to automatic review settings July 14, 2026 10:11

Copilot started reviewing on behalf of huimiu July 14, 2026 10:11 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent.go

huimiu mentioned this pull request Jul 15, 2026

fix: resolve toolbox $ref config before deploy #9148

Open

Copilot AI review requested due to automatic review settings July 15, 2026 03:14

Copilot started reviewing on behalf of huimiu July 15, 2026 03:15 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

huimiu mentioned this pull request Jul 15, 2026

fix: read unified azure.yaml in agent run and deploy #9149

Open

fix: migrate agent doctor and next-step to unified azure.yaml

60069a5

Copilot AI review requested due to automatic review settings July 15, 2026 05:08

huimiu force-pushed the hui/fix-unified-next-steps branch from 1b997ef to 60069a5 Compare July 15, 2026 05:08

huimiu changed the base branch from main to hui/unified-config-runtime July 15, 2026 05:08

Copilot started reviewing on behalf of huimiu July 15, 2026 05:08 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

huimiu marked this pull request as draft July 15, 2026 05:23

jongio approved these changes Jul 15, 2026

View reviewed changes

		if projectpkg.ConfigContainsFileRef(svc.GetAdditionalProperties()) \|\|
		projectpkg.ConfigContainsFileRef(svc.GetConfig()) {

		ca, isHosted, found, source, err :=
		AgentDefinitionFromResolvedService(svc, projectRoot)

		for _, svc := range services {
		data := readManifestBytes(projectPath, svc.RelativePath)

		suggestion := "Run `azd provision` to create the missing " +
		"connection(s), or update their azure.yaml service names."

Uh oh!

Conversation

huimiu commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Scope

Doctor

Next-step guidance

Out of scope

Review order

Validation

Uh oh!

github-actions Bot commented Jul 10, 2026

📋 Prioritization Note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

trangevi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

huimiu commented Jul 14, 2026

Uh oh!

Copilot AI commented Jul 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

huimiu commented Jul 10, 2026 •

edited

Loading