docs: technical design spec for unifying Foundry config in azure.yaml by huimiu · Pull Request #8590 · Azure/azure-dev

huimiu · 2026-06-10T05:27:27Z

Summary

Add technical design spec for unifying Foundry agent configuration in azure.yaml at docs/specs/unify-azure-yaml/spec.md
Docs only, no product code changes

Details

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:

End to end experience: command flows for azd ai agent init, provision, deploy, up, and azd down; a Foundry service next to a normal service via uses:; connecting to an existing project via endpoint:; migration from host: azure.ai.agent and separate agent.yaml / agent.manifest.yaml files; partial deploy failure and safe re-run behavior.
Technical design: config binding through AdditionalProperties and gRPC, wiring host: microsoft.foundry to a new service target, JSON Schema composition at the service level, $ref file includes and overlay overrides, ${VAR} vs ${{...}} templating, service target lifecycle with per-agent fan-out, init rework, state reconciliation, sibling-extension schema ownership, and telemetry and errors.

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

Copilot

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.md covering end-to-end CLI flows and detailed technical design.
Document proposed schema composition for host: microsoft.foundry and extension wiring/rollout considerations.
Define $ref include/overlay behavior, templating coexistence (${VAR} vs ${{...}}), and reconciliation/idempotency approach.

github-actions · 2026-06-10T05:33:01Z

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Review may take a bit longer — reach out to @rajeshkamal5050 or @kristenwomack if you'd like to discuss prioritization.

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

glharper · 2026-06-10T15:47:09Z

I'm not seeing a new skill added for design-spec.

github-actions · 2026-06-11T02:51:07Z

🔗 Linked Issue Required

Thanks for the contribution! Please link a GitHub issue to this PR by adding Fixes #123 to the description or using the sidebar.
No issue yet? Feel free to create one!

huimiu · 2026-06-11T02:51:51Z

I'm not seeing a new skill added for design-spec.

@glharper Sorry, wrong content removed

therealjohn · 2026-06-11T15:28:11Z

+creating one. This is the path for teams that provision infrastructure on their own, and
+for reusing a shared or private network bound account, which is the minimum issue
+[#8165](https://github.com/Azure/azure-dev/issues/8165) asks for. Provisioning a new
+network bound account from scratch is part of the separate built-in Bicep work, not this


I understand why this is this way - just making a note that we will need to ensure there is a path to create and customize network settings in the bicep work.

What we are saying here is that in order to do that, you'd need to immediately eject to Bicep and customize it to get VNET settings, etc.

We don't expose the Account resource as a service here, and the network settings are on the account not the Foundry Project.

therealjohn · 2026-06-11T15:29:53Z

+explicit and runs through `azd down` or the per resource `azd ai` commands.
+
+`azd down` removes the Foundry project that azd provisioned. If the service used an
+`endpoint:` to point at an existing project, `azd down` does not delete that project,


This is correct - and I think AZD down might already have logic for this so we may not need to build anything custom, but double-check.

therealjohn · 2026-06-11T17:36:35Z

+
+- `${VAR}` is an azd environment value, resolved on the client before anything is sent
+  to Foundry. Example: a connection secret read from the azd environment.
+- `${{...}}` is resolved by Foundry on the server, for example


This is just treated as a string value, no resolution needed. Its a special syntax for Foundry.

therealjohn · 2026-06-11T17:43:04Z

+
+### 2.8 State reconciliation and idempotency
+
+Deploy compares the declared state in `azure.yaml` against the live state in Foundry and


I dont expect the extensions to query state and do a compare - that seems very complex to manage.

Instead, I expected we could just do a CreateOrUpdate type API call and the service would handle it.

therealjohn · 2026-06-11T17:43:58Z

+Following the brief, v1 takes **Option A**: the `azure.ai.agents` extension owns the full
+schema and reconciles every slice (deployments, connections, toolboxes, skills, routines,
+agents), while the sibling extensions keep their imperative CLIs unchanged. The
+alternative, Option B, has the meta-package own the schema and each sibling register a


Now that we have the meta package, it makes sense to me it would live there but confirm that doesnt have other consequences.

… templating in the unify-azure-yaml spec

…e unify-azure-yaml spec

…B) in the unify-azure-yaml spec

huimiu · 2026-06-12T06:04:14Z

Thanks for the review! Here's what got updated based on your feedback:

Network settings — Noted that VNET config is on the Foundry Account, not the Project. azd doesn't manage the Account, so you'd need to eject to Bicep today. The Bicep work needs to cover this path.
azd down — Added a note that the existing teardown logic likely already handles this — just needs a confirm.
${{...}} — Clarified that azd never resolves this; it's passed through as-is to Foundry.
State reconciliation (§2.8) — Switched to idempotent CreateOrUpdate, letting Foundry handle it server-side instead of diffing on the client.
Schema ownership (§2.10) — Flipped to Option B: microsoft.foundry meta-package owns the schema, each sibling extension contributes its slice. Reconciliation stays in azure.ai.agents. Core will need a new slice contribution mechanism.

Copilot AI review requested due to automatic review settings June 10, 2026 05:27

huimiu requested review from JeffreyCA, RickWinter, hemarina, tg-msft and vhvb1989 as code owners June 10, 2026 05:27

Copilot started reviewing on behalf of huimiu June 10, 2026 05:27 View session

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

docs: remove external username reference from spec

f38e2d4

Copilot AI reviewed Jun 10, 2026

View reviewed changes

Comment thread docs/specs/unify-azure-yaml/spec.md Outdated

Comment thread docs/specs/unify-azure-yaml/spec.md Outdated

Comment thread docs/specs/unify-azure-yaml/spec.md

Comment thread docs/specs/unify-azure-yaml/spec.md Outdated

huimiu requested a review from danieljurek as a code owner June 10, 2026 05:48

huimiu force-pushed the hui/unify-azure-yaml branch from e1dc707 to f38e2d4 Compare June 10, 2026 05:51

huimiu removed the request for review from danieljurek June 10, 2026 05:52

huimiu added 9 commits June 10, 2026 14:11

docs: fix review comments on unify-azure-yaml spec

1df8039

docs: revise overview to focus on what the spec provides

393252b

docs: simplify open questions intro to a plain lead-in

02df33f

docs: warmer, more collaborative tone for open questions

ef2d119

This was referenced Jun 11, 2026

feat(agents): support Foundry ${{...}} server-side expressions in env expansion #8602

Merged

feat(agents): add microsoft.foundry azure.yaml schema #8603

Open

antriksh30 mentioned this pull request Jun 11, 2026

[WIP][not-for-review] azure.ai.agents: revamp next-step + doctor for unified azure.yaml #8605

Draft

therealjohn approved these changes Jun 11, 2026

View reviewed changes

huimiu added 3 commits June 12, 2026 12:53

docs: address review notes on network settings, azd down, and Foundry…

fd2b026

… templating in the unify-azure-yaml spec

docs: switch state reconciliation to server-side CreateOrUpdate in th…

2889da1

…e unify-azure-yaml spec

docs: make the microsoft.foundry meta-package own the schema (Option …

f375511

…B) in the unify-azure-yaml spec

This was referenced Jun 12, 2026

Resolve $ref file includes with overlay overrides in Foundry config #8626

Open

feat(agents): resolve $ref file includes with overlay overrides in Foundry config #8627

Open

This was referenced Jun 12, 2026

[ext-agents] Add microsoft.foundry service target (foundation: single hosted agent) #8628

Open

feat(agents): add microsoft.foundry service target for a single hosted agent #8629

Draft


		### 2.8 State reconciliation and idempotency

		Deploy compares the declared state in `azure.yaml` against the live state in Foundry and

Conversation

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

Uh oh!

Summary

Details

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!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Prioritization Note

Uh oh!

glharper commented Jun 10, 2026

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked Issue Required

Uh oh!

huimiu commented Jun 11, 2026

Uh oh!

therealjohn Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

therealjohn Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

therealjohn Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

therealjohn Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

therealjohn Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

huimiu commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

huimiu commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading