Agent Sensors

Agent sensors allow any system to self-report its status. Some common examples of possible agents:

  • IoT devices
  • 3rd party webhooks, such as a NewRelic alert webhook
  • Track server resource usage

An agent can create its own child node or add a monitor to an existing parent node. An agent may also adopt a template. Templates make it easy to configure, and manage, any sized group of nodes to behave in the same way.

If you know what you need, please visit the API docs for the /agent/ endpoint at the External Message Ingestion Service Documentation page.


You can jump right in with these examples. What are you trying to do?

  • Associate an agent monitor to a parent node
    • Useful to track, and group, multiple different types of system issues from 3rd party analytics providers (refer to Report uptime status)
  • Create a new node that lives under the parent node
    • IoT devices
    • Scalable systems that are built up / torn down depending on need
  • Report a single value, creating a single monitor
    • IoT sensors that report a single value (humidity, water level, light level, etc.)
  • Report multiple values, creating multiple monitors for each value
    • Proxies that report number of requests, number of errors, etc.
    • Machine status such as CPU, HDD, RAM, and network utilization
  • Report uptime status, create a monitor that represents the uptime status of a system
    • Integrate a 3rd party provider which reports the status of your system(s) via a webhook. The system may trigger an unhealthy state and may also (optionally) recover from an unhealthy state.
  • Adopt a template node
    • A group of systems must behave in the same way

Required Configuration

Every agent must provide the following:

  • The parent the agent is associated to
  • An “org secret” to ensure you have access to add nodes to the organization. Ask your admin for this value.
  • How the agent relates to the parent (more on this later)


An agent may relate:

  • Directly to a parent node as a new monitor. This is ideal when you want to group many (3rd party) services together on a single node.
  • As a child to the parent. This is ideal for grouping IoT devices, machines, and possibly services by a physical region, building, or floor.

A special type of relationship exists which allows more than one agent to relate to the same child node as different monitors. Please refer to the child relationship documentation for more information.

How you group nodes is up to you. ays gives you the power to manage your hierarchy in the way that best suits your needs.

I want to create a:

Values & Statuses

There are four ways to send status to ays from your agent.

  • Provide a single value. e.g. A sensor value for humidity, light, or water level
  • Provide multiple values. e.g. If monitoring a server, you may provide CPU, HDD, RAM, and Network in the same status payload.
  • Provide a health status. e.g. 3rd party analytics provider, such as NewRelic, can send a signal (via a webhook) that a threshold was breached. It can also send the recovery signal.
  • No value or status. When coupled with heartbeat configuration, this helps you know if the system is online. Obviously, this doesn’t provide any additional insight into the state of the system.

I want to configure an agent to report:


The heartbeat configuration allows you to configure your agent to alert if no signal has been received from the agent within a given timeout.


Properties are an important way to track state information on an agent. For example, an IoT device may report its IP address, firmware version, or any other configuration as a node property.

Properties may also be used by the Node API to target agent systems. For example, if the IP address of an IoT is provided, the Node API may send a request to that device to update its firmware.


There may be times when you need a group of systems to behave in the same way. Templates allow you to do this by pre-configuring alerting and monitors that an agent system will adopt.