fix(template-15): deploy fails with HTTP 409 because we PUT a second account-level capability host that the Cognitive Services resource provider already auto-created (closes #312)

[KazuOnuki]

TL;DR

• Bug: Deploying the 15-private-network-standard-agent-setup template fails with HTTP 409 on the caphostacct step.
• Why: The Cognitive Services resource provider (Microsoft.CognitiveServices) silently auto-creates an account-level capability host named {account}@aml_aiagentservice whenever the account is created with networkInjections.scenario='agent' (which this template always does). Our explicit addAccountCapabilityHost module then tries to PUT a second one called caphostacct — but only one capability host per account is allowed, so the resource provider rejects it.
• Fix: Delete the addAccountCapabilityHost call from this template's main.bicep. The auto-created @aml_aiagentservice capability host is sufficient — the project capability host binds to it cleanly and the whole deploy succeeds.

---

The bug you'll hit

Deploy this template against a clean subscription today, and the caphostacct sub-deployment fails with this exact error from the Cognitive Services API:

There is an existing Capability Host with name: <accountName>@aml_aiagentservice,
provisioning state: Succeeded for workspace: ...
cannot create a new Capability Host with name: caphostacct for the same ClientId.

This is the symptom reported in #312 and several other open issues (#254, #255, #265 all show the same for the same ClientId text).

---

Why it happens

The resource provider has a hidden behavior:

account PUT with networkInjections.scenario='agent'
     ↓  (~5 seconds later, no extra API call required)
account-level capability host named "{accountName}@aml_aiagentservice"
auto-appears under GET /capabilityHosts

Once that auto-created capability host exists, any other account-level capability host PUT — even with a different name like caphostacct — returns 409, because each account can hold only one capability host (documented constraint: "Each account can have only one active capability host. If you try to create a second capability host with a different name at the same scope, you'll receive a 409 error").

I verified the auto-create trigger on a clean subscription:

Test account	Created with networkInjections.scenario='agent'?	Account capability host ~5s after create
Control #1	x No	(empty list)
Control #2	x No	(empty list)
Control #3	x No	(empty list)
Control #4	x No	(empty list)
This template	o Yes (via ai-account-identity.bicep)	{name}@aml_aiagentservice appears

So the moment this template's ai-account-identity.bicep finishes, we already have an account capability host — and the addAccountCapabilityHost step is guaranteed to collide.

---

Why the existing code looked correct

addAccountCapabilityHost was added in #261 to support BYO / basic-setup scenarios where the account does not auto-create a capability host. That intent is still valid for sibling templates. The author had no way to know that this template — because of its networkInjections.scenario='agent' flag — already gets one for free, because:

• networkInjections schema (scenario, subnetArmId, useMicrosoftManagedNetwork) is documented in the Bicep / ARM reference and in the REST API spec (2025-04-01-preview, PR #32877 Mar 2025, PR #36395 Aug 2025).
• The side effect of scenario='agent' (auto-creating @aml_aiagentservice) is not documented anywhere public — not in virtual-networks, not in use-your-own-resources.

Two unrelated edits — adding networkInjections here, and adding addAccountCapabilityHost in #261 — therefore silently collide. This PR also adds an inline block comment in main.bicep so the next maintainer doesn't re-introduce the same conflict.

---

The fix (concrete changes)

In infrastructure/infrastructure-setup-bicep/15-private-network-standard-agent-setup/:

main.bicep (33 ins / 25 del):

• Delete the addAccountCapabilityHost module block (the one that PUTs caphostacct).
• Delete the 4 helper vars that only existed to compute that module's scope:
  useExistingAccount, existingAccountIdParts, existingAccountSubscriptionId, existingAccountResourceGroupName.
• Remove the addAccountCapabilityHost entry from addProjectCapabilityHost.dependsOn.
• Add a block comment explaining: "This template does not create an account-level capability host. The resource provider auto-creates {account}@aml_aiagentservice because we set networkInjections.scenario='agent'. The project capability host below binds to that auto-created one."

README.md (6 lines changed):

• Notes / Cleanup / Module table sections updated from "declaratively created by add-account-capability-host.bicep" to "auto-created by the resource provider via networkInjections.scenario='agent'".

After this PR, addProjectCapabilityHost still depends on aiProjectModule, which depends on aiAccount (which is when the auto-create fires). So the ordering is preserved without addAccountCapabilityHost in the chain.

---

What I intentionally did NOT delete

modules-network-secured/add-account-capability-host.bicep is kept even though this template no longer calls it. Reason: PR #261 added it for BYO / basic-setup templates that do not pass networkInjections.scenario='agent' and therefore really do need to declare their own account capability host. Removing the file would regress those templates. grep -r add-account-capability-host confirms no other current external callers, but the file is preserved for the documented BYO scenario.

---

Validation

Check	Result
Reproduce the original 409 on a freshly created account with networkInjections.scenario='agent' (no Portal, no SDK, no prior deploy)	o 409 for the same ClientId reproduced
Confirm an account without networkInjections does NOT auto-create any capability host (4 control accounts)	o All 4 show empty capability host list
Trace the internal resource provider chain via service logs	o account PUT → VirtualWorkspace/CreateOrUpdateWorkspace 202 → NotifyCapabilityHost 202 (same operation_Id) → {name}@aml_aiagentservice visible via GET /capabilityHosts
Fresh end-to-end deploy of the patched template in a clean RG (japaneast, 2026-06-04) — variant A: if (false) guard	o 15/15 sub-deployments Succeeded
Fresh end-to-end deploy — variant B: this PR's clean removal	o 20/20 sub-deployments Succeeded, PT19M0.87S
After deploy: {account}@aml_aiagentservice exists, project capability host bound to vectorStore/storage/threadStorage connections, caphostacct GET returns 404 (because we never PUT it)	o All confirmed
az bicep build main.bicep	o 0 warnings related to this change
Compiled main.json contains no caphostacct / addAccountCapabilityHost / add-account-capability-host references	o Confirmed

---

Related issues

• Closes capabilityHost error with bicep script #312 (primary symptom)
• Likely fixes Deployment fails at capability host step #254 / Conflict during Cognitive services account creation #255 / What is happening when capabilityHost is being created. #265 — all three show the same for the same ClientId 409 error string
• Builds on Force-replace project capability host on changes #261 — does not remove the add-account-capability-host.bicep module file, preserving Force-replace project capability host on changes #261's BYO / basic-setup intent for sibling templates

[haflidif]

Thanks @KazuOnuki — this is excellent root-cause work, especially the control-account matrix proving the RP auto-creates {account}@aml_aiagentservice from networkInjections.scenario='agent', and the RP-chain trace. That mechanism writeup is genuinely valuable.

I'm going to close this PR without merging, for two reasons:

1. The 409 is already prevented on main. The account-level capability host is now gated behind an opt-in parameter (added in #438):

param createAccountCapabilityHost bool = false
module addAccountCapabilityHost '...add-account-capability-host.bicep' = if (createAccountCapabilityHost) { ... }

Because it defaults to false, a normal deploy never PUTs caphostacct, so the collision in #312 / #254 / #255 / #265 doesn't occur. Your PR's base predates this gate, which is why the diff still shows the unconditional module.

2. Full removal would regress the BYO path. Deleting the module (rather than gating it) removes the escape hatch for non-network-secured / BYO accounts that legitimately need to declare their own account caphost — the exact scenario #261 added it for. The opt-in gate keeps both paths working.

What I am taking from here is your documentation — the precise root-cause explanation is clearer than what's currently in the template comment/README, and I've ported it into the template (comments + README) with attribution to you.

Net: the deployment failure you hit is already fixed on main by the default-off gate; please pull latest and confirm. Thanks again for the deep investigation. 🙏

[haflidif]

Closing per the note above — the 409 is already prevented on main by the default-off createAccountCapabilityHost gate (#438), and the root-cause docs from this PR have been ported into the template. Reopen if you hit the collision on latest main. Thanks again @KazuOnuki!