Skip to main content
The agents array in scenario.json tells the runner which agents execute the scenario. Like hosts, how you define an agent depends on the execution mode.

​
Host Mode (--mode host)

In host mode, you reference an existing agent already registered in your 2501 deployment. The runner flushes the agent’s memory before execution to ensure a clean slate, then leaves the record untouched after the run. 
"agents": [
  {
    "agent_id": "agt_xyz789",
    "host_name": "web-01"
  }
]
Find agent IDs in the Command Center or via the API. host_name must match a host_name defined in the hosts array (or use host_id directly if preferred).

​
VM Mode (--mode incus / --mode lima)

In VM mode, hosts are ephemeral VMs created fresh for each run, so agents are also defined inline and created from scratch. The runner injects SSH credentials automatically — you don’t need to provide them. 
"agents": [
  {
    "agent_name": "web-agent",
    "host_name": "web-01",
    "specialty_key": "SERVICES_MANAGER"
  }
]
What the runner does for each run:
  1. Creates a new agent record in the DB with the provided fields
  2. Injects SSH credentials for the provisioned VM automatically
  3. Flushes memory at run start
  4. Removes the agent record from the DB after the run
The host_name must match a host_name defined in the hosts array.

​
Multiple Agents

"agents": [
  { "agent_name": "web-agent", "host_name": "web-01", "specialty_key": "SERVICES_MANAGER" },
  { "agent_name": "db-agent",  "host_name": "db-01",  "specialty_key": "DATABASE_MANAGER" }
]

​
Field Reference

FieldModeDescription
agent_idhostReuse an existing agent from the DB. If provided, the agent is not re-created.
agent_nameVM / newDisplay name for the agent. Required when creating a new agent.
host_nameallLinks this agent to a host defined in the hosts array.
host_idhostAlternative to host_name: link to a host by its DB ID.
specialty_keyVM / newSpecialty key for the agent (e.g. SERVICES_MANAGER, KUBERNETES_OPERATOR).