> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Agent configuration for host mode and VM mode

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.

```json theme={null}
"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, so you don't need to provide them.

```json theme={null}
"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. 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

```json theme={null}
"agents": [
  { "agent_name": "web-agent", "host_name": "web-01", "specialty_key": "SERVICES_MANAGER" },
  { "agent_name": "db-agent",  "host_name": "db-01",  "specialty_key": "SQL_SERVER_MANAGER" }
]
```

***

## Field Reference

| Field           | Mode     | Description                                                                    |
| --------------- | -------- | ------------------------------------------------------------------------------ |
| `agent_id`      | host     | Reuse an existing agent from the DB. If provided, the agent is not re-created. |
| `agent_name`    | VM / new | Display name for the agent. Required when creating a new agent.                |
| `host_name`     | all      | Links this agent to a host defined in the `hosts` array.                       |
| `host_id`       | host     | Alternative to `host_name`: link to a host by its DB ID.                       |
| `specialty_key` | VM / new | Specialty key for the agent (e.g. `SERVICES_MANAGER`, `KUBERNETES_OPERATOR`).  |