Manual Post-Deployment Setup for Dialogs and Python Agents

Before you begin, collect the following from the deployed resource group:

You can also retrieve a principal ID via Azure CLI:

az identity show --resource-group <rg> --name <mi-name> --query principalId --output tsv

ADLS Gen2 uses POSIX-style ACLs. Parent directories require execute (--x) for traversal, and listing a directory requires read + execute (r-x). Write permissions are needed only on the specific subdirectories where the agents produce data.

Apply the following access ACL entries. Where “default ACL” is listed, also add the same permissions under the Default permissions tab so newly-created children inherit them.

The Code Executor needs read access to setup/conf (to download its bundle) and read/write/execute on its own log subfolder logs/codeexecutorlogs (with execute-only traversal on the parent logs directory), plus traversal on the parents. It does not require any access under dialogs/.

Permission required: Storage Blob Data Owner on the storage account. Storage Blob Data Contributor is NOT sufficient: it can read/write blob content but cannot set ACLs on items it does not own.

1. Navigate to your storage account in the Azure portal.

2. In the left blade, open Storage browser.

3. Expand Blob containers and click your Kyvos container name.

4. Apply ACL on the container root FIRST: in Storage browser, right-click the container itself (the row above 'user') → Manage ACL → add the agent MI with Execute only (--x). Then right-click the user folder → Manage ACL. If the folder does not exist yet, create it with + New folder at the top of the container. Repeat for each parent in the path you intend to ACL.

5. In the Manage ACL blade:

   1. Click + Add principal.

   2. Search for the agent MI by name (kyvos-dialogs-agent-mi-<UniqueNumber> or kyvos-code-executor-mi-<UniqueNumber>).

   3. Select it and click Add.

   4. Under the Access permissions tab, set the Read / Write / Execute checkboxes according to the ACL Model above.

   5. For the rwx + default rwx rows (tmp, saved, logs): switch to the Default permissions tab and check Read / Write / Execute there too.

   6. Click Save.

6. Repeat steps 4–5 for every directory in the ACL Model, walking shallowest (/user) to deepest (.../dialogs/deepdive/chatsessions/saved).

7. If you also deployed the Code Executor, repeat the entire procedure for the Code Executor MI on its (shorter) path list.

In the Storage browser, right-click any path → Manage ACL and confirm the agent MI is listed under Security principal with the expected R/W/X checkboxes.

Alternatively, from Azure CLI on a machine with VNet line-of-sight to the storage account:

az storage fs access show \
  --account-name <storage-account> \
  --file-system <container> \
  --path user/engine_work/logs \
  --auth-mode login

Look for user:<principal-id>:rwx in the returned acl field.

The Dialogs Agent MI needs get, wrapKey, unwrapKey, encrypt, decrypt on the Key Vault keys. The Code Executor MI (if deployed) needs get, unwrapKey, decrypt (read-only crypto operations on encrypted data).

How you grant this depends on the Key Vault's permission model. Note: for Vault-access-policy Key Vaults, the deployment adds these entries automatically when 'Is Encryption enabled' is on, so this section is mainly a fallback (or for verification). For Azure RBAC Key Vaults, the automatic step does not apply and you must grant access manually as below.

1. Navigate to the Key Vault in the Azure portal.

2. Open Access configuration in the left blade.

3. Note the value of Permission model — either Vault access policy (legacy) or Azure role-based access control (RBAC).

Permission required: Owner or Contributor on the Key Vault, or any role that can add access policies (e.g. Key Vault Administrator).

1. In the Key Vault, open Access policies.

2. Click + Create.

3. Permissions tab → under Key permissions:

   1. Dialogs Agent MI: check Get, Wrap Key, Unwrap Key, Encrypt, Decrypt.

   2. Code Executor MI (separate policy): check Get, Unwrap Key, Decrypt.

   3. Leave Secret permissions and Certificate permissions blank. Click Next.

4. Principal tab → search for the agent MI by name → select it → Next.

5. Application (optional) tab → leave blank → Next.

6. Review + create → Create.

7. Repeat for the Code Executor MI if applicable. Each MI gets its own policy entry.

Permission required: User Access Administrator (or any role that can assign Azure RBAC roles on the Key Vault).

1. In the Key Vault, open Access control (IAM).

2. Click + Add → Add role assignment.

3. For the Dialogs Agent MI:

   • Role tab → search and select Key Vault Crypto User.

   • Members tab → Assign access to Managed identity → + Select members → pick the Dialogs Agent MI → Select.

   • Review + assign.

4. Repeat for the Code Executor MI:

   • Role tab → Key Vault Crypto User also covers the read-only ops the Code Executor needs.

   • Alternatively, for least privilege, assign Key Vault Crypto Service Encryption User (grants only unwrapKey).

   • Members tab → select the Code Executor MI → assign.

Run one of the following from any machine with management-plane access to the Key Vault.

• Vault access policy mode:
  az keyvault show --name <vault-name> \
    --query "properties.accessPolicies[?objectId=='<dialog-mi-principal-id>'].permissions.keys" \
    --output tsv
  # Expected output: get wrapKey unwrapKey encrypt decrypt

• RBAC mode:
  az role assignment list \
    --assignee <dialog-mi-principal-id> \
    --scope /subscriptions/<sub-id>/resourceGroups/<vault-rg>/providers/Microsoft.KeyVault/vaults/<vault-name> \
    --query "[].roleDefinitionName" --output tsv
  # Expected output: Key Vault Crypto User

Separately from the key permissions above, when a Vault name is supplied the deployment automatically adds an access policy that grants the Dialogs Agent MI get and list on the Key Vault secrets (the accessPolicy-dialogs-kv-secret-* deployment). No manual action is required — this note is for reference only. The manual step in 2.2 still leaves Secret permissions blank, because secrets are handled by this automatic policy entry.

To verify (vault access policy mode:

az keyvault show --name <vault-name> \
  --query "properties.accessPolicies[?objectId=='<dialog-mi-principal-id>'].permissions.secrets" \
  --output tsv
# Expected output: get list

The agent VMSS bootstrap downloads its bundle and venv on first boot. If the ACLs or KV access policies were missing at boot time, the agents will have failed silently. To trigger a fresh bootstrap on existing instances:

1. Navigate to the agent VMSS (e.g. kyvos-dialogs-agent-<UniqueNumber>)

2. Open Instances → select the VM → Reimage.
   Or, for a fresh deployment, scale the VMSS from 0 → 1 (since sku.capacity = 0 by default):

3. Scaling blade → Manual scale → set instance count to 1 → Save.

4. The first instance will boot, pick up the new ACLs and KV access, and start the agent.

• Collected MI principal IDs for Dialogs Agent (and Code Executor if applicable)

• Created the directory tree under /user/engine_work/ if any paths didn’t exist

• Applied access ACLs on all paths in the ACL Model (shallowest → deepest)

• Applied default ACLs on tmp, saved, logs directories

• Verified one ACL via az storage fs access show or the portal

• Determined Key Vault permission model (access policy vs RBAC)

• Added Dialogs Agent MI to Key Vault with get, wrapKey, unwrapKey, encrypt, decrypt

• Added Code Executor MI to Key Vault with get, unwrapKey, decrypt (if deployed)

• Confirmed the automatic secret access policy grants the Dialogs Agent MI get, list on Key Vault secrets

• Scaled the VMSS up or reimaged existing instances to trigger a fresh bootstrap