Foundry Caphost Lifecycle

Foundry Capability Host Lifecycle — Day-2 Operations

1. Goal

This skill teaches Day-2 operations for Microsoft Foundry capability hosts: how to inspect, idempotently re-create, delete, soft-delete the parent account, purge, and redeploy without tripping the Subnet already in use failure that blocks every team that has ever torn down a VNet-injected Foundry account.

This is explicitly not greenfield create — for first-time BYO-VNet deploys see [foundry-vnet-deploy](../foundry-vnet-deploy/SKILL.md), and for the azd template flow see [foundry-hosted-agents](../foundry-hosted-agents/SKILL.md) or threadlight-deploy. This skill is the field-experience overlay on top of the MS Learn capability-hosts page (learn.microsoft.com/azure/foundry/agents/concepts/capability-hosts) that ships with the operational knowledge MS Learn does not document.

2. When to use

Trigger this skill whenever any of these are true:

• You teardown'd a Foundry VNet-injected account and now az deployment group create

fails with Subnet already in use (or SubnetIsFull referencing a serviceAssociationLink) when you try to redeploy into the same agent subnet.

• A caphost create is stuck in Creating for more than 10 minutes (the upstream

operation has a documented ~5-15 min p99; longer means hung — go to § 9).

• You need to change the connections referenced by a project capability host

(e.g., swap a Cosmos connection). MS Learn is explicit: updates are not supported; delete + recreate is the only path.

• You need to fully reclaim the soft-deleted account name within the 48h window

(so a new account can be created with the same custom domain).

• You want a clean teardown that releases the serviceAssociationLink on the agent

subnet AND removes the hidden ACA Managed Environment that the capability host provisioned under the covers.

• You have a soft-deleted account that needs to be recovered (not purged)

before the 48h window expires.

If none of those describe your situation and you're doing first-time create, stop and use [foundry-vnet-deploy](../foundry-vnet-deploy/SKILL.md) instead.

3. What MS Learn covers vs what this skill adds

MS Learn (capability-hosts) is the authoritative source for the REST API surface and create-time semantics. Use it for the contract. This skill exists because MS Learn does not cover the operational reality of Day-2.

| Concern | MS Learn | This skill | |---|---|---| | Account + project caphost REST shape (PUT/GET) | ✅ | references it | | Idempotency rules (200/400/409 matrix) | ✅ | retry pattern (§ 6) | | One caphost per scope constraint | ✅ | redeploy implications (§ 9) | | Updates not supported — delete and recreate | ✅ | safe-replace flow (§ 7) | | Account caphost prerequisite for project caphost | ✅ | inspect order (§ 5) | | DELETE caphost REST endpoint | ✅ | what it does/doesn't free (§ 7) | | Deleting caphost releases the SAL on the agent subnet | ❌ | FALSE — only purging the parent account does (§ 8, § 9) | | az cognitiveservices account purge semantics | ❌ | full sequence (§ 8) | | 48h soft-delete window + recovery | ❌ | when to recover vs purge (§ 10) | | Hidden Managed ACA Environment created by caphost | ❌ | only released on account purge (§ 8) | | Redeploy-after-teardown failure mode | ❌ | the Subnet already in use guard (§ 9) | | Concurrent-op 409 retry (currently in non creating) | ✅ pseudocode | runnable retry loop (§ 6) |

> The single most important field-verified rule: deleting a capability host > does NOT release the serviceAssociationLink on the agent subnet. Only purging > the parent Microsoft.CognitiveServices/accounts resource releases it. If you > need to redeploy into the same subnet, you MUST purge — soft-delete alone is not > enough. See § 8 and § 9 for the exact sequence and the symptom-to-fix mapping.

4. Constraints recap (from MS Learn)

Read these once. They drive every Day-2 decision below.

| Constraint | Rule | Source | |---|---|---| | One caphost per scope | Each account, each project: only one active capability host. Second host with different name → 409 Conflict. | MS Learn § Constraints | | No updates | There is no PATCH support. Configuration changes require DELETE + recreate. | MS Learn § Constraints | | Account caphost prerequisite | You cannot create a project capability host unless an account-level one already exists. | MS Learn § Constraints | | Idempotency: same-name + same-config | Returns 200 OK with the existing resource. Safe to retry. | MS Learn § Idempotent behavior | | Idempotency: same-name + different config | Returns 400 Bad Request. No silent in-place modification. | MS Learn § Idempotent behavior | | Idempotency: different name at occupied scope | Returns 409 Conflict (one-per-scope). | MS Learn § Idempotent behavior | | Concurrent operation in flight | Returns 409 currently in non creating, retry after its complete. Retry with backoff. | MS Learn § Concurrent operations | | Permissions to create / delete caphost | Contributor on the Foundry account. | MS Learn § Prerequisites | | Permissions to wire BYO connections | User Access Administrator or Owner (for assigning RBAC on the BYO resources). | MS Learn § Prerequisites | | API version | 2025-06-01 is the current canonical version this skill targets. | MS Learn REST examples | | Project caphost connection refs are by name, not resource ID | threadStorageConnections / vectorStoreConnections / storageConnections / aiServicesConnections are arrays of connection names that already exist on the project. | MS Learn § Required properties |

5. Inspect: query caphost state before any change

> Always inspect before mutating. The one-per-scope constraint and the > no-update rule mean an idempotent PUT only behaves "idempotently" if you know > what's already there. Read first, decide second.

5.1 List account-level capability hosts

GET https://management.azure.com/subscriptions/{subId}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01

Equivalent az (works for any user with Cognitive Services Contributor):

az rest --method get \
  --url "https://management.azure.com/subscriptions/${SUB}/resourceGroups/${RG}/providers/Microsoft.CognitiveServices/accounts/${ACCT}/capabilityHosts?api-version=2025-06-01" \
  --query "value[].{name:name, state:properties.provisioningState, kind:properties.capabilityHostKind}"

Expected shapes:

• value: [] — no account caphost exists. You cannot create a project caphost

until one does (§ 4 prerequisite). Go to § 6 to create one.

• value: [{name: "default", state: "Succeeded", kind: "Agents"}] — healthy.

Safe to operate on the project caphost.

• value: [{state: "Creating"}] — operation in flight. Do NOT issue another PUT;

poll the operation result (§ 5.3) until terminal.

• value: [{state: "Failed"}] — broken. DELETE it (§ 7), then recreate.

5.2 List project-level capability hosts

az rest --method get \
  --url "https://management.azure.com/subscriptions/${SUB}/resourceGroups/${RG}/providers/Microsoft.CognitiveServices/accounts/${ACCT}/projects/${PROJ}/capabilityHosts?api-version=2025-06-01" \
  --query "value[].{name:name, state:properties.provisioningState, thread:properties.threadStorageConnections, vector:properties.vectorStoreConnections, storage:properties.storageConnections, ai:properties.aiServicesConnections}"

5.3 Poll an in-flight operation

Capability-host PUT/DELETE return an Azure-AsyncOperation header with a URL of this shape:

https://management.azure.com/subscriptions/{subId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

Poll it (5-second interval, 15-minute budget — covers documented p99) until properties.status is Succeeded or Failed. Do not issue a parallel PUT or DELETE on the same scope while an operation is Running — you'll get the currently in non creating, retry after its complete 409 (§ 6).

6. Create: idempotent PUT pattern with retry

6.1 Account capability host

PUT https://management.azure.com/subscriptions/{subId}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

(For VNet-injected accounts, the customerSubnet is set at deploy time by [foundry-vnet-deploy](../foundry-vnet-deploy/SKILL.md). This skill operates on the caphost after that subnet binding already exists; it does not re-bind the subnet.)

6.2 Project capability host

PUT https://management.azure.com/subscriptions/{subId}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["my-cosmosdb-conn"],
    "vectorStoreConnections":   ["my-aisearch-conn"],
    "storageConnections":       ["my-storage-conn"],
    "aiServicesConnections":    ["my-azure-openai-conn"]
  }
}

The four *Connections arrays are connection names that already exist on the project (or are inherited from account-level), per MS Learn § "Project capability host required properties". Wrong-name → 400. Resource IDs in place of names → 400.

6.3 The retry-on-409 contract

Three distinct 409 responses, three different handling rules (per MS Learn § "HTTP 409 Conflict errors"):

# Python pseudocode using azure-mgmt-cognitiveservices
from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
from azure.core.exceptions import HttpResponseError
import time

def put_caphost_idempotent(client, rg, acct, name, body, *, max_retries=6, backoff_s=30):
    """Idempotent caphost PUT with 409-class-aware retry.

    Per MS Learn:
      - 200 on same-name + same-config (returns existing)
      - 400 on same-name + different config (no PATCH; delete + recreate)
      - 409 'existing Capability Host with name ' — different name at occupied scope
      - 409 'currently in non creating' — concurrent op; retry with backoff
    """
    for attempt in range(max_retries):
        try:
            poller = client.capability_hosts.begin_create_or_update(
                resource_group_name=rg,
                account_name=acct,
                capability_host_name=name,
                capability_host=body,
            )
            return poller.result()
        except HttpResponseError as e:
            msg = (e.message or "").lower()
            if "currently in non creating" in msg:
                # Concurrent-op 409 — wait + retry
                if attempt == max_retries - 1:
                    raise RuntimeError(f"caphost {name} still busy after {max_retries} retries") from e
                time.sleep(backoff_s)
                continue
            if "existing capability host with name" in msg:
                # Different-name 409 — this is policy, not transient. Caller decides.
                raise
            if "differs from the current configuration" in msg or "bad request" in msg:
                # 400 same-name + different-config — caller must delete first
                raise
            raise

6.4 What a 200-on-replay looks like

If you PUT the same name with the same body twice, the second call returns 200 OK with the existing resource per MS Learn § "Understand idempotent behavior". This is what makes the retry above safe: if a transient network blip hides the success of attempt N, attempt N+1 returns 200 against the now-existing resource. Field-verified in the catalog fixture (skills/foundry-caphost-lifecycle/test-fixture/consumer_prompt.md step 4).

7. Delete: caphost-only (lightweight, keeps account)

7.1 When to use this path

DELETE the capability host (without deleting the parent account) when:

• You need to change a connection reference (Cosmos, Search, Storage, AOAI)

on a project caphost. MS Learn is explicit that updates are not supported, so the only path is DELETE + recreate.

• You're tearing down agents for a project but want to keep the Foundry account,

models, other projects, etc.

• The caphost is in Failed or stuck Updating state and you need a clean slate.

7.2 DELETE caphost REST

DELETE https://management.azure.com/subscriptions/{subId}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

(For project scope, insert projects/{projectName}/ between accounts/{accountName}/ and capabilityHosts/.)

The response is 202 with an Azure-AsyncOperation header. Poll per § 5.3 until Succeeded (typical: 30s-2min; p99 ~5min). Then verify with GET — expect 404.

# verify gone
az rest --method get \
  --url "https://management.azure.com/subscriptions/${SUB}/resourceGroups/${RG}/providers/Microsoft.CognitiveServices/accounts/${ACCT}/capabilityHosts/${NAME}?api-version=2025-06-01"
# expect HTTP 404 ResourceNotFound

7.3 What DELETE caphost DOES free

• The caphost resource itself (the per-scope Microsoft.CognitiveServices/accounts/capabilityHosts object).
• The project's runtime binding to the listed connections.
• After deletion, agents in that project will no longer have access to the BYO

thread/file/vector resources the caphost pointed to (MS Learn § "Delete capability hosts" Warning).

7.4 What DELETE caphost DOES NOT free (field-verified)

• The serviceAssociationLink on the agent subnet (only account purge does — § 8).
• The hidden Microsoft.App Managed Environment resource that the caphost

provisioned to host agent compute (only account purge does — § 8).

• Any account-level RBAC or connection definitions.
• Soft-delete state on the account if the account itself is soft-deleted.

This asymmetry is the single biggest gotcha in Foundry Day-2 ops. If you delete the caphost expecting to redeploy a new one into the same agent subnet, you will hit Subnet already in use on the next deploy — see § 9.

8. Soft-delete + purge: full account teardown

8.1 Why this matters (the rule)

> Field-verified rule: the serviceAssociationLink (SAL) that a VNet-injected > Foundry account holds on its agent subnet is only released when the parent > Microsoft.CognitiveServices/accounts resource is fully purged — not when > the capability host is deleted, and not when the account is soft-deleted. If > you intend to redeploy into the same subnet, you MUST complete the soft-delete > + purge sequence below.

This is true for **any

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aiappsgbb
• Source: aiappsgbb/awesome-gbb
• License: MIT

Install and usage instructions live in the source repository linked above.