docs: technical design spec for unifying Foundry config in azure.yaml#8590
Open
huimiu wants to merge 11 commits into
Open
docs: technical design spec for unifying Foundry config in azure.yaml#8590huimiu wants to merge 11 commits into
huimiu wants to merge 11 commits into
Conversation
…yaml Engineering design that backs the unified azure.yaml product brief. Covers the end to end command experience and the technical design (schema composition, config binding, the microsoft.foundry service target, ref includes, templating, init rework, reconciliation), plus a provision dependency callout and new open questions.
huimiu
requested review from
JeffreyCA,
RickWinter,
hemarina,
tg-msft and
vhvb1989
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an engineering technical design spec documenting the proposed unified azure.yaml shape and lifecycle for Foundry projects/agents, including schema composition, config binding, $ref includes, templating, lifecycle fan-out, migration/deprecation, and open questions. This lives under docs/specs/ and introduces no product code changes.
Changes:
- Add a new design spec at
docs/specs/unify-azure-yaml/spec.mdcovering end-to-end CLI flows and detailed technical design. - Document proposed schema composition for
host: microsoft.foundryand extension wiring/rollout considerations. - Define
$refinclude/overlay behavior, templating coexistence (${VAR}vs${{...}}), and reconciliation/idempotency approach.
📋 Prioritization NoteThanks for the contribution! The linked issue isn't in the current milestone yet. |
huimiu
force-pushed
the
hui/unify-azure-yaml
branch
from
e1dc707 to
f38e2d4
Compare
Align $ref path handling with FileRef.json (accept absolute paths and URLs), document path rebasing and instruction/prompt file loading, model agent-level tools, scope deploy-mode validation to hosted agents, order routine reconciliation after agents, add a sibling-extension schema-ownership section (Option A), and merge Parts 3 and 4 into a single flat Open questions section. Trim the summary to deltas on the brief.
Remove the built-in Bicep, idempotency, and per-agent CLI items from the open questions list, since the brief raises each with a recommended option (opt-in in-memory Bicep, Bicep-like reconciliation semantics, and 3a per-agent build). Fold the #8349/#8350 references into the 2.8 reconciliation section and note where the brief leaves instructions-format and routines open.
John's brief already raises skill instructions format (open question 5) and routines ownership and triggers (open question 6). The instructions item also contradicted section 2.4, which already decides both inline and file forms. Remove both echoes; open questions now list only items this design adds.
FileRef.json states absolute paths and URLs are accepted and that sibling properties act as overlay overrides, and the brief recommends Option A (azure.ai.agents owns schema and reconciliation). That settles ref ownership, overlay rules, and absolute/remote paths, so remove both from open questions and fold the accepted-paths decision into section 2.4. Open questions now list only items the brief leaves open.
Issue 8587's preferred fix is deploy-time reconciliation of toolboxes and connections, which the design already does (folded into 2.8). Issue 8165's stated minimum, reusing an existing account, is the endpoint design (folded into 1.4). Split-file validation is already decided in 2.4. Remove all three from open questions, leaving only items with no settled direction: agent versioning (8066), gRPC config size, and composition surface naming (8049).
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.yamlatdocs/specs/unify-azure-yaml/spec.mddesign-specworkflow skill at.github/skills/design-spec/SKILL.mdDetails
Design spec (
docs/specs/unify-azure-yaml/spec.md)The spec is the engineering counterpart to the product brief. It covers two areas the brief does not address:
azd ai agent init,provision,deploy,up, andazd down; a Foundry service next to a normal service viauses:; connecting to an existing project viaendpoint:; migration fromhost: azure.ai.agentand separateagent.yaml/agent.manifest.yamlfiles; partial deploy failure and safe re-run behavior.AdditionalPropertiesand gRPC, wiringhost: microsoft.foundryto a new service target, JSON Schema composition at the service level,$reffile includes and overlay overrides,${VAR}vs${{...}}templating, service target lifecycle with per-agent fan-out,initrework, state reconciliation, sibling-extension schema ownership, and telemetry and errors.Also includes a consolidated Open questions section covering provision-experience dependencies for PM confirmation alongside design questions specific to this work.
design-spec skill (
.github/skills/design-spec/SKILL.md)A reusable workflow skill that encodes the full process used to produce the spec above. Covers: clarifying inputs, reading repo conventions, researching the PM brief and related issues, exploring relevant code, writing the spec, self-review checklist, cspell, commit/push, and opening a PR with the correct
## Summary/## Detailsformat.Closes #7962 (partial, spec milestone)