docs(spec): Bicep-less Foundry agent init design (#8065)

[hund030]

Design spec for RFC #8065 — make azd ai agent init Bicep-less by default, with the azure.ai.agents extension owning provisioning via a custom provider named microsoft.foundry.

Summary

Moves infrastructure templates from Azure-Samples/azd-ai-starter-basic into the azure.ai.agents extension binary. azd ai agent init produces only azure.yaml and an agent code project — no infra/ directory. At azd provision time, the extension's own provisioning provider synthesizes Bicep in memory from azure.yaml and applies it. azd ai agent init --infra ejects on demand: same synthesis, written to ./infra/; subsequent provisions read from disk.

The azure.yaml shape is fixed by the Foundry azure.yaml reference: a single host: microsoft.foundry service per project, with nested agents:, deployments:, connections:, etc. This spec only changes how that file is provisioned; it does not redesign the YAML.

Key design decisions

• host: microsoft.foundry — one consolidated service per Foundry project, with nested agents[], deployments[], connections[], toolboxes[], skills[], routines[]. Matches the reference doc.
• infra.provider: microsoft.foundry — explicit declaration required until service-host-driven auto-routing lands. Reuses the custom provisioning provider framework from feat: Add provisioning provider support to extension framework #7482 (merged).
• Brownfield via endpoint: URL — not ARM resource ID. Matches what Portal and az CLI show; deploy verb resolves ARM ID from endpoint when it needs control-plane access.
• Three deploy modes per agent: docker:, runtime:, or image: (pre-built container). Exactly one is required; validator rejects two-or-none.
• On-disk reuse after eject: extension reads ./infra/ when present, synthesizes otherwise. azure.yaml is never mutated by eject.
• No --force flag for eject. To regenerate, the user deletes ./infra/ and re-runs the command.
• Preview via ARM What-If — mirrors Core's Bicep provider (scope.go:132 uses WhatIfDeployToResourceGroup).

Scope

In scope: Bicep-less default behavior, eject command, embedded templates, ARM-backed synthesis only (Foundry project + model deployments + ACR when needed), schema relaxation to allow extension-named providers in infra.provider.

Out of scope:

• azd deploy — agent code push and data-plane reconciliation (connections, toolboxes, skills, routines, agent definitions) are deploy's job, not provisioning's. This spec ends at "ARM resources are in place."
• Data-plane YAML fields — connections:, toolboxes:, skills:, routines:, agent-level tools:/skill:, $ref: resolution. Synthesizer reads them only to skip them; deploy verb owns them.
• Service-host-driven auto-routing (RFC Core Ask 1) — would remove the explicit infra.provider:. Defers to a future spec.
• Unified azure.yaml schema (Unify Foundry agent configuration in azure.yaml #7962); incremental composition (Add connections, models, tools, and skills to Foundry Agent projects after init #8049); coexistence with non-Foundry services (use infra.layers[] as escape hatch).

Core changes collapsed. The original RFC asked Core to surface services.<svc>.uses and a typed services.<svc>.runtime on the extension-facing proto. With nested agents[], runtime lives inside the service body (read via additional_properties); no proto/struct/mapper plumbing needed. Down to one Core change: relax the infra.provider enum.

Related

• RFC: Make azd ai agent init Bicep-less by default; add --infra to eject #8065
• Builds on: feat: Add provisioning provider support to extension framework #7482 (custom provisioning provider framework, merged)
• Reference YAML: therealjohn/foundry-azd-config-preview

Notes for reviewers

Doc-only PR. Adds docs/specs/bicepless-foundry/spec.md. No code changes — the spec is the implementation contract; code PRs follow.

Particular attention welcomed on:

1. The "What the synthesizer ignores" table — is the data-plane / ARM split drawn at the right line?
2. The Open Question and its proposed answer (drift detection on Deploy()).
3. The eject "delete-and-rerun" model with no --force flag — does this match azd's broader UX posture?

[github-actions]

🔗 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!

[Copilot]

Pull request overview

Adds a new design spec documenting the proposed “Bicep-less by default” experience for azd ai agent init, where the azure.ai.agents extension owns provisioning via a custom provisioning provider and can optionally “eject” generated Bicep to ./infra/.

Changes:

• Introduces a detailed design spec for extension-owned provisioning + in-memory Bicep synthesis.
• Defines activation/eject behavior, validation pipeline, and post-eject drift/UX expectations.
• Outlines required (future) Core schema/proto surfacing for uses and a service-level runtime.

[glharper]

Spec review

Strong, well-grounded spec. I verified the code citations against main and they''re all accurate: ParseProvider pass-through (provisioning.go:53-57), provider resolution unchanged (manager.go:505-540), detectProviderFromFiles gated on NotSpecified (importer.go:304), ProjectInfrastructure never inspecting service.Host (importer.go:292-358), the azdext.ProvisioningProvider interface methods (:23-36) matching the method table, schema enum at azure.yaml.json:44-52, and registration parity between default.go:81-86 and provisioning_service.go:138-152. Implementation-ready.

The three questions you flagged

1. Is the data-plane/ARM split in "What the synthesizer ignores" drawn correctly?
Mostly, but there''s an internal inconsistency. The table lists agents[].runtime: as ignored ("deploy verb''s job"), yet Validation step 3 requires the synthesizer to read docker:/runtime:/image: to enforce the exactly-one deploy-mode invariant, and docker:->ACR / image:->no-ACR are explicitly read for branching. So those three aren''t "ignored" - they''re read for validation and ARM branching but emit no ARM of their own. Suggest splitting the table into read-for-branching-but-no-ARM (docker, image, runtime) vs not-read-at-all (connections, toolboxes, skills, routines, tools, skill, protocols, env, startupCommand). As written the table contradicts the validation section.

2. Drift detection on Deploy() - is "no detection" right?
This is the weakest part of the proposal. The justification ("CLI add commands already warn at the entry point") only covers mutations made through azd commands. A user hand-editing azure.yaml (e.g. adding a second container agent -> needs ACR) bypasses every add warning, then azd provision reads stale on-disk Bicep, silently skips the ACR, and the failure surfaces much later in azd deploy (docker push) with a confusing error. A cheap, non-invasive guard at Deploy() - diff the set of ARM-relevant fields in azure.yaml against what the on-disk template declares, and warn (not block) - would catch this without re-introducing auto-merge. I''d push back on "no detection" and at least make it a one-line warn.

3. Eject delete-and-rerun with no --force?
Refusing to clobber user-owned files matches azd''s posture. But a hard refuse is slightly more friction than azd''s usual style - azd typically prompts on overwrite rather than erroring out. Consider an interactive confirm ("./infra/ exists, regenerate and overwrite? [y/N]") with the hard-refuse behavior preserved under --no-prompt/CI. Keeps the safety while feeling more native. The all-or-nothing scope is right.

Other findings

• Destroy is under-specified and risks a real bug. "Delete resource group or use deployment stacks" omits soft-delete purge. Foundry/Cognitive Services accounts (and any Key Vault) are soft-delete-protected; Core''s Bicep provider handles purge. Without it, up->down->up under the same name fails on the second provision. Should be called out so the extension''s Destroy matches Core parity.

• Schema relaxation loses typo-catching. Changing enum: ["bicep","terraform"] -> examples means provider: biceps is no longer flagged in IDE validation for anyone, not just Foundry users. Since extension provider names are open-ended an enum can''t enumerate them - but consider a pattern (e.g. ^[a-z0-9.]+$) alongside examples to retain some validation, or note the accepted regression explicitly.

• Brownfield + Preview (What-If) needs scope resolution too. The spec says ARM-ID-from-endpoint: resolution is deploy-time, but What-If also needs the target scope (RG/subscription). Confirm Preview resolves endpoint->scope, not just Deploy.

• Telemetry doc requirement. Per repo convention (cli/azd/AGENTS.md), new fields (provision.synthesis_source, init.infra_flag) must be added to docs/reference/telemetry-data.md. Worth naming this file as a required deliverable in the implementation PRs.

• infra.layers[] escape-hatch is asserted but unverified. The coexistence story relies on per-layer provider scoping, but importer.go:316 short-circuits on len(Layers) > 0 and the spec doesn''t confirm an InfraLayer can name an extension provider. Worth a one-line verification since it''s the only mixed-project answer.

• Minor: Stability Contract ("semantically identical") vs Test Plan ("byte-equal output") - clarify byte-equal is per extension version. And the infra.provider: line added by init becomes dead once auto-routing lands; note a cleanup path.

[hund030]

@glharper Thanks for the careful review — all 8 points hold up and have been applied to the spec:

1. Synthesizer ignores table — split into "read for branching" (docker/runtime/image) and "not read at all" (everything else). runtime was the only contradiction; docker/image weren't actually in the table.
2. Drift detection — Open Question 1 flipped to warn (don't block) on every on-disk Deploy(). Pseudocode and method-table row updated.
3. Eject UX — now matches azd infra generate: interactive [y/N] prompt, --no-prompt keeps the hard-refuse for CI.
4. Destroy soft-delete purge — row updated to mirror Core's getCognitiveAccountsToPurge + purgeItems (bicep_provider.go:1283-1413); up → down → up failure mode called out.
5. Schema typo regression — pattern: ^[a-z0-9.]+$ + examples instead of examples alone.
6. Brownfield + Preview scope — both Deploy and Preview now resolve endpoint: to ARM ID + scope before invoking ARM.
7. Telemetry doc requirement — one-line callout naming docs/reference/telemetry-data.md per cli/azd/AGENTS.md:246-249.
8. infra.layers[] escape hatch — verified inline: InfraLayer.Provider (provider.go:57 → :40) + ParseProvider accepts any string.
9. Stability vs Test Plan wording — tightened to byte-stable within a patch extension version, matching the test.

[hund030]

Thanks for the careful review — all 8 points hold up and have been applied to the spec:

1. Synthesizer ignores table — split into "read for branching" (docker/runtime/image) and "not read at all" (everything else). runtime was the only contradiction; docker/image weren't actually in the table.
2. Drift detection — Open Question 1 flipped to warn (don't block) on every on-disk Deploy(). Pseudocode and method-table row updated.
3. Eject UX — now matches azd infra generate: interactive [y/N] prompt, --no-prompt keeps the hard-refuse for CI.
4. Destroy soft-delete purge — row updated to mirror Core's getCognitiveAccountsToPurge + purgeItems (bicep_provider.go:1283-1413); up → down → up failure mode called out.
5. Schema typo regression — pattern: ^[a-z0-9.]+$ + examples instead of examples alone.
6. Brownfield + Preview scope — both Deploy and Preview now resolve endpoint: to ARM ID + scope before invoking ARM.
7. Telemetry doc requirement — one-line callout naming docs/reference/telemetry-data.md per cli/azd/AGENTS.md:246-249.
8. infra.layers[] escape hatch — verified inline: InfraLayer.Provider (provider.go:57 → :40) + ParseProvider accepts any string.
9. Stability vs Test Plan wording — tightened to byte-stable within a patch extension version, matching the test.

Test Plan also picked up entries for each new behavior. Pushing the commit shortly.