Deploying Python Agents VMSS through Azure Portal

Before you open the Azure portal, decide the answers to two independent questions. Each maps to a checkbox on the Basics tab. These are now SEPARATE — you can enable either one, both, or neither.

1. Log in to your Azure Portal, with the user having sufficient permissions.

2. On the Home page, click Cloud Shell.  

3. Upload the DialogsAndCodeExecutorAgentsUiDefinition.json and DialogsAndCodeExecutorAgents.json templates (Available in Azure Installation Files) by clicking the Upload button.

4. After uploading the template, in the Cloud Shell Area, execute the following command to create Template Specs.
   az ts create --name <TemplateSpecName> --version <“VersionNumber”> --resource-group <Resource Group name> --location <“Location”> --template-file "MainTemplatePath" --ui-form-definition "FormFilePath"

   For example,

   az ts create --name kyvosspec --version "v1.0.33" --resource-group Kyvos_RG2 --location "Central US" --template-file "./DialogsAndCodeExecutorAgents.json" --ui-form-definition "./DialogsAndCodeExecutorAgentsUiDefinition.json"  

5. Close the Cloud Shell and in the Search box, click Template Specs. The Template Specs page is displayed.

6. On the Template Specs page, search the Template Specs that you have created in Step 4, as mentioned above.

7. Browse the selected Template Spec and then click the Deploy option to open the deployment form.

8. Enter details as:

7. After completing the information on the Tags tab, click Next, and this displays the Review + Create page. The system validates your inputs and displays a summary of the provided inputs. 

8. Review the summary. The portal will run a final validation.

9. Click Create. The deployment usually finishes in 5–10 minutes. You can leave the page open or come back later (the status persists in Resource group → Deployments).
   
   

If you left BOTH 'Firewall enabled on Storage account' AND 'Is Encryption enabled' unchecked — and you let the deployment create the managed identities (the default) — no manual steps are required. The deployment has already:

• Created the managed identities.

• Granted each managed identity a self-scoped role assignment so the VM can resolve its own client ID at boot.

• Applied ADLS Gen2 ACLs on the storage paths automatically (via a temporary ACL-setter identity that removes its own access when finished).

• Created the VMSS resources with 0 instances.

Skip to Section 6 (Starting the agents).

Two manual procedures may be needed depending on which toggles you enabled. They are INDEPENDENT — if only one toggle is on, you only need one procedure: (1) If 'Firewall enabled on Storage account' was ON, you must apply ADLS Gen2 ACLs manually (Section 5.1–5.3). (2) If 'Is Encryption enabled' was ON, you may need to grant the agent managed identities access on your Key Vault (Section 5.4). Without these, the affected feature(s) will fail — bundles won't download (ACL miss) or decryption won't work (Key Vault miss).

Without those, the agents will fail to download their bundles and fail to decrypt data. You will need to complete the applicable step(s) before scaling the VMSS up.

You have two options. Pick the one that matches your environment:

Use this option if you have a jumpbox / dev VM that can reach your storage account.

1. Open apply-agent-acls.sh in a text editor (Notepad, VS Code, vim, anything).

2. Fill in the five variables at the top of the file:

   1. STORAGE_ACCOUNT — the name of your Kyvos storage account.

   2. CONTAINER — the name of the container inside it.

   3. KYVOS_WORK_DIR_RAW — usually /user/engine_work/

   4. DIALOGS_PRINCIPAL_ID — the object ID of the Dialogs Agent managed identity.

   5. CODE_EXECUTOR_PRINCIPAL_ID — the object ID of the Code Executor managed identity (leave empty if you didn't deploy Python Agents).

To find a managed identity's object ID:

1. In the Azure portal, navigate to your resource group.

   • Find the user-assigned managed identity (named like kyvos-dialogs-agent-mi-XXXX).

   • On its Overview blade, copy the Object (Principal) ID.

2. Copy apply-agent-acls.sh to your jumpbox (any way: SCP, RDP+copy, OneDrive, etc.).

3. On the jumpbox, run:
   chmod +x apply-agent-acls.sh
   az login
   ./apply-agent-acls.sh

4. Watch the output. The script ends with: Agent ACL configuration complete.

Use this option if you do not have a jumpbox. The detailed click-by-click instructions are in MANUAL_SETUP.docx — Section 1.2. Open that document and follow it.

Regardless of whether you used Option A or B for ACLs, you may also need to grant the agent managed identities access to your Key Vault. Note: if your Key Vault uses the legacy "Vault access policy" model, the deployment already added these access-policy entries automatically — this manual step is then only needed if that automatic step was skipped or failed. If your Key Vault uses the modern "Azure RBAC" model, the automatic step does not apply and you must grant access manually.

Open MANUAL_SETUP.docx — Section 2 and follow it. It covers both modes.

The deployment created the VMSS resources with 0 instances. You need to scale up to 1 to actually start an agent. Do this for each VMSS you deployed.

1. In the Azure portal, navigate to your resource group.

2. Click on the agent VMSS (named like kyvos-dialogs-agent-XXXX).

3. In the left blade, click Scaling.

4. Make sure Manual scale is selected (it is the default — no autoscale rules are configured).

5. Set the instance count to 1.

6. Click Save at the top.

7. Wait 3–5 minutes. Azure will provision a VM and the bootstrap script will run automatically: install Python 3.12, mount the data disk, download the agent bundle, extract the Python venv, and launch the agent.

8. Repeat for the Code Executor VMSS if you deployed it.

Use these quick checks to confirm everything is up:

1. Navigate to the VMSS → Instances → click an instance. Note its private IP address (the VM doesn't have a public IP by default).

2. From a jumpbox or VPN-connected machine: ssh adminuser@<private-ip> using the SSH key you provided on the Basics tab.

3. Useful files once you're in:

   • /tmp/bootstrap_logs.out — full bootstrap log.

   • /data/kyvos/app/kyvos/<agent-name>/logs/ — agent runtime logs.

   • /data/kyvos/app/kyvos/<agent-name>/bin/start-<agent>.sh — startup script (useful to verify USER_ASSIGNED_CLIENT_ID was substituted correctly).