docs: unify Foundry agent configuration in azure.yaml

[huimiu]

What

Adds docs/architecture/adr-unify-foundry-agent-config.md — the architecture decision record for #7962: Unify Foundry agent configuration in azure.yaml.

Also adds five illustrative azure.yaml examples (under docs/architecture/azure-yaml-examples/) that capture the proposed end-state schema, one file per scenario.

---

Why (context)

The azure.ai.agents extension currently spreads a hosted Foundry agent across three files: azure.yaml, agent.yaml, and agent.manifest.yaml. This causes:

• Duplicate data — agent name, model deployment name, and container resources all appear in multiple places with two overlapping templating syntaxes.
• Scope conflation — services.<agent>.config mixes agent-scoped concerns with project-scoped resources (model deployments, connections, toolboxes).
• No cross-agent sharing — project-scoped resources are nested under a single agent; a second agent that shares a toolbox must redeclare it.
• Divergent tooling — Foundry Toolkit for VS Code parses agent.yaml directly while azd ai agent works off an AgentManifest.

---

What the ADR records

Decisions (locked)

#	Decision
1	host: azure.ai.agent owns agent-runtime config only (kind, container.resources, env, startupCommand, etc.)
2	host: azure.ai.project (new) owns all project-scoped Foundry data-plane state (toolboxes, connections, deployments)
3	Agents reference the project via the existing uses: field — no new dependsOn, no core schema change
4	Container mode reuses the existing docker: block; existing images use the existing image: field
5	Code-deploy mode uses a typed runtime: { stack, version } block
6	Deploy source is explicit and exactly one of image: / docker: / runtime: — validation error otherwise
7	container.resources (cpu/memory) applies to every deploy mode
8	${VAR} expansion in config: is performed by the extension (core does not expand config:)
9	init populates config: and stops emitting agent.yaml / agent.manifest.yaml (deprecation window kept)

Phasing (locked)

• Phase 1 — Consolidate files. Retire agent.yaml / agent.manifest.yaml, introduce host: azure.ai.project. No mandatory azd core change.
• Phase 2 — Bicep-less provisioning (in-memory ARM generation, opt-in eject). Gated on a separate RFC.

Open questions (to resolve before locking the schema)

1. Provision vs. deploy inventory — what does azure.ai.project Deploy create vs. what stays in Bicep? (model deployments and connections are ambiguous)
2. Idempotency and state — diff vs. recreate on repeated azd deploy; how are removals handled? (relates to #8350, #8349)
3. Error recovery — partial-failure story when azure.ai.project Deploy fails partway through the uses chain
4. Service-level runtime: typing — AdditionalProperties (untyped) vs. promoting runtime to a first-class ServiceConfig field in core

Example scenarios

Scenario	File	Deploy source
New project, zip/code-deploy	code-deploy.yaml	runtime:
New project, build from Dockerfile	container-build.yaml	docker:
New project, pre-built image (ACR)	existing-image.yaml	image:
Existing project, reuse existing model	brownfield-existing-model.yaml	runtime:
Existing project, create new model	brownfield-new-model.yaml	runtime:

---

Notes

• Docs-only change — no build, lint, or test impact.
• Status is Proposed — opened as draft to gather review on the Decision section and the 4 open questions before marking Accepted.

Refs #7962

[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 an Architecture Decision Record (ADR) proposing a unified, azure.yaml-only configuration model for Foundry agent projects, along with illustrative end-state azure.yaml examples that demonstrate the proposed schema across common scenarios.

Changes:

• Adds a Proposed ADR documenting decisions and phasing for consolidating azure.ai.agents configuration into azure.yaml via host: azure.ai.agent + new host: azure.ai.project.
• Adds five scenario-based azure.yaml examples showing runtime: (code/zip deploy), docker: (Dockerfile build), and image: (pre-built image) deployment sources.
• Documents brownfield patterns via a proposed resourceId: field and references related RFC/issues for Phase 2.

Reviewed changes

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

Show a summary per file

File	Description
docs/architecture/adr-unify-foundry-agent-config.md	Proposed ADR capturing the decision to split agent runtime vs project-scoped Foundry resources across two host kinds in azure.yaml.
docs/architecture/azure-yaml-examples/code-deploy.yaml	Example showing code/zip deploy via a typed runtime: { stack, version } block plus project-scoped resources.
docs/architecture/azure-yaml-examples/container-build.yaml	Example showing container mode via docker: build configuration.
docs/architecture/azure-yaml-examples/existing-image.yaml	Example showing image-only deploy via top-level image: with no build step.
docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml	Brownfield example showing reuse of an existing model deployment and referencing an existing Foundry project.
docs/architecture/azure-yaml-examples/brownfield-new-model.yaml	Brownfield example showing creation of a new model deployment against an existing Foundry project.

Comments suppressed due to low confidence (1)

docs/architecture/adr-unify-foundry-agent-config.md:141

• This ADR omits the ### Consequences and ### Alternatives Considered sections that are part of the standard ADR template (docs/architecture/adr-template.md). Adding these sections helps readers understand tradeoffs and why this approach was chosen, especially since the status is still Proposed.

### Proposed `azure.yaml` shape

The proposed end-state of `azure.yaml` is captured as standalone, illustrative
examples alongside this ADR, one self-contained file per scenario, under
[`azure-yaml-examples/`](./azure-yaml-examples/):

| Scenario | File | Deploy source |
|---|---|---|
| New project, zip/code-deploy | [`code-deploy.yaml`](./azure-yaml-examples/code-deploy.yaml) | `runtime:` |
| New project, build from Dockerfile | [`container-build.yaml`](./azure-yaml-examples/container-build.yaml) | `docker:` |
| New project, existing pre-built image (ACR) | [`existing-image.yaml`](./azure-yaml-examples/existing-image.yaml) | `image:` |
| Existing project, reuse existing model | [`brownfield-existing-model.yaml`](./azure-yaml-examples/brownfield-existing-model.yaml) | `runtime:` |
| Existing project, create new model | [`brownfield-new-model.yaml`](./azure-yaml-examples/brownfield-new-model.yaml) | `runtime:` |

Each file pairs a single `host: azure.ai.project` service (project-scoped
data-plane resources — model deployments, connections, toolboxes) with a
`host: azure.ai.agent` service that references it via `uses:`. The three deploy
sources (`runtime:` / `docker:` / `image:`) are mutually exclusive; exactly one
is required. The brownfield files use the `resourceId:` field introduced by the
Bicep-less RFC [#8065](https://github.com/Azure/azure-dev/issues/8065) (Phase 2).