Domotz Agents git:20260728.b7e78fcA

Immutable. This exact content never changes and is served at /api/v1/blob/3caea324bd7adec5.

---
name: "Domotz Agents"
description: >
  Domotz agents (collectors/probes) as the per-site entry point for all device
  and network operations: agent types, lifecycle, ONLINE/OFFLINE status, the
  list/get tools and their license and last-seen fields, and fleet health,
  site inventory, and capacity-planning workflows.
when_to_use: >-
  When listing agents, checking collector health, or working with Domotz sites.
  Use when: domotz
  agent, domotz collector, domotz site, domotz probe, agent health, agent status, agent list,
  collector management, or site management.
---

# Domotz Agents

## Overview

Domotz agents (also called collectors or probes) are software or hardware appliances deployed at customer sites that perform network discovery, device monitoring, and data collection. Each agent represents a monitored site/location and is the entry point for all device and network operations.

## Key Concepts

### Agent Types

- **Software Agent** - Installed on a VM or physical machine at the site
- **Domotz Box** - Dedicated hardware appliance
- **Virtual Appliance** - Pre-configured VM image

### Agent Lifecycle

Agents are deployed at customer sites and maintain a persistent connection to the Domotz cloud. Each agent:
- Discovers and monitors devices on local networks
- Runs scheduled and on-demand network scans
- Executes Domotz Eyes sensor checks
- Reports alerts and status changes

### Agent Status

| Status | Meaning |
|--------|---------|
| `ONLINE` | Agent is connected and reporting |
| `OFFLINE` | Agent is not connected to the cloud |

## API Patterns

### List Agents

```
domotz_list_agents
```

Returns all agents associated with your account.

**Example response:**

```json
[
  {
    "id": 12345,
    "display_name": "Acme Corp - Main Office",
    "status": {
      "value": "ONLINE"
    },
    "license": {
      "bound_devices": 47
    },
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "last_seen": "2026-03-27T15:30:00Z"
  }
]
```

### Get Agent Details

```
domotz_get_agent
```

Parameters:
- `agent_id` -- The specific agent ID

**Example response:**

```json
{
  "id": 12345,
  "display_name": "Acme Corp - Main Office",
  "status": {
    "value": "ONLINE"
  },
  "license": {
    "bound_devices": 47,
    "allowed_devices": 100
  },
  "access_right": {
    "api_enabled": true
  },
  "creation_time": "2025-01-15T10:00:00Z",
  "last_seen": "2026-03-27T15:30:00Z"
}
```

## Common Workflows

### Fleet Health Check

1. Call `domotz_list_agents` to get all agents
2. Group by status (ONLINE/OFFLINE)
3. Flag agents not seen in >1 hour as potentially unhealthy
4. Check `license.bound_devices` vs `license.allowed_devices` for capacity

### Site Inventory

1. Call `domotz_list_agents` to get all sites
2. For each agent, note `display_name`, status, and bound device count
3. Build a summary table of all monitored sites

### Agent Capacity Planning

1. List all agents
2. Compare `bound_devices` to `allowed_devices` for each
3. Flag agents approaching their device limit
4. Recommend license upgrades where needed

## Error Handling

### Agent Not Found

**Cause:** Invalid agent ID or agent has been deleted
**Solution:** Verify the agent ID; check if the site was decommissioned

### Agent Offline

**Cause:** Network connectivity issue, agent service stopped, or hardware failure
**Solution:** Check site connectivity; verify agent service is running; contact site contact

### Empty Agent List

**Cause:** No agents deployed or API key has limited scope
**Solution:** Verify API key permissions; check Domotz Portal for agent list

## Best Practices

- Monitor `last_seen` timestamps to detect offline agents early
- Track `bound_devices` vs `allowed_devices` for license planning
- Use `display_name` consistently with client site names in your PSA
- Cross-reference agent sites with RMM site structures
- Set up alerts for agent offline events in Domotz

## Related Skills

- [api-patterns](../api-patterns/SKILL.md) - Pagination and rate limiting
- [devices](../devices/SKILL.md) - Devices monitored by agents
- [alerts](../alerts/SKILL.md) - Alerts generated by agents
- [network](../network/SKILL.md) - Network scanning via agents
- [eyes](../eyes/SKILL.md) - Sensors running on agents