From 3ff1b74778734dfbd6197cfda0f0ef8b1ce07aa3 Mon Sep 17 00:00:00 2001
From: huimiu <miuhui@outlook.com>
Date: Mon, 8 Jun 2026 14:44:33 +0800
Subject: [PATCH 1/7] docs(adr): add ADR-001 for unifying Foundry agent config
 in azure.yaml

Records the agreed direction from #7962: consolidate agent.yaml /
agent.manifest.yaml into azure.yaml, split agent-scoped vs project-scoped
config across host: azure.ai.agent and the new host: azure.ai.project, and
capture the locked decisions, open provision/deploy boundary questions, core
impact, and alternatives considered.

Refs #7962
---
 .../adr-001-unify-foundry-agent-config.md     | 176 ++++++++++++++++++
 1 file changed, 176 insertions(+)
 create mode 100644 docs/architecture/adr-001-unify-foundry-agent-config.md

diff --git a/docs/architecture/adr-001-unify-foundry-agent-config.md b/docs/architecture/adr-001-unify-foundry-agent-config.md
new file mode 100644
index 00000000000..49ef43107fe
--- /dev/null
+++ b/docs/architecture/adr-001-unify-foundry-agent-config.md
@@ -0,0 +1,176 @@
+# ADR-001: Unify Foundry agent configuration in `azure.yaml`
+
+**Status:** Proposed
+
+**Date:** 2026-06-08
+
+**Tracking issue:** [#7962](https://github.com/Azure/azure-dev/issues/7962)
+
+### Context
+
+The `azure.ai.agents` extension currently models a hosted Foundry agent across
+**three files**: `azure.yaml`, `agent.yaml` (an `AgentDefinition`), and
+`agent.manifest.yaml` (an `AgentManifest`). This creates several problems:
+
+1. **Three files, overlapping data.** The agent name appears in three places,
+   container resources in two, the model deployment name in three. Two
+   templating syntaxes (`{{param}}` and `${ENV}`) overlap. Issue
+   [#7901](https://github.com/Azure/azure-dev/issues/7901) is a symptom — `init`
+   fails when run in a directory that already contains the manifest.
+2. **Scope conflation.** `services.<agent>.config` mixes agent-scoped concerns
+   (container resources, env, startup command) with project-scoped resources
+   (model deployments, connections, toolboxes).
+3. **No sharing across agents.** Project-scoped resources are nested under a
+   single agent, so a second agent that wants the same toolbox must redeclare
+   it. There is nowhere to say "this toolbox belongs to the project."
+4. **Divergent tooling.** The Foundry Toolkit for VS Code parses `agent.yaml`
+   directly while `azd ai agent` works off an `AgentManifest`; the experiences
+   diverge.
+5. **The manifest layer carries no weight.** `agent.manifest.yaml` was designed
+   for an agent catalog that was never built. Its templating isn't paying for
+   itself, and abstracting concrete values with `${ENV_VAR}` blurs the line
+   between a definition and a template.
+
+We want `azure.yaml` to be the single source of truth: it describes **what
+exists in the Foundry project** and **how the agent runs**; agent code defines
+**what the agent does**; the azd environment carries deployment-target values;
+Bicep is opt-in for developers who need full IaC reproducibility.
+
+### Decision
+
+Consolidate all hosted-agent configuration into `azure.yaml` and split it by
+scope across two host kinds.
+
+1. **`host: azure.ai.agent`** describes the agent runtime only. Its `config:`
+   block maps to the Foundry create-agent API: `kind`, `description`,
+   `metadata`, `protocols`, `container.resources`, `env`, `startupCommand`. The
+   project-scoped fields (`deployments`, `resources`, `toolConnections`,
+   `toolboxes`, `connections`) are removed from this schema.
+2. **`host: azure.ai.project`** (new) owns all project-scoped Foundry
+   data-plane state that can't be modeled in ARM/Bicep — today toolboxes,
+   connections, and model deployments; future additions (eval datasets, vector
+   indexes, knowledge sources) go here too (`additionalProperties: true`). It is
+   a service **without source code**: no `project:` directory, no build, no
+   artifact. One `azure.ai.project` service per Foundry project.
+3. **Agents reference the project via the existing `uses:` field**
+   (`uses: [foundry-project]`). This is azd's existing inter-service dependency
+   primitive on `ServiceConfig` — it orders deploys and injects the
+   dependency's outputs as env vars. **No `dependsOn`, no core schema change.**
+4. **Container mode reuses the existing `docker:` block** (`docker.path`,
+   `docker.remoteBuild`). No new top-level `dockerfile` field — that would
+   conflict with the existing `DockerProjectOptions` on `ServiceConfig`.
+5. **Code-deploy mode uses a typed `runtime: { stack, version }` block**,
+   following the existing azure.yaml runtime precedent — not a bare string.
+6. **Deploy mode is explicit.** `docker:` present → container mode; `runtime:`
+   present → code-deploy mode; neither → validation error; both → validation
+   error. No silent defaults.
+7. **`${VAR}` env-var expansion** uses the same syntax `azure.yaml` already
+   supports. The extension performs the expansion inside `config:` blocks
+   (the core framework does not expand `config:` — see Consequences).
+8. **`init` populates `config:`** the way it currently populates `agent.yaml`,
+   and stops emitting `agent.yaml` / `agent.manifest.yaml`. A deprecation window
+   keeps reading the old files (with a warning + telemetry) before removal.
+
+**Phasing (locked):**
+
+- **Phase 1** — Consolidate files. Retire `agent.yaml` / `agent.manifest.yaml`,
+  move their content into `azure.yaml`, and ship the new `azure.ai.project`
+  service target. Provisioning continues to use existing Bicep/ARM.
+- **Phase 2** — Bicep-less provisioning: the extension carries built-in Bicep
+  templates and generates ARM in memory during `azd provision` (similar to
+  `azd compose`), with opt-in eject to Bicep on disk. Gated on a separate RFC
+  (not yet filed) and on a real multi-agent sample that needs shared resources.
+
+### Open Questions (to resolve before locking the schema)
+
+This ADR records the agreed direction; the following provision/deploy boundary
+questions (raised in the issue's framework review) must be answered before the
+`azure.ai.project` schema is finalized:
+
+1. **What exactly does `azure.ai.project` Deploy create vs. what stays in
+   provision/Bicep?** Toolboxes are clearly data-plane (Deploy). Model
+   deployments and connections are ambiguous — today deployments are serialized
+   to env vars and consumed by Bicep, and connection creation involves
+   ARM-level resources plus credential handling. We need a clear inventory of
+   the provision (ARM) vs. deploy (Foundry API) split.
+2. **Idempotency and state.** On repeated `azd deploy`, does the project target
+   diff declared config against existing Foundry state and apply incremental
+   changes, or recreate from scratch? How are removals handled (a toolbox
+   deleted from config — does Deploy delete it from Foundry)? Relates to
+   [#8350](https://github.com/Azure/azure-dev/issues/8350) and
+   [#8349](https://github.com/Azure/azure-dev/issues/8349).
+3. **Error recovery across the `uses` chain.** If `azure.ai.project` Deploy
+   fails partway (toolboxes created, a connection fails), what is the recovery
+   story for downstream agents that depend on it?
+4. **Service-level `runtime:` typing.** The typed `runtime: { stack, version }`
+   block exists in the schema today only under the compose `appServiceResource`
+   definition, **not under `services.<name>`**, and `ServiceConfig` has no
+   `Runtime` field. Phase 1 can capture it via `AdditionalProperties` (untyped,
+   not validated by the core schema), or core can promote `runtime` to a
+   first-class service field. Decide whether the typing/validation cost
+   justifies a core change.
+
+### Consequences
+
+**Easier:**
+
+- One file to read and edit. The agent name, container resources, and model
+  deployment name each live in exactly one place.
+- Clean scope separation: "what the agent IS to Foundry" (`config:`) vs. "how
+  azd packages and orders it" (service-level `docker:` / `runtime:` / `uses:`).
+- Resource sharing across agents is natural — a second agent is just another
+  `host: azure.ai.agent` with `uses: [foundry-project]`, nothing duplicated.
+- Foundry Toolkit for VS Code can read/write `azure.yaml` directly, converging
+  the CLI and Toolkit experiences.
+
+**Harder / requires care:**
+
+- The core framework does **not** expand `${VAR}` inside `config:` blocks
+  (`Config` is serialized straight to `structpb` without `Envsubst`). The
+  extension must own interpolation; a shared recursive config walker should be
+  used by both the agent and project targets.
+- `azure.ai.project` is a service with no source code — Package/Publish are
+  no-ops and the lifecycle (toolbox/connection/deployment creation) must move
+  out of provisioning hooks into the project target's `Deploy`.
+- A deprecation window for `agent.yaml` / `agent.manifest.yaml` means two read
+  paths exist temporarily; telemetry is needed to know when removal is safe.
+- Downstream cleanup: rename/repurpose `exterrors.CodeInvalidAgentManifest`,
+  retire the `agent_yaml` package, migrate reference templates/samples, and
+  update docs (`glossary.md`, `feature-status.md`).
+
+**Core impact:** Phase 1 needs **no mandatory azd core change**. `host` is an
+open `type: string` (not a closed enum), host kinds register over gRPC via
+`WithServiceTarget`, `uses` ordering and source-less services already work, and
+`ServiceConfig.Config` is `map[string]any`. The only optional core changes are:
+(a) adding `azure.ai.project` to the `host` examples in the core schema for
+discoverability, and (b) promoting a service-level `runtime:` field to
+`ServiceConfig` + schema if first-class typing is desired (see Open Question 4).
+
+### Alternatives Considered
+
+- **Make `agent.yaml` the source of truth; introduce `azure.yaml` only on
+  opt-in.** Keeps a single per-agent file for the standalone path. Rejected
+  because `agent.yaml` is per-agent by definition — project-scoped resources
+  (toolboxes today, knowledge indexes tomorrow) have nowhere good to live.
+  Every sub-option (inline in each agent, a new `foundry.yaml`, or AZD-only
+  project scope) reintroduces duplication or a third file.
+- **Hybrid: keep `agent.yaml` for the per-agent definition, `azure.yaml` for
+  orchestration only.** Structurally separates concerns but keeps two parallel
+  deploy code paths alive and requires permanent schema vigilance to keep
+  agent-definition fields out of the service block. The "no `azure.yaml` in the
+  root" win is mostly perceptual — the standalone path here is already
+  `azure.yaml` + agent code, no `.azure/`, no `infra/`.
+- **Project-scoped resources as a sibling service per resource type**
+  (`host: azure.ai.toolbox`, etc., Option A). Rejected — proliferation risk;
+  toolboxes aren't really "services" (no source dir, no build), and it sets a
+  precedent for `host: azure.ai.eval-dataset`, `host: azure.ai.vector-index`,
+  and so on.
+- **Project-scoped resources under the agent extension namespace**
+  (`extensions.azure.ai.agents.toolboxes:`). Rejected — still nests
+  project-level resources under the agent extension's namespace, which doesn't
+  address that models, connections, and toolboxes live at the Foundry **project**
+  scope, not the agent scope.
+- **A new top-level `resources:` section** (Option C). Clean separation but
+  introduces a new top-level concept to the core azure.yaml schema — a bigger
+  cross-cutting change than reusing a single `azure.ai.project` host kind
+  (Option B, chosen).

From 976089e872d3f82b644780973e33e935f6cebf30 Mon Sep 17 00:00:00 2001
From: huimiu <miuhui@outlook.com>
Date: Mon, 8 Jun 2026 14:52:24 +0800
Subject: [PATCH 2/7] docs(adr): trim ADR-001 to the proposal and add
 azure.yaml example

Remove the Consequences and Alternatives Considered sections (impact is
already well understood by reviewers) so the ADR focuses on proposing the
final azure.yaml shape, and add a standalone illustrative example file
referenced from the ADR.

Refs #7962
---
 .../adr-001-azure-yaml-example.yaml           | 89 +++++++++++++++++++
 .../adr-001-unify-foundry-agent-config.md     | 74 +++------------
 2 files changed, 99 insertions(+), 64 deletions(-)
 create mode 100644 docs/architecture/adr-001-azure-yaml-example.yaml

diff --git a/docs/architecture/adr-001-azure-yaml-example.yaml b/docs/architecture/adr-001-azure-yaml-example.yaml
new file mode 100644
index 00000000000..67d436234d4
--- /dev/null
+++ b/docs/architecture/adr-001-azure-yaml-example.yaml
@@ -0,0 +1,89 @@
+# Proposed azure.yaml shape for ADR-001 — Unify Foundry agent configuration.
+# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
+#
+# Illustrative end-state, not a runnable template. It shows the two host kinds
+# and how an agent references the project via `uses`.
+
+name: my-foundry-agents
+
+services:
+  # ---------------------------------------------------------------------------
+  # Project-scoped service: all Foundry data-plane resources in one place.
+  # No source directory, no build artifact — pure declarative state.
+  # `provision` creates the Foundry project (ARM); `deploy` creates/updates the
+  # data-plane resources (deployments, connections, toolboxes) via Foundry APIs.
+  # ---------------------------------------------------------------------------
+  foundry-project:
+    host: azure.ai.project
+    config:
+      deployments:
+        - name: gpt-4.1-mini
+          model:
+            format: OpenAI
+            name: gpt-4.1-mini
+            version: "2025-04-14"
+          sku:
+            name: GlobalBatch
+            capacity: 10
+      connections:
+        - name: github-mcp-conn
+          category: CustomKeys
+          target: https://api.githubcopilot.com/mcp
+          authType: ApiKey
+      toolboxes:
+        agent-toolbox:
+          tools:
+            - { type: web_search }
+            - { type: code_interpreter }
+            - { type: mcp, connection: ${GITHUB_MCP_CONN} }
+
+  # ---------------------------------------------------------------------------
+  # Agent-scoped service: the agent runtime. References the project via `uses`.
+  # Code-deploy mode: a `runtime:` block is present -> azd zips the project
+  # directory and Foundry schedules it on the appropriate managed base image.
+  # ---------------------------------------------------------------------------
+  my-agent:
+    project: src/my-agent
+    host: azure.ai.agent
+    uses: [foundry-project]
+    runtime:
+      stack: python
+      version: "3.13"
+    config:
+      kind: hosted
+      description: A basic agent hosted by Foundry.
+      protocols:
+        - { protocol: responses, version: 1.0.0 }
+      env:
+        AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
+      startupCommand: python main.py
+
+  # ---------------------------------------------------------------------------
+  # A second agent that wants the same toolbox is just another
+  # `host: azure.ai.agent` entry with `uses: [foundry-project]` — nothing is
+  # duplicated. The project service is the single source of truth for shared
+  # resources.
+  # ---------------------------------------------------------------------------
+
+  # ---------------------------------------------------------------------------
+  # Container-mode variant: replace the `runtime:` block with a `docker:` block.
+  # `docker:` and `runtime:` are mutually exclusive; exactly one is required.
+  # ---------------------------------------------------------------------------
+  #
+  #   my-agent:
+  #     project: src/my-agent
+  #     host: azure.ai.agent
+  #     uses: [foundry-project]
+  #     docker: { path: Dockerfile, remoteBuild: true }
+  #     config:
+  #       kind: hosted
+  #       protocols:
+  #         - { protocol: responses, version: 1.0.0 }
+  #       container:
+  #         resources: { cpu: "0.25", memory: 0.5Gi }
+  #       env:
+  #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
+
+# No infra: block needed by default. azd provision uses built-in Bicep templates
+# internally (like azd compose). Opt in to Bicep on disk via `azd infra gen` or
+# equivalent (separate RFC).
diff --git a/docs/architecture/adr-001-unify-foundry-agent-config.md b/docs/architecture/adr-001-unify-foundry-agent-config.md
index 49ef43107fe..c9cce33aac4 100644
--- a/docs/architecture/adr-001-unify-foundry-agent-config.md
+++ b/docs/architecture/adr-001-unify-foundry-agent-config.md
@@ -110,67 +110,13 @@ questions (raised in the issue's framework review) must be answered before the
    first-class service field. Decide whether the typing/validation cost
    justifies a core change.
 
-### Consequences
-
-**Easier:**
-
-- One file to read and edit. The agent name, container resources, and model
-  deployment name each live in exactly one place.
-- Clean scope separation: "what the agent IS to Foundry" (`config:`) vs. "how
-  azd packages and orders it" (service-level `docker:` / `runtime:` / `uses:`).
-- Resource sharing across agents is natural — a second agent is just another
-  `host: azure.ai.agent` with `uses: [foundry-project]`, nothing duplicated.
-- Foundry Toolkit for VS Code can read/write `azure.yaml` directly, converging
-  the CLI and Toolkit experiences.
-
-**Harder / requires care:**
-
-- The core framework does **not** expand `${VAR}` inside `config:` blocks
-  (`Config` is serialized straight to `structpb` without `Envsubst`). The
-  extension must own interpolation; a shared recursive config walker should be
-  used by both the agent and project targets.
-- `azure.ai.project` is a service with no source code — Package/Publish are
-  no-ops and the lifecycle (toolbox/connection/deployment creation) must move
-  out of provisioning hooks into the project target's `Deploy`.
-- A deprecation window for `agent.yaml` / `agent.manifest.yaml` means two read
-  paths exist temporarily; telemetry is needed to know when removal is safe.
-- Downstream cleanup: rename/repurpose `exterrors.CodeInvalidAgentManifest`,
-  retire the `agent_yaml` package, migrate reference templates/samples, and
-  update docs (`glossary.md`, `feature-status.md`).
-
-**Core impact:** Phase 1 needs **no mandatory azd core change**. `host` is an
-open `type: string` (not a closed enum), host kinds register over gRPC via
-`WithServiceTarget`, `uses` ordering and source-less services already work, and
-`ServiceConfig.Config` is `map[string]any`. The only optional core changes are:
-(a) adding `azure.ai.project` to the `host` examples in the core schema for
-discoverability, and (b) promoting a service-level `runtime:` field to
-`ServiceConfig` + schema if first-class typing is desired (see Open Question 4).
-
-### Alternatives Considered
-
-- **Make `agent.yaml` the source of truth; introduce `azure.yaml` only on
-  opt-in.** Keeps a single per-agent file for the standalone path. Rejected
-  because `agent.yaml` is per-agent by definition — project-scoped resources
-  (toolboxes today, knowledge indexes tomorrow) have nowhere good to live.
-  Every sub-option (inline in each agent, a new `foundry.yaml`, or AZD-only
-  project scope) reintroduces duplication or a third file.
-- **Hybrid: keep `agent.yaml` for the per-agent definition, `azure.yaml` for
-  orchestration only.** Structurally separates concerns but keeps two parallel
-  deploy code paths alive and requires permanent schema vigilance to keep
-  agent-definition fields out of the service block. The "no `azure.yaml` in the
-  root" win is mostly perceptual — the standalone path here is already
-  `azure.yaml` + agent code, no `.azure/`, no `infra/`.
-- **Project-scoped resources as a sibling service per resource type**
-  (`host: azure.ai.toolbox`, etc., Option A). Rejected — proliferation risk;
-  toolboxes aren't really "services" (no source dir, no build), and it sets a
-  precedent for `host: azure.ai.eval-dataset`, `host: azure.ai.vector-index`,
-  and so on.
-- **Project-scoped resources under the agent extension namespace**
-  (`extensions.azure.ai.agents.toolboxes:`). Rejected — still nests
-  project-level resources under the agent extension's namespace, which doesn't
-  address that models, connections, and toolboxes live at the Foundry **project**
-  scope, not the agent scope.
-- **A new top-level `resources:` section** (Option C). Clean separation but
-  introduces a new top-level concept to the core azure.yaml schema — a bigger
-  cross-cutting change than reusing a single `azure.ai.project` host kind
-  (Option B, chosen).
+### Proposed `azure.yaml` shape
+
+The proposed end-state of `azure.yaml` after this change is captured as a
+standalone, illustrative example alongside this ADR:
+[`adr-001-azure-yaml-example.yaml`](./adr-001-azure-yaml-example.yaml).
+
+It shows a single `host: azure.ai.project` service that owns the project-scoped
+data-plane resources (model deployments, connections, toolboxes) and a
+`host: azure.ai.agent` service that references it via `uses:`, in both
+code-deploy (`runtime:`) and container (`docker:`) modes.

From b0d5395a8e9b6cfc172fdd14c31aaf6c980c91e2 Mon Sep 17 00:00:00 2001
From: huimiu <miuhui@outlook.com>
Date: Mon, 8 Jun 2026 14:54:54 +0800
Subject: [PATCH 3/7] docs(adr): drop numbered prefix from ADR filenames and
 content

Refs #7962
---
 ...ndry-agent-config.md => adr-unify-foundry-agent-config.md} | 4 ++--
 ...-azure-yaml-example.yaml => azure-yaml-agent-example.yaml} | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
 rename docs/architecture/{adr-001-unify-foundry-agent-config.md => adr-unify-foundry-agent-config.md} (98%)
 rename docs/architecture/{adr-001-azure-yaml-example.yaml => azure-yaml-agent-example.yaml} (97%)

diff --git a/docs/architecture/adr-001-unify-foundry-agent-config.md b/docs/architecture/adr-unify-foundry-agent-config.md
similarity index 98%
rename from docs/architecture/adr-001-unify-foundry-agent-config.md
rename to docs/architecture/adr-unify-foundry-agent-config.md
index c9cce33aac4..526669f342a 100644
--- a/docs/architecture/adr-001-unify-foundry-agent-config.md
+++ b/docs/architecture/adr-unify-foundry-agent-config.md
@@ -1,4 +1,4 @@
-# ADR-001: Unify Foundry agent configuration in `azure.yaml`
+# ADR: Unify Foundry agent configuration in `azure.yaml`
 
 **Status:** Proposed
 
@@ -114,7 +114,7 @@ questions (raised in the issue's framework review) must be answered before the
 
 The proposed end-state of `azure.yaml` after this change is captured as a
 standalone, illustrative example alongside this ADR:
-[`adr-001-azure-yaml-example.yaml`](./adr-001-azure-yaml-example.yaml).
+[`azure-yaml-agent-example.yaml`](./azure-yaml-agent-example.yaml).
 
 It shows a single `host: azure.ai.project` service that owns the project-scoped
 data-plane resources (model deployments, connections, toolboxes) and a
diff --git a/docs/architecture/adr-001-azure-yaml-example.yaml b/docs/architecture/azure-yaml-agent-example.yaml
similarity index 97%
rename from docs/architecture/adr-001-azure-yaml-example.yaml
rename to docs/architecture/azure-yaml-agent-example.yaml
index 67d436234d4..49f0dec5cf5 100644
--- a/docs/architecture/adr-001-azure-yaml-example.yaml
+++ b/docs/architecture/azure-yaml-agent-example.yaml
@@ -1,4 +1,4 @@
-# Proposed azure.yaml shape for ADR-001 — Unify Foundry agent configuration.
+# Proposed azure.yaml shape — Unify Foundry agent configuration.
 # Tracking issue: https://github.com/Azure/azure-dev/issues/7962
 #
 # Illustrative end-state, not a runnable template. It shows the two host kinds

From 9a8f53c847577416728345b94d6c518eab85f787 Mon Sep 17 00:00:00 2001
From: huimiu <miuhui@outlook.com>
Date: Mon, 8 Jun 2026 15:01:20 +0800
Subject: [PATCH 4/7] docs(adr): clarify cpu/memory applies to all deploy
 modes; add existing-image example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- container.resources (cpu/memory) is part of the Foundry create-agent API for
  both code-deploy and container/image agents (defaults cpu:1, memory:2Gi), so
  it stays in the agent config regardless of deploy source — corrected in the
  ADR and shown in the code-deploy example.
- Add a third deploy source: existing pre-built image via the top-level image:
  field (e.g. ACR), mutually exclusive with docker:/runtime:, with an example
  variant in the sample azure.yaml.

Refs #7962
---
 .../adr-unify-foundry-agent-config.md         | 29 ++++++++++++------
 .../azure-yaml-agent-example.yaml             | 30 +++++++++++++++++--
 2 files changed, 48 insertions(+), 11 deletions(-)

diff --git a/docs/architecture/adr-unify-foundry-agent-config.md b/docs/architecture/adr-unify-foundry-agent-config.md
index 526669f342a..699186761be 100644
--- a/docs/architecture/adr-unify-foundry-agent-config.md
+++ b/docs/architecture/adr-unify-foundry-agent-config.md
@@ -57,17 +57,27 @@ scope across two host kinds.
    primitive on `ServiceConfig` — it orders deploys and injects the
    dependency's outputs as env vars. **No `dependsOn`, no core schema change.**
 4. **Container mode reuses the existing `docker:` block** (`docker.path`,
-   `docker.remoteBuild`). No new top-level `dockerfile` field — that would
+   `docker.remoteBuild`) to build the image from a Dockerfile. An
+   already-published image is referenced via the existing top-level `image:`
+   field on `ServiceConfig` (e.g. `myregistry.azurecr.io/my-agent:v1`) — no
+   build, no new field. No new top-level `dockerfile` field — that would
    conflict with the existing `DockerProjectOptions` on `ServiceConfig`.
 5. **Code-deploy mode uses a typed `runtime: { stack, version }` block**,
    following the existing azure.yaml runtime precedent — not a bare string.
-6. **Deploy mode is explicit.** `docker:` present → container mode; `runtime:`
-   present → code-deploy mode; neither → validation error; both → validation
-   error. No silent defaults.
-7. **`${VAR}` env-var expansion** uses the same syntax `azure.yaml` already
+6. **Deploy source is explicit and exactly one of three.** `image:` present →
+   use the existing pre-built image; `docker:` present → build the image from a
+   Dockerfile; `runtime:` present → zip the project for code-deploy. Zero or
+   more than one present → validation error. No silent defaults.
+7. **`container.resources` (`cpu`/`memory`) applies to every deploy mode**, not
+   just container mode. The Foundry create-agent API carries `cpu` and `memory`
+   for both code-deploy and container/image agents; when omitted the extension
+   applies defaults (today `cpu: "1"`, `memory: "2Gi"`). So `container.resources`
+   stays in the agent `config:` regardless of whether `image:`, `docker:`, or
+   `runtime:` is used.
+8. **`${VAR}` env-var expansion** uses the same syntax `azure.yaml` already
    supports. The extension performs the expansion inside `config:` blocks
-   (the core framework does not expand `config:` — see Consequences).
-8. **`init` populates `config:`** the way it currently populates `agent.yaml`,
+   (the core framework does not expand `config:`).
+9. **`init` populates `config:`** the way it currently populates `agent.yaml`,
    and stops emitting `agent.yaml` / `agent.manifest.yaml`. A deprecation window
    keeps reading the old files (with a warning + telemetry) before removal.
 
@@ -118,5 +128,6 @@ standalone, illustrative example alongside this ADR:
 
 It shows a single `host: azure.ai.project` service that owns the project-scoped
 data-plane resources (model deployments, connections, toolboxes) and a
-`host: azure.ai.agent` service that references it via `uses:`, in both
-code-deploy (`runtime:`) and container (`docker:`) modes.
+`host: azure.ai.agent` service that references it via `uses:`, across all three
+deploy sources: code-deploy (`runtime:`), build-from-Dockerfile (`docker:`), and
+existing pre-built image (`image:`).
diff --git a/docs/architecture/azure-yaml-agent-example.yaml b/docs/architecture/azure-yaml-agent-example.yaml
index 49f0dec5cf5..a9110f5ef22 100644
--- a/docs/architecture/azure-yaml-agent-example.yaml
+++ b/docs/architecture/azure-yaml-agent-example.yaml
@@ -54,6 +54,12 @@ services:
       description: A basic agent hosted by Foundry.
       protocols:
         - { protocol: responses, version: 1.0.0 }
+      # container.resources (cpu/memory) applies to ALL deploy modes, including
+      # code-deploy — the Foundry create-agent API carries cpu/memory for both
+      # code and container agents. Defaults apply when omitted (cpu: "1",
+      # memory: "2Gi").
+      container:
+        resources: { cpu: "0.5", memory: 1Gi }
       env:
         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
       startupCommand: python main.py
@@ -66,8 +72,9 @@ services:
   # ---------------------------------------------------------------------------
 
   # ---------------------------------------------------------------------------
-  # Container-mode variant: replace the `runtime:` block with a `docker:` block.
-  # `docker:` and `runtime:` are mutually exclusive; exactly one is required.
+  # Container mode variant (build from Dockerfile): replace the `runtime:` block
+  # with a `docker:` block. `image:` / `docker:` / `runtime:` are mutually
+  # exclusive; exactly one is required.
   # ---------------------------------------------------------------------------
   #
   #   my-agent:
@@ -84,6 +91,25 @@ services:
   #       env:
   #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
 
+  # ---------------------------------------------------------------------------
+  # Existing image variant (no build, no zip): point `image:` at an
+  # already-published container image (e.g. in ACR). azd skips package/publish
+  # and Foundry pulls the image directly.
+  # ---------------------------------------------------------------------------
+  #
+  #   my-agent:
+  #     host: azure.ai.agent
+  #     uses: [foundry-project]
+  #     image: myregistry.azurecr.io/my-agent:v1
+  #     config:
+  #       kind: hosted
+  #       protocols:
+  #         - { protocol: responses, version: 1.0.0 }
+  #       container:
+  #         resources: { cpu: "0.25", memory: 0.5Gi }
+  #       env:
+  #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
+
 # No infra: block needed by default. azd provision uses built-in Bicep templates
 # internally (like azd compose). Opt in to Bicep on disk via `azd infra gen` or
 # equivalent (separate RFC).

From 61a3bbfba0053a9a18011ceb52b77f247dad4fa4 Mon Sep 17 00:00:00 2001
From: huimiu <miuhui@outlook.com>
Date: Mon, 8 Jun 2026 15:27:30 +0800
Subject: [PATCH 5/7] docs(adr): add brownfield (existing project/model) sample
 variants

Add two commented brownfield variants to the example azure.yaml: existing
project + reuse existing model, and existing project + create a new model
deployment. Both use the resourceId: field from the Bicep-less RFC (#8065,
Phase 2), clearly noted as such. ADR prose updated to reference them.

Refs #7962
---
 .../adr-unify-foundry-agent-config.md         |  4 +-
 .../azure-yaml-agent-example.yaml             | 55 +++++++++++++++++++
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/docs/architecture/adr-unify-foundry-agent-config.md b/docs/architecture/adr-unify-foundry-agent-config.md
index 699186761be..e9d58a3c35c 100644
--- a/docs/architecture/adr-unify-foundry-agent-config.md
+++ b/docs/architecture/adr-unify-foundry-agent-config.md
@@ -130,4 +130,6 @@ It shows a single `host: azure.ai.project` service that owns the project-scoped
 data-plane resources (model deployments, connections, toolboxes) and a
 `host: azure.ai.agent` service that references it via `uses:`, across all three
 deploy sources: code-deploy (`runtime:`), build-from-Dockerfile (`docker:`), and
-existing pre-built image (`image:`).
+existing pre-built image (`image:`). It also includes brownfield variants for an
+existing Foundry project/model via the `resourceId:` field (introduced by the
+Bicep-less RFC [#8065](https://github.com/Azure/azure-dev/issues/8065), Phase 2).
diff --git a/docs/architecture/azure-yaml-agent-example.yaml b/docs/architecture/azure-yaml-agent-example.yaml
index a9110f5ef22..45f52217e02 100644
--- a/docs/architecture/azure-yaml-agent-example.yaml
+++ b/docs/architecture/azure-yaml-agent-example.yaml
@@ -110,6 +110,61 @@ services:
   #       env:
   #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
 
+  # ===========================================================================
+  # BROWNFIELD VARIANTS — using an existing Foundry project and/or model.
+  #
+  # NOTE: the `resourceId:` field below is introduced by the Bicep-less
+  # provisioning RFC (https://github.com/Azure/azure-dev/issues/8065), i.e.
+  # Phase 2. Its presence flips the project service to "existing project" mode:
+  # the Foundry project ARM resource is omitted from the synthesized Bicep and
+  # only referenced. Until Phase 2 lands, brownfield is handled via the
+  # USE_EXISTING_AI_PROJECT / AZURE_AI_PROJECT_ID azd environment variables.
+  # ===========================================================================
+
+  # ---------------------------------------------------------------------------
+  # Brownfield A — existing project, reuse an existing model deployment.
+  # `resourceId:` references the project (not created). No `deployments:` block:
+  # the model already exists, so the agent just references its deployment name.
+  # ---------------------------------------------------------------------------
+  #
+  #   foundry-project:
+  #     host: azure.ai.project
+  #     resourceId: ${AZURE_AI_PROJECT_ID}   # presence -> existing project mode
+  #     config:
+  #       # No deployments: — the model already exists in the project.
+  #       toolboxes:
+  #         agent-toolbox:
+  #           tools:
+  #             - { type: web_search }
+  #
+  #   my-agent:
+  #     project: src/my-agent
+  #     host: azure.ai.agent
+  #     uses: [foundry-project]
+  #     runtime: { stack: python, version: "3.13" }
+  #     config:
+  #       kind: hosted
+  #       protocols:
+  #         - { protocol: responses, version: 1.0.0 }
+  #       env:
+  #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini   # reference only
+  #       startupCommand: python main.py
+
+  # ---------------------------------------------------------------------------
+  # Brownfield B — existing project, but create a NEW model deployment on it.
+  # `resourceId:` references the project; the deployment under `config:` is still
+  # synthesized (ARM-backed) against that existing project.
+  # ---------------------------------------------------------------------------
+  #
+  #   foundry-project:
+  #     host: azure.ai.project
+  #     resourceId: ${AZURE_AI_PROJECT_ID}   # existing project
+  #     config:
+  #       deployments:                       # but this model is created by azd
+  #         - name: gpt-4.1-mini2
+  #           model: { format: OpenAI, name: gpt-4.1-mini, version: "2025-04-14" }
+  #           sku: { name: Standard, capacity: 10 }
+
 # No infra: block needed by default. azd provision uses built-in Bicep templates
 # internally (like azd compose). Opt in to Bicep on disk via `azd infra gen` or
 # equivalent (separate RFC).

From 25df2e67703959fe1b09d0ac58da4a1902ac0ffd Mon Sep 17 00:00:00 2001
From: huimiu <miuhui@outlook.com>
Date: Mon, 8 Jun 2026 15:32:25 +0800
Subject: [PATCH 6/7] docs(adr): split azure.yaml example into per-scenario
 files

Replace the single combined example with five self-contained files under
docs/architecture/azure-yaml-examples/ (code-deploy, container-build,
existing-image, brownfield-existing-model, brownfield-new-model) and index
them from the ADR with a scenario table.

Refs #7962
---
 .../adr-unify-foundry-agent-config.md         |  29 +--
 .../azure-yaml-agent-example.yaml             | 170 ------------------
 .../brownfield-existing-model.yaml            |  39 ++++
 .../brownfield-new-model.yaml                 |  45 +++++
 .../azure-yaml-examples/code-deploy.yaml      |  60 +++++++
 .../azure-yaml-examples/container-build.yaml  |  49 +++++
 .../azure-yaml-examples/existing-image.yaml   |  46 +++++
 7 files changed, 257 insertions(+), 181 deletions(-)
 delete mode 100644 docs/architecture/azure-yaml-agent-example.yaml
 create mode 100644 docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml
 create mode 100644 docs/architecture/azure-yaml-examples/brownfield-new-model.yaml
 create mode 100644 docs/architecture/azure-yaml-examples/code-deploy.yaml
 create mode 100644 docs/architecture/azure-yaml-examples/container-build.yaml
 create mode 100644 docs/architecture/azure-yaml-examples/existing-image.yaml

diff --git a/docs/architecture/adr-unify-foundry-agent-config.md b/docs/architecture/adr-unify-foundry-agent-config.md
index e9d58a3c35c..ed6d0ba3b42 100644
--- a/docs/architecture/adr-unify-foundry-agent-config.md
+++ b/docs/architecture/adr-unify-foundry-agent-config.md
@@ -122,14 +122,21 @@ questions (raised in the issue's framework review) must be answered before the
 
 ### Proposed `azure.yaml` shape
 
-The proposed end-state of `azure.yaml` after this change is captured as a
-standalone, illustrative example alongside this ADR:
-[`azure-yaml-agent-example.yaml`](./azure-yaml-agent-example.yaml).
-
-It shows a single `host: azure.ai.project` service that owns the project-scoped
-data-plane resources (model deployments, connections, toolboxes) and a
-`host: azure.ai.agent` service that references it via `uses:`, across all three
-deploy sources: code-deploy (`runtime:`), build-from-Dockerfile (`docker:`), and
-existing pre-built image (`image:`). It also includes brownfield variants for an
-existing Foundry project/model via the `resourceId:` field (introduced by the
-Bicep-less RFC [#8065](https://github.com/Azure/azure-dev/issues/8065), Phase 2).
+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).
diff --git a/docs/architecture/azure-yaml-agent-example.yaml b/docs/architecture/azure-yaml-agent-example.yaml
deleted file mode 100644
index 45f52217e02..00000000000
--- a/docs/architecture/azure-yaml-agent-example.yaml
+++ /dev/null
@@ -1,170 +0,0 @@
-# Proposed azure.yaml shape — Unify Foundry agent configuration.
-# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
-#
-# Illustrative end-state, not a runnable template. It shows the two host kinds
-# and how an agent references the project via `uses`.
-
-name: my-foundry-agents
-
-services:
-  # ---------------------------------------------------------------------------
-  # Project-scoped service: all Foundry data-plane resources in one place.
-  # No source directory, no build artifact — pure declarative state.
-  # `provision` creates the Foundry project (ARM); `deploy` creates/updates the
-  # data-plane resources (deployments, connections, toolboxes) via Foundry APIs.
-  # ---------------------------------------------------------------------------
-  foundry-project:
-    host: azure.ai.project
-    config:
-      deployments:
-        - name: gpt-4.1-mini
-          model:
-            format: OpenAI
-            name: gpt-4.1-mini
-            version: "2025-04-14"
-          sku:
-            name: GlobalBatch
-            capacity: 10
-      connections:
-        - name: github-mcp-conn
-          category: CustomKeys
-          target: https://api.githubcopilot.com/mcp
-          authType: ApiKey
-      toolboxes:
-        agent-toolbox:
-          tools:
-            - { type: web_search }
-            - { type: code_interpreter }
-            - { type: mcp, connection: ${GITHUB_MCP_CONN} }
-
-  # ---------------------------------------------------------------------------
-  # Agent-scoped service: the agent runtime. References the project via `uses`.
-  # Code-deploy mode: a `runtime:` block is present -> azd zips the project
-  # directory and Foundry schedules it on the appropriate managed base image.
-  # ---------------------------------------------------------------------------
-  my-agent:
-    project: src/my-agent
-    host: azure.ai.agent
-    uses: [foundry-project]
-    runtime:
-      stack: python
-      version: "3.13"
-    config:
-      kind: hosted
-      description: A basic agent hosted by Foundry.
-      protocols:
-        - { protocol: responses, version: 1.0.0 }
-      # container.resources (cpu/memory) applies to ALL deploy modes, including
-      # code-deploy — the Foundry create-agent API carries cpu/memory for both
-      # code and container agents. Defaults apply when omitted (cpu: "1",
-      # memory: "2Gi").
-      container:
-        resources: { cpu: "0.5", memory: 1Gi }
-      env:
-        AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
-      startupCommand: python main.py
-
-  # ---------------------------------------------------------------------------
-  # A second agent that wants the same toolbox is just another
-  # `host: azure.ai.agent` entry with `uses: [foundry-project]` — nothing is
-  # duplicated. The project service is the single source of truth for shared
-  # resources.
-  # ---------------------------------------------------------------------------
-
-  # ---------------------------------------------------------------------------
-  # Container mode variant (build from Dockerfile): replace the `runtime:` block
-  # with a `docker:` block. `image:` / `docker:` / `runtime:` are mutually
-  # exclusive; exactly one is required.
-  # ---------------------------------------------------------------------------
-  #
-  #   my-agent:
-  #     project: src/my-agent
-  #     host: azure.ai.agent
-  #     uses: [foundry-project]
-  #     docker: { path: Dockerfile, remoteBuild: true }
-  #     config:
-  #       kind: hosted
-  #       protocols:
-  #         - { protocol: responses, version: 1.0.0 }
-  #       container:
-  #         resources: { cpu: "0.25", memory: 0.5Gi }
-  #       env:
-  #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
-
-  # ---------------------------------------------------------------------------
-  # Existing image variant (no build, no zip): point `image:` at an
-  # already-published container image (e.g. in ACR). azd skips package/publish
-  # and Foundry pulls the image directly.
-  # ---------------------------------------------------------------------------
-  #
-  #   my-agent:
-  #     host: azure.ai.agent
-  #     uses: [foundry-project]
-  #     image: myregistry.azurecr.io/my-agent:v1
-  #     config:
-  #       kind: hosted
-  #       protocols:
-  #         - { protocol: responses, version: 1.0.0 }
-  #       container:
-  #         resources: { cpu: "0.25", memory: 0.5Gi }
-  #       env:
-  #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
-
-  # ===========================================================================
-  # BROWNFIELD VARIANTS — using an existing Foundry project and/or model.
-  #
-  # NOTE: the `resourceId:` field below is introduced by the Bicep-less
-  # provisioning RFC (https://github.com/Azure/azure-dev/issues/8065), i.e.
-  # Phase 2. Its presence flips the project service to "existing project" mode:
-  # the Foundry project ARM resource is omitted from the synthesized Bicep and
-  # only referenced. Until Phase 2 lands, brownfield is handled via the
-  # USE_EXISTING_AI_PROJECT / AZURE_AI_PROJECT_ID azd environment variables.
-  # ===========================================================================
-
-  # ---------------------------------------------------------------------------
-  # Brownfield A — existing project, reuse an existing model deployment.
-  # `resourceId:` references the project (not created). No `deployments:` block:
-  # the model already exists, so the agent just references its deployment name.
-  # ---------------------------------------------------------------------------
-  #
-  #   foundry-project:
-  #     host: azure.ai.project
-  #     resourceId: ${AZURE_AI_PROJECT_ID}   # presence -> existing project mode
-  #     config:
-  #       # No deployments: — the model already exists in the project.
-  #       toolboxes:
-  #         agent-toolbox:
-  #           tools:
-  #             - { type: web_search }
-  #
-  #   my-agent:
-  #     project: src/my-agent
-  #     host: azure.ai.agent
-  #     uses: [foundry-project]
-  #     runtime: { stack: python, version: "3.13" }
-  #     config:
-  #       kind: hosted
-  #       protocols:
-  #         - { protocol: responses, version: 1.0.0 }
-  #       env:
-  #         AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini   # reference only
-  #       startupCommand: python main.py
-
-  # ---------------------------------------------------------------------------
-  # Brownfield B — existing project, but create a NEW model deployment on it.
-  # `resourceId:` references the project; the deployment under `config:` is still
-  # synthesized (ARM-backed) against that existing project.
-  # ---------------------------------------------------------------------------
-  #
-  #   foundry-project:
-  #     host: azure.ai.project
-  #     resourceId: ${AZURE_AI_PROJECT_ID}   # existing project
-  #     config:
-  #       deployments:                       # but this model is created by azd
-  #         - name: gpt-4.1-mini2
-  #           model: { format: OpenAI, name: gpt-4.1-mini, version: "2025-04-14" }
-  #           sku: { name: Standard, capacity: 10 }
-
-# No infra: block needed by default. azd provision uses built-in Bicep templates
-# internally (like azd compose). Opt in to Bicep on disk via `azd infra gen` or
-# equivalent (separate RFC).
diff --git a/docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml b/docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml
new file mode 100644
index 00000000000..36ca6e49254
--- /dev/null
+++ b/docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml
@@ -0,0 +1,39 @@
+# Scenario: Brownfield — existing Foundry project, reuse an existing model.
+# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
+#
+# NOTE: the `resourceId:` field is introduced by the Bicep-less provisioning RFC
+# (https://github.com/Azure/azure-dev/issues/8065), i.e. Phase 2. Its presence
+# flips the project service to "existing project" mode: the Foundry project ARM
+# resource is omitted from the synthesized Bicep and only referenced. Until
+# Phase 2 lands, brownfield is handled via the USE_EXISTING_AI_PROJECT /
+# AZURE_AI_PROJECT_ID azd environment variables. Illustrative, not runnable.
+
+name: my-foundry-agents
+
+services:
+  foundry-project:
+    host: azure.ai.project
+    resourceId: ${AZURE_AI_PROJECT_ID}   # presence -> existing project mode
+    config:
+      # No deployments: — the model already exists in the project; the agent
+      # only references its deployment name below.
+      toolboxes:
+        agent-toolbox:
+          tools:
+            - { type: web_search }
+
+  my-agent:
+    project: src/my-agent
+    host: azure.ai.agent
+    uses: [foundry-project]
+    runtime:
+      stack: python
+      version: "3.13"
+    config:
+      kind: hosted
+      description: A basic agent hosted by Foundry.
+      protocols:
+        - { protocol: responses, version: 1.0.0 }
+      env:
+        AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini   # reference only
+      startupCommand: python main.py
diff --git a/docs/architecture/azure-yaml-examples/brownfield-new-model.yaml b/docs/architecture/azure-yaml-examples/brownfield-new-model.yaml
new file mode 100644
index 00000000000..bf651912fd1
--- /dev/null
+++ b/docs/architecture/azure-yaml-examples/brownfield-new-model.yaml
@@ -0,0 +1,45 @@
+# Scenario: Brownfield — existing Foundry project, create a NEW model on it.
+# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
+#
+# NOTE: the `resourceId:` field is introduced by the Bicep-less provisioning RFC
+# (https://github.com/Azure/azure-dev/issues/8065), i.e. Phase 2. `resourceId:`
+# references the existing project (not created), but the deployment declared
+# under `config:` is still synthesized (ARM-backed) against that project.
+# Illustrative end-state, not a runnable template.
+
+name: my-foundry-agents
+
+services:
+  foundry-project:
+    host: azure.ai.project
+    resourceId: ${AZURE_AI_PROJECT_ID}   # existing project (not created)
+    config:
+      deployments:                       # but this model IS created by azd
+        - name: gpt-4.1-mini2
+          model:
+            format: OpenAI
+            name: gpt-4.1-mini
+            version: "2025-04-14"
+          sku:
+            name: Standard
+            capacity: 10
+      toolboxes:
+        agent-toolbox:
+          tools:
+            - { type: web_search }
+
+  my-agent:
+    project: src/my-agent
+    host: azure.ai.agent
+    uses: [foundry-project]
+    runtime:
+      stack: python
+      version: "3.13"
+    config:
+      kind: hosted
+      description: A basic agent hosted by Foundry.
+      protocols:
+        - { protocol: responses, version: 1.0.0 }
+      env:
+        AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini2
+      startupCommand: python main.py
diff --git a/docs/architecture/azure-yaml-examples/code-deploy.yaml b/docs/architecture/azure-yaml-examples/code-deploy.yaml
new file mode 100644
index 00000000000..f698157216c
--- /dev/null
+++ b/docs/architecture/azure-yaml-examples/code-deploy.yaml
@@ -0,0 +1,60 @@
+# Scenario: Code-deploy (zip) — new Foundry project.
+# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
+#
+# A `runtime:` block is present, so azd zips the project directory and Foundry
+# schedules it on the appropriate managed base image. Illustrative end-state,
+# not a runnable template.
+
+name: my-foundry-agents
+
+services:
+  # Project-scoped service: all Foundry data-plane resources in one place.
+  # No source directory, no build artifact — pure declarative state.
+  foundry-project:
+    host: azure.ai.project
+    config:
+      deployments:
+        - name: gpt-4.1-mini
+          model:
+            format: OpenAI
+            name: gpt-4.1-mini
+            version: "2025-04-14"
+          sku:
+            name: GlobalBatch
+            capacity: 10
+      connections:
+        - name: github-mcp-conn
+          category: CustomKeys
+          target: https://api.githubcopilot.com/mcp
+          authType: ApiKey
+      toolboxes:
+        agent-toolbox:
+          tools:
+            - { type: web_search }
+            - { type: code_interpreter }
+            - { type: mcp, connection: ${GITHUB_MCP_CONN} }
+
+  # Agent-scoped service: the runtime. References the project via `uses`.
+  my-agent:
+    project: src/my-agent
+    host: azure.ai.agent
+    uses: [foundry-project]
+    # Deploy source: runtime present -> zip/code-deploy.
+    runtime:
+      stack: python
+      version: "3.13"
+    config:
+      kind: hosted
+      description: A basic agent hosted by Foundry.
+      protocols:
+        - { protocol: responses, version: 1.0.0 }
+      # cpu/memory apply to code-deploy too; defaults cpu:"1", memory:"2Gi".
+      container:
+        resources: { cpu: "0.5", memory: 1Gi }
+      env:
+        AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
+      startupCommand: python main.py
+
+# No infra: block needed by default. azd provision uses built-in Bicep templates
+# internally (like azd compose). Opt in to Bicep on disk via `azd infra gen` or
+# equivalent (separate RFC: https://github.com/Azure/azure-dev/issues/8065).
diff --git a/docs/architecture/azure-yaml-examples/container-build.yaml b/docs/architecture/azure-yaml-examples/container-build.yaml
new file mode 100644
index 00000000000..3aefb15197e
--- /dev/null
+++ b/docs/architecture/azure-yaml-examples/container-build.yaml
@@ -0,0 +1,49 @@
+# Scenario: Container build from Dockerfile — new Foundry project.
+# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
+#
+# A `docker:` block is present, so azd builds and pushes the image via the
+# existing docker.path / docker.remoteBuild fields. Illustrative end-state, not
+# a runnable template.
+
+name: my-foundry-agents
+
+services:
+  foundry-project:
+    host: azure.ai.project
+    config:
+      deployments:
+        - name: gpt-4.1-mini
+          model:
+            format: OpenAI
+            name: gpt-4.1-mini
+            version: "2025-04-14"
+          sku:
+            name: GlobalBatch
+            capacity: 10
+      toolboxes:
+        agent-toolbox:
+          tools:
+            - { type: web_search }
+            - { type: code_interpreter }
+
+  my-agent:
+    project: src/my-agent
+    host: azure.ai.agent
+    uses: [foundry-project]
+    # Deploy source: docker present -> build the image from a Dockerfile.
+    docker:
+      path: Dockerfile
+      remoteBuild: true
+    config:
+      kind: hosted
+      description: A basic agent hosted by Foundry.
+      protocols:
+        - { protocol: responses, version: 1.0.0 }
+      container:
+        resources: { cpu: "0.25", memory: 0.5Gi }
+      env:
+        AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
+
+# No infra: block needed by default. azd provision uses built-in Bicep templates
+# internally (like azd compose). Opt in to Bicep on disk via `azd infra gen` or
+# equivalent (separate RFC: https://github.com/Azure/azure-dev/issues/8065).
diff --git a/docs/architecture/azure-yaml-examples/existing-image.yaml b/docs/architecture/azure-yaml-examples/existing-image.yaml
new file mode 100644
index 00000000000..21a4f753ec8
--- /dev/null
+++ b/docs/architecture/azure-yaml-examples/existing-image.yaml
@@ -0,0 +1,46 @@
+# Scenario: Existing pre-built image (e.g. ACR) — new Foundry project.
+# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
+#
+# An `image:` reference is present (no build, no zip). azd skips package/publish
+# and Foundry pulls the already-published image directly. The top-level `image:`
+# field is the existing ServiceConfig field (also used by containerapp), and it
+# supports ${VAR} expansion. Illustrative end-state, not a runnable template.
+
+name: my-foundry-agents
+
+services:
+  foundry-project:
+    host: azure.ai.project
+    config:
+      deployments:
+        - name: gpt-4.1-mini
+          model:
+            format: OpenAI
+            name: gpt-4.1-mini
+            version: "2025-04-14"
+          sku:
+            name: GlobalBatch
+            capacity: 10
+      toolboxes:
+        agent-toolbox:
+          tools:
+            - { type: web_search }
+
+  my-agent:
+    host: azure.ai.agent
+    uses: [foundry-project]
+    # Deploy source: image present -> use the existing pre-built image as-is.
+    image: myregistry.azurecr.io/my-agent:v1
+    config:
+      kind: hosted
+      description: A basic agent hosted by Foundry.
+      protocols:
+        - { protocol: responses, version: 1.0.0 }
+      container:
+        resources: { cpu: "0.25", memory: 0.5Gi }
+      env:
+        AZURE_AI_MODEL_DEPLOYMENT_NAME: gpt-4.1-mini
+
+# No infra: block needed by default. azd provision uses built-in Bicep templates
+# internally (like azd compose). Opt in to Bicep on disk via `azd infra gen` or
+# equivalent (separate RFC: https://github.com/Azure/azure-dev/issues/8065).

From feb6a2ec6250fa34948f98280b6c4af103cd54f4 Mon Sep 17 00:00:00 2001
From: huimiu <miuhui@outlook.com>
Date: Mon, 8 Jun 2026 15:55:44 +0800
Subject: [PATCH 7/7] docs(adr): remove tracking issue comments from examples
 and ADR header

---
 docs/architecture/adr-unify-foundry-agent-config.md             | 2 --
 .../azure-yaml-examples/brownfield-existing-model.yaml          | 1 -
 docs/architecture/azure-yaml-examples/brownfield-new-model.yaml | 1 -
 docs/architecture/azure-yaml-examples/code-deploy.yaml          | 1 -
 docs/architecture/azure-yaml-examples/container-build.yaml      | 1 -
 docs/architecture/azure-yaml-examples/existing-image.yaml       | 1 -
 6 files changed, 7 deletions(-)

diff --git a/docs/architecture/adr-unify-foundry-agent-config.md b/docs/architecture/adr-unify-foundry-agent-config.md
index ed6d0ba3b42..c5ad604db37 100644
--- a/docs/architecture/adr-unify-foundry-agent-config.md
+++ b/docs/architecture/adr-unify-foundry-agent-config.md
@@ -4,8 +4,6 @@
 
 **Date:** 2026-06-08
 
-**Tracking issue:** [#7962](https://github.com/Azure/azure-dev/issues/7962)
-
 ### Context
 
 The `azure.ai.agents` extension currently models a hosted Foundry agent across
diff --git a/docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml b/docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml
index 36ca6e49254..87cdb3f57f0 100644
--- a/docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml
+++ b/docs/architecture/azure-yaml-examples/brownfield-existing-model.yaml
@@ -1,5 +1,4 @@
 # Scenario: Brownfield — existing Foundry project, reuse an existing model.
-# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
 #
 # NOTE: the `resourceId:` field is introduced by the Bicep-less provisioning RFC
 # (https://github.com/Azure/azure-dev/issues/8065), i.e. Phase 2. Its presence
diff --git a/docs/architecture/azure-yaml-examples/brownfield-new-model.yaml b/docs/architecture/azure-yaml-examples/brownfield-new-model.yaml
index bf651912fd1..87059044a58 100644
--- a/docs/architecture/azure-yaml-examples/brownfield-new-model.yaml
+++ b/docs/architecture/azure-yaml-examples/brownfield-new-model.yaml
@@ -1,5 +1,4 @@
 # Scenario: Brownfield — existing Foundry project, create a NEW model on it.
-# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
 #
 # NOTE: the `resourceId:` field is introduced by the Bicep-less provisioning RFC
 # (https://github.com/Azure/azure-dev/issues/8065), i.e. Phase 2. `resourceId:`
diff --git a/docs/architecture/azure-yaml-examples/code-deploy.yaml b/docs/architecture/azure-yaml-examples/code-deploy.yaml
index f698157216c..7e1faa07924 100644
--- a/docs/architecture/azure-yaml-examples/code-deploy.yaml
+++ b/docs/architecture/azure-yaml-examples/code-deploy.yaml
@@ -1,5 +1,4 @@
 # Scenario: Code-deploy (zip) — new Foundry project.
-# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
 #
 # A `runtime:` block is present, so azd zips the project directory and Foundry
 # schedules it on the appropriate managed base image. Illustrative end-state,
diff --git a/docs/architecture/azure-yaml-examples/container-build.yaml b/docs/architecture/azure-yaml-examples/container-build.yaml
index 3aefb15197e..26da48298ca 100644
--- a/docs/architecture/azure-yaml-examples/container-build.yaml
+++ b/docs/architecture/azure-yaml-examples/container-build.yaml
@@ -1,5 +1,4 @@
 # Scenario: Container build from Dockerfile — new Foundry project.
-# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
 #
 # A `docker:` block is present, so azd builds and pushes the image via the
 # existing docker.path / docker.remoteBuild fields. Illustrative end-state, not
diff --git a/docs/architecture/azure-yaml-examples/existing-image.yaml b/docs/architecture/azure-yaml-examples/existing-image.yaml
index 21a4f753ec8..4c7d38eb2fe 100644
--- a/docs/architecture/azure-yaml-examples/existing-image.yaml
+++ b/docs/architecture/azure-yaml-examples/existing-image.yaml
@@ -1,5 +1,4 @@
 # Scenario: Existing pre-built image (e.g. ACR) — new Foundry project.
-# Tracking issue: https://github.com/Azure/azure-dev/issues/7962
 #
 # An `image:` reference is present (no build, no zip). azd skips package/publish
 # and Foundry pulls the already-published image directly. The top-level `image:`