Domotz Agents

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:

[
  {
    "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:

{
  "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