[ext-agents]: azd ai agent init should adopt the sample's azure.yaml, not scaffold/clone from azd-ai-starter-basic (unified azure.yaml + bicep-less)

[therealjohn]

Summary

Today azd ai agent init points at an agent manifest (agent.manifest.yaml) and generates/scaffolds the project-root azure.yaml (and, on main, an infra/ directory cloned from Azure-Samples/azd-ai-starter-basic). Any azure.yaml that ships in the sample is downloaded into the agent's src/<agent-id>/ subfolder and ignored by azd.

Under the unified azure.yaml work on huimiu/foundry-azure-yaml, this needs to change. init will no longer point to an agent manifest -- samples will ship their configuration as a complete unified azure.yaml (host: microsoft.foundry). init should consume the sample's azure.yaml as the project manifest instead of scaffolding/cloning its own, and it should stop downloading infra/ + azure.yaml from azd-ai-starter-basic, because bicep-less provisioning (infra.provider: microsoft.foundry) is the default under the unified work (#8643).

Current behavior (on main)

1. ensureProject finds no existing project, so it runs azd init -t Azure-Samples/azd-ai-starter-basic <targetDir>, which scaffolds the project-root azure.yaml + infra/ from the starter repo, then chdirs into it. (cli/azd/extensions/azure.ai.agents/internal/cmd/init.go, ensureProject ~L1489-1544; starter template at ~L1517-1518)
2. For hosted/container agents, downloadParentDirectory downloads the entire remote manifest folder (no filename filtering) into src/<agent-id>/ -- including the sample's own azure.yaml, which lands at src/<agent-id>/azure.yaml and is never read by azd (azd only reads the project-root azure.yaml). (init.go downloadAgentYaml ~L2472-2495, downloadParentDirectory / downloadDirectoryContents ~L3120-3222)
3. The agent is wired in via Project().AddService(), which appends a service entry to the project-root azure.yaml. (init.go addToProject ~L2691; host gRPC handler cli/azd/internal/grpcserver/project_service.go AddService ~L181-232)

Net result: two azure.yaml files -- the scaffolded project-root one (used) and the sample's copy buried under src/<agent-id>/ (unused).

Note: #8643 (already merged into huimiu/foundry-azure-yaml) replaced the azd-ai-starter-basic clone with an azd init -t <emptyStagedDir> scaffold plus a generated bicep-less azure.yaml (infra.provider: microsoft.foundry). That removed the starter infra/ clone, but init still generates the project azure.yaml rather than adopting the sample's.

Why this needs to change

The unified azure.yaml direction (#8676, #8773, #8709, #8710, and the huimiu/foundry-azure-yaml base branch):

• init no longer points to an agent.manifest.yaml; agent.yaml / agent.manifest.yaml are retired in favor of a single unified azure.yaml using host: microsoft.foundry.
• Samples will therefore ship a complete unified azure.yaml that already declares the project, model deployments, connections, toolboxes, and agent(s).
• Bicep-less provisioning is the default (feat(agents): bicep-less init for azd ai agent init #8643), so there is no need to pull infra/ (or a separate azure.yaml) from azd-ai-starter-basic.

Continuing to scaffold/generate a project azure.yaml (or clone one from the starter repo) and bury the sample's azure.yaml under src/<agent-id>/ is wrong under this model: the sample's azure.yaml is the source of truth.

Proposed behavior

When initializing from a sample/URL that ships a unified azure.yaml:

1. Use the sample's azure.yaml as the project-root manifest (place it at the project root) instead of scaffolding from azd-ai-starter-basic or generating a new one.
2. Do not download/clone infra/ + azure.yaml from azd-ai-starter-basic; rely on bicep-less provisioning (infra.provider: microsoft.foundry) by default.
3. Do not leave an unused/duplicate azure.yaml under src/<agent-id>/.
4. Preserve existing-project behavior: if a project-root azure.yaml already exists on disk, do not overwrite it (merge/add as appropriate).

Notes / open questions

• Define the fallback when a sample does not include an azure.yaml (backward compatibility): generate the bicep-less unified azure.yaml as feat(agents): bicep-less init for azd ai agent init #8643 does today.
• Reconcile with the per-resource service split (feat(agents): split Foundry init into per-resource azure.yaml services #8675): the adopted azure.yaml should already contain the azure.ai.project / azure.ai.connection / azure.ai.toolbox + agent service entries, so init should not re-derive them.
• Decide how --src, --agent-name, and folder-naming interact when the sample's azure.yaml already names services / paths.
• Update next-step / doctor flows accordingly (tracked in Migrate next step suggestions and doctor command to make it work with unified azure.yaml #8710).

Related

• Base branch: https://github.com/Azure/azure-dev/tree/huimiu/foundry-azure-yaml
• [ext-agents]: azd ai agent init writes unified microsoft.foundry config in azure.yaml #8676 [ext-agents]: azd ai agent init writes unified microsoft.foundry config in azure.yaml
• feat(agents): bicep-less init for azd ai agent init #8643 feat(agents): bicep-less init for azd ai agent init
• feat(agents): split Foundry init into per-resource azure.yaml services #8675 feat(agents): split Foundry init into per-resource azure.yaml services
• [ext-agents]: evolve azure.ai.agent to service-level shape, retire agent.yaml, add migration #8773 [ext-agents]: evolve azure.ai.agent to service-level shape, retire agent.yaml, add migration
• [ext-foundry]: make project/connection/toolbox Foundry resources real service targets #8774 [ext-foundry]: make project/connection/toolbox Foundry resources real service targets
• Migrate rai policy to unified azure.yaml #8709 Migrate rai policy to unified azure.yaml
• Migrate next step suggestions and doctor command to make it work with unified azure.yaml #8710 Migrate next step suggestions and doctor command to make it work with unified azure.yaml

[therealjohn]

To satisfy this, we either need to support the azure.yaml as the argument or just make -m work with the azure.yaml. @trangevi thoughts on if it makes sense to re-use -m for this?