doc: design unified azure yaml guidance#9082
Open
huimiu wants to merge 5 commits into
Open
Conversation
huimiu
requested review from
JeffreyCA,
RickWinter,
hemarina and
tg-msft
as code owners
huimiu
changed the title
🔗 Linked Issue RequiredThanks for the contribution! Please link a GitHub issue to this PR by adding |
Contributor
There was a problem hiding this comment.
Pull request overview
Defines the proposed unified azure.yaml agent configuration and post-command guidance design.
Changes:
- Establishes unified configuration precedence and legacy fallback.
- Proposes core-rendered next-step guidance.
- Records unresolved product decisions.
|
|
||
| ## Context and scope | ||
|
|
||
| This design aligns the end-to-end CLI experience for the configuration migration in [issue #8710](https://github.com/Azure/azure-dev/issues/8710) and the local-first guidance from [issue #7975](https://github.com/Azure/azure-dev/issues/7975). It covers the Azure AI Agents extension's configuration readers, next-step guidance, doctor checks, and the core contribution contract. Foundry provisioning, agent deployment, and manifest content are unchanged. |
|
|
||
| ### Core-rendered guidance | ||
|
|
||
| Core accepts one project-scoped post-command contribution with a stable identity. Post-provision writes or updates that contribution after refreshing state. Project post-deploy recomputes and replaces it, so `azd up` renders only the final post-deploy guidance. Service postdeploy handlers do not contribute user guidance. |
|
|
||
| The contribution is structured rather than direct stdout. Core renders it once after the command result and applies output-mode suppression. Contribution assembly failures remain diagnostic and do not change a successful command result. | ||
|
|
||
| Malformed unified configuration produces a service-scoped validation or doctor error instead of an empty state. Legacy fallback keeps the single warning path in `project.WarnLegacyAgentShape`. |
jongio
approved these changes
Jul 13, 2026
jongio
left a comment
jongio
left a comment
Member
There was a problem hiding this comment.
Design spec reads clearly and is internally consistent. The deferred contract details and open decisions are explicitly scoped in the doc, so the direction is sound to proceed.
|
|
||
| ### Unified state and attribution | ||
|
|
||
| `nextstep.AssembleState` reads the parsed service graph first and falls back to legacy agent files only when unified configuration is unavailable. Doctor consumes the same state snapshot. Both continue classifying unresolved infrastructure variables by matching Bicep outputs, consistent with [issue #7975](https://github.com/Azure/azure-dev/issues/7975) and [PR #9081](https://github.com/Azure/azure-dev/pull/9081). |
JeffreyCA
added
ext-agents
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
azure.yaml.Details
The spec covers the unified
azure.yamlconfiguration readers, local-first next-step guidance, and doctor checks, plus the core-rendered post-command guidance contract. It preserves the legacyagent.yaml/agent.manifest.yamlfallback and migration warning during the compatibility window.It records two decisions for John: whether the core post-command contribution contract is in this milestone, and whether top-level post-deploy guidance replaces the workflow guidance in endpoint artifact notes.
Relates to #8710, #7975, and #8804.