docs: technical design spec for unifying Foundry config in azure.yaml#8590
Open
huimiu wants to merge 14 commits into
Open
docs: technical design spec for unifying Foundry config in azure.yaml#8590huimiu wants to merge 14 commits into
huimiu wants to merge 14 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).
Member
|
I'm not seeing a new skill added for design-spec. |
🔗 Linked Issue RequiredThanks for the contribution! Please link a GitHub issue to this PR by adding |
Member
Author
@glharper Sorry, wrong content removed |
This was referenced Jun 11, 2026
therealjohn
approved these changes
Jun 11, 2026
… templating in the unify-azure-yaml spec
…e unify-azure-yaml spec
…B) in the unify-azure-yaml spec
This was referenced Jun 12, 2026
Member
Author
|
Thanks for the review!
|
This was referenced Jun 12, 2026
therealjohn
pushed a commit
that referenced
this pull request
Jun 12, 2026
* feat(agents): add microsoft.foundry azure.yaml schema Schema-only scaffolding for unifying Microsoft Foundry agent config in azure.yaml (design spec PR #8590, section 2.3). - Add the host: microsoft.foundry conditional to schemas/v1.0 and schemas/alpha azure.yaml.json, composing the extension schema at the service level via allOf and turning off project/runtime/docker/image/config. - Add microsoft.foundry to the host examples list. - Publish the Foundry extension schemas under cli/azd/extensions/azure.ai.agents/schemas/: microsoft.foundry.json plus per-resource files (Agent, Skill, Routine, Connection, Toolbox, Deployment, FileRef), ported from the PM preview repo with $id rewritten to the azure-dev path and relative $refs preserved. - microsoft.foundry.json uses additionalProperties: true at the project level (deliberate deviation from the preview's false) so future Foundry resource types do not break the schema, per the brief and design spec section 2.3. Authoring-only: no service-target wiring, provider registration, or alpha-feature gating (those are later PRs). * fix(agents): relax PromptAgent to accept skill without instructions PromptAgent now requires name + kind plus at least one of instructions or skill (anyOf), instead of always requiring instructions. A prompt agent backed by a skill (which supplies the instructions) no longer fails schema validation. This fixes the complex sample's summarizer-agent validation failure. * fix(agents): enforce Foundry schema dependencies Require project when hosted agents define docker or runtime settings, and enforce routine trigger-specific required fields for schedule, webhook, and event triggers. * fix(agents): align Foundry schema constraints Use conditional schema constraints for hosted-agent project requirements and routine trigger-specific fields. * feat: target foundry azure.yaml schema at integration branch with validatable samples * fix: normalize foundry azure.yaml schema URLs to short raw.githubusercontent form
therealjohn
approved these changes
Jun 12, 2026
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.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.