feat(agents): add microsoft.foundry azure.yaml schema by huimiu · Pull Request #8603 · Azure/azure-dev

huimiu · 2026-06-11T04:35:45Z

Schema-only scaffolding for unifying Foundry agent config in azure.yaml. Implements design spec #8590 §2.3.

Changes

Core schema (schemas/v1.0/azure.yaml.json + schemas/alpha/azure.yaml.json):

Added microsoft.foundry to the host examples list.
Added a service-level conditional after azure.ai.agent, composing microsoft.foundry.json via allOf -> $ref and disabling project/runtime/docker/image/config.

Extension schemas (cli/azd/extensions/azure.ai.agents/schemas/) ported from therealjohn/foundry-azd-config-preview:
microsoft.foundry.json, Agent.json, Skill.json, Routine.json, Connection.json, Toolbox.json, Deployment.json, FileRef.json.

Transformations: $id rewritten to the azure-dev path; relative $refs preserved.

Deliberate deviations from preview

microsoft.foundry.json: top-level additionalProperties: true, per the PM brief and design spec §2.3, so future Foundry resource types do not break the schema.
Agent.json: PromptAgent accepts either instructions or skill, so a skill-backed prompt agent does not need duplicate instructions.
Agent.json: HostedAgent requires project when docker or runtime is set, matching its property description.
Routine.json: trigger now enforces cron for schedule and filter for webhook/event, matching its property descriptions.

Validation

All JSON files parse.
simple and complex samples validate end-to-end with ajv against the core schema plus composed sub-schemas.
Targeted negative checks confirm missing routine cron/filter and missing hosted-agent project are rejected.
cspell (misc + cli configs): 0 issues.

Fixes #8611

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

Copilot

Pull request overview

This PR adds Microsoft Foundry authoring support to azure.yaml by extending the core azure.yaml JSON Schemas to recognize host: microsoft.foundry and composing in a new set of Foundry-specific schemas owned by the azure.ai.agents extension.

Changes:

Added microsoft.foundry to the host examples list in both schemas/v1.0/azure.yaml.json and schemas/alpha/azure.yaml.json.
Added a new services.* conditional for host: microsoft.foundry that composes the Foundry schema via $ref and disables service-level properties that should not appear at the Foundry service entry level.
Added 8 new JSON Schema files under cli/azd/extensions/azure.ai.agents/schemas/ to model Foundry project/service configuration and per-resource shapes.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
schemas/v1.0/azure.yaml.json	Adds `microsoft.foundry` host example and service-level schema composition via `$ref`.
schemas/alpha/azure.yaml.json	Mirrors the v1.0 Foundry host example and conditional composition.
cli/azd/extensions/azure.ai.agents/schemas/microsoft.foundry.json	New composed Foundry project schema (service entry shape) with `additionalProperties: true`.
cli/azd/extensions/azure.ai.agents/schemas/Agent.json	New Foundry agent schema (hosted/prompt/file-ref variants).
cli/azd/extensions/azure.ai.agents/schemas/Skill.json	New Foundry skill schema (inline or file ref).
cli/azd/extensions/azure.ai.agents/schemas/Routine.json	New Foundry routine schema (inline or file ref).
cli/azd/extensions/azure.ai.agents/schemas/Connection.json	New Foundry connection schema (inline or file ref).
cli/azd/extensions/azure.ai.agents/schemas/Toolbox.json	New Foundry toolbox schema (inline or file ref).
cli/azd/extensions/azure.ai.agents/schemas/Deployment.json	New Foundry model deployment schema (inline or file ref).
cli/azd/extensions/azure.ai.agents/schemas/FileRef.json	New shared file-reference schema used by the other Foundry schemas.

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.

Require project when hosted agents define docker or runtime settings, and enforce routine trigger-specific required fields for schedule, webhook, and event triggers.

Use conditional schema constraints for hosted-agent project requirements and routine trigger-specific fields.

github-actions · 2026-06-11T19:41:23Z

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

glharper

Minor/informational notes (none blocking):

Cross-draft mix (core 2019-09, sub-schemas draft-07) matches the pre-existing azure.ai.agent.json pattern — fine.
Cosmetic $id URL-form inconsistency across new schemas vs core vs existing (no-$id) agent schema.
Schema only resolves post-merge (core $ref points at main raw URL) — same as existing behavior.
"runtime": false is a real selective guard given additionalProperties:true, not dead.

glharper · 2026-06-11T20:11:18Z

/check-enforcer override

therealjohn

This isnt ready to be merged yet - its pending more prototyping from #8590.
Can you build out the prototype in a branch so we can test it before it gets merged and released in main by accident.

…idatable samples

…content form

huimiu · 2026-06-12T07:32:38Z

@therealjohn good catch, and agreed the intent wasn''t clear from the PR description.

Current plan:

We have an integration branch huimiu/foundry-azure-yaml that acts as the prototype staging area. This PR (#8603) already targets that branch, not main. All Foundry prototype PRs (schema, $ref file includes, config binding, service target implementation, etc.) will land there first.

Only when we have a working end-to-end prototype that can be tested (azd up with a host: microsoft.foundry azure.yaml) will we open a PR from huimiu/foundry-azure-yaml to main.

I''ll also retarget PR #8627 ($ref file includes) to huimiu/foundry-azure-yaml so it''s part of the same prototype stack.

Please let me know if you have any other thoughts

huimiu · 2026-06-12T09:14:59Z

Thanks for the thorough review and the helpful notes, @glharper!

Good to know on the cross-draft mix. We're keeping it consistent with the existing azure.ai.agent.json pattern, so that feels right.
Totally agree on the $id URL form. I'll clean that up when this eventually moves to main.
Yep, same behavior as what's already there, so happy to keep it as is.
Great catch on "runtime": false being a real guard. That's intentional given additionalProperties: true on the parent.

Copilot AI review requested due to automatic review settings June 11, 2026 04:35

huimiu requested review from JeffreyCA, RickWinter, glharper, tg-msft, therealjohn, trangevi, trrwilson and vhvb1989 as code owners June 11, 2026 04:35

Copilot started reviewing on behalf of huimiu June 11, 2026 04:35 View session

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

Copilot AI reviewed Jun 11, 2026

View reviewed changes

Comment thread cli/azd/extensions/azure.ai.agents/schemas/Routine.json

Comment thread cli/azd/extensions/azure.ai.agents/schemas/Agent.json

github-actions Bot added the ext-agents azure.ai.{agents,connections,inspector,projects,routines,skills,toolboxes} extensions label Jun 11, 2026

huimiu added 3 commits June 11, 2026 13:22

fix(agents): enforce Foundry schema dependencies

fb2e096

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

8bd8bd3

Use conditional schema constraints for hosted-agent project requirements and routine trigger-specific fields.

huimiu mentioned this pull request Jun 11, 2026

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

Merged

glharper reviewed Jun 11, 2026

View reviewed changes

glharper approved these changes Jun 11, 2026

View reviewed changes

therealjohn requested changes Jun 11, 2026

View reviewed changes

huimiu changed the base branch from main to huimiu/foundry-azure-yaml June 12, 2026 05:21

feat: target foundry azure.yaml schema at integration branch with val…

250b5bf

…idatable samples

This was referenced Jun 12, 2026

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

Closed

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

Merged

fix: normalize foundry azure.yaml schema URLs to short raw.githubuser…

dac084e

…content form

huimiu mentioned this pull request Jun 12, 2026

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

Open

huimiu mentioned this pull request Jun 12, 2026

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

Draft

therealjohn approved these changes Jun 12, 2026

View reviewed changes

therealjohn merged commit a4d4c11 into huimiu/foundry-azure-yaml Jun 12, 2026
20 checks passed

huimiu deleted the huimiu/foundry-schema-scaffold branch June 12, 2026 12:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(agents): add microsoft.foundry azure.yaml schema#8603
therealjohn merged 6 commits into
huimiu/foundry-azure-yamlfrom
huimiu/foundry-schema-scaffold

huimiu commented Jun 11, 2026 •

edited by glharper

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 11, 2026

Uh oh!

glharper left a comment

Uh oh!

glharper commented Jun 11, 2026

Uh oh!

therealjohn left a comment

Uh oh!

huimiu commented Jun 12, 2026 •

edited

Loading

Uh oh!

huimiu commented Jun 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

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

Uh oh!

Changes

Deliberate deviations from preview

Validation

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!

github-actions Bot commented Jun 11, 2026

📋 Prioritization Note

Uh oh!

glharper left a comment

Choose a reason for hiding this comment

Uh oh!

glharper commented Jun 11, 2026

Uh oh!

therealjohn left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

huimiu commented Jun 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

huimiu commented Jun 11, 2026 •

edited by glharper

Loading

huimiu commented Jun 12, 2026 •

edited

Loading