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

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

Summary

Read inline agent definitions, typed env values, split Foundry resources, and local $ref files from unified azure.yaml while retaining legacy config and sidecar fallbacks.
Keep next-step guidance and doctor checks consistent with provision/deploy ownership, and fail diagnostics when resource state is incomplete.
Apply the same effective config to local run, agent deployment, brownfield provisioning, and split connection/toolbox service targets.

Testing

go build ./... and go test ./... -count=1 in azure.ai.agents, azure.ai.connections, and azure.ai.toolboxes
golangci-lint run ./... in all three extensions
cspell checks for Go and Markdown files in all three extensions

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

+@description('Foundry project connections to create (host: azure.ai.connection services).')
+param connections connectionsType = []


+@description('Foundry project connections to create on the existing project (host: azure.ai.connection services).')
+param connections connectionsType = []


+	Category    string            `yaml:"category,omitempty"`
+	Target      string            `yaml:"target,omitempty"`
+	AuthType    string            `yaml:"authType,omitempty"`
+	Credentials map[string]any    `yaml:"credentials,omitempty"`
+	Metadata    map[string]string `yaml:"metadata,omitempty"`


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 45 out of 46 changed files in this pull request and generated 8 comments.

jongio

The rebase cleaned this up, and my earlier blocking concerns are resolved:

The branch no longer carries the #9042 registry-check tooling or the other in-flight commits it had picked up. It is down to 2 commits / 46 files, all under cli/azd/extensions/.
The connection bicep templates that stored resolved credentials in a plain (non-@secure()) ARM array param are no longer in this diff, so the deployment-history exposure I raised earlier is out of scope here.
The $ref pinning is handled now: persistBuildService writes the resolved path for the build, then the deferred combineBuildServiceRestore writes the original $ref config back after Package, and file-ref services no longer persist resolved container settings in prepareContainerSettings.

The three open items from the latest automated pass still hold. I checked them against the current HEAD: the ${{...}} env values getting pre-expanded by core in the helpers/deploy paths, ProjectRoot not reaching collectConnections so split-connection $ref files stay unresolved, and the env decode rejecting non-string YAML scalars in config.go. Those are already captured, so I am not repeating them inline.

One net-new item below.

Copilot

Pull request overview

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

Copilot

Pull request overview

Copilot reviewed 42 out of 42 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 {


+	resolved, err := foundry.ResolveFileRefs(
+		props.AsMap(),
+		projectRoot,
+	)


+func agentEnvironmentValues(
+	agentDef guidanceAgentDefinition,
+	cfg *guidanceServiceConfig,
+) []string {
+	var values []string
+	if agentDef.EnvironmentVariables != nil {
+		for _, envVar := range *agentDef.EnvironmentVariables {
+			values = append(values, envVar.Value)
+		}
+	}
+	if cfg != nil {
+		for _, key := range slices.Sorted(maps.Keys(cfg.Environment)) {
+			values = append(values, cfg.Environment[key])
+		}
+	}
+	return values
+}


Copilot

Pull request overview

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

+		ca, isHosted, err := agentDefinitionFromStruct(
+			resolved,
+			image,
+		)


+		if err := unmarshalServiceProps(
+			props,
+			&candidateCfg,
+		); err != nil {


+		definitions, err := agent_yaml.ExtractResourceDefinitions(data)
 		if err != nil {
+			appendResourceLoadError(
+				errs,
+				resources,
+				svc.Name,
+				err,


 	// Placeholder fix-ups always come first when present: they are broken
 	// state in azure.yaml itself and block both `run` and `deploy`. The
-	// user has to edit azure.yaml (or define a matching parameter in
-	// agent.manifest.yaml) — `azd env set` cannot reach them.
+	// user has to edit azure.yaml; `azd env set` cannot reach them.


Copilot

Pull request overview

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

+	resolved, err := foundry.ResolveFileRefs(
+		props.AsMap(),
+		projectRoot,
+	)


+		if err := unmarshalServiceProps(
+			props,
+			&candidateCfg,
+		); err != nil {
+			return agentDef, cfg, props, err


+				if !isHosted {
+					failures = append(
+						failures,
+						fmt.Sprintf(
+							"%s: unsupported agent kind",
+							svc.GetName(),
+						),
+					)


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


 	// Placeholder fix-ups always come first when present: they are broken
 	// state in azure.yaml itself and block both `run` and `deploy`. The
-	// user has to edit azure.yaml (or define a matching parameter in
-	// agent.manifest.yaml) — `azd env set` cannot reach them.
+	// user has to edit azure.yaml; `azd env set` cannot reach them.


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

fix: align agent workflows with unified azure.yaml

77c0cb2

fix: preserve referenced agent service fields

5689831

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

huimiu force-pushed the hui/fix-unified-next-steps branch from 4b33245 to 5689831 Compare July 14, 2026 02:26

Copilot started reviewing on behalf of huimiu July 14, 2026 02:27 View session

github-actions Bot added the area/extensions Extensions (general) label Jul 14, 2026

Copilot AI reviewed Jul 14, 2026

View reviewed changes

jongio reviewed Jul 14, 2026

View reviewed changes

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

fix: preserve raw config and provision connections

fdb53b9

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

Copilot started reviewing on behalf of huimiu July 14, 2026 02:58 View session

fix: clone service configs before resolution

c41a7a8

Copilot AI reviewed Jul 14, 2026

View reviewed changes

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

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

Copilot AI reviewed Jul 14, 2026

View reviewed changes

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

fix: complete unified configuration checks

6bd9914

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

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

fix: remove rootless endpoint resolution

9a62a7f

Copilot AI reviewed Jul 14, 2026

View reviewed changes

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

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

Copilot AI reviewed Jul 14, 2026

View reviewed changes

huimiu added 2 commits July 14, 2026 12:48

fix: apply container defaults for referenced agents

c23161e

fix: reject referenced agents in optimize apply

e0e8170

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

		@description('Foundry project connections to create (host: azure.ai.connection services).')
		param connections connectionsType = []

Uh oh!

Conversation

huimiu commented Jul 10, 2026

Summary

Testing

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!

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!

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

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!

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

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!