Agents are project-wide services configured in the Agents view (Ctrl+4). Add one with the Add button, configure it there, then use its events and commands in the Programming view. Under the hood an agent is a driver flagged as an agent, and most allow only one instance per project. Third-party agents install the same way as drivers, from Documents\Control4\Agents.
Agents catalog overview
Common agents (names and availability vary by OS version):
- Scheduler: time and sunrise/sunset events.
- Advanced Lighting Scenes: lighting scenes with tracking and keypad LEDs.
- Wakeup/Goodnight (Wake/Sleep): homeowner-adjustable wake and sleep routines per room.
- Announcements: play a sound or show text on an event.
- Media Scenes: multi-room music presets.
- Timer: countdown timers with events.
- Variables: custom Boolean, Number, and String variables.
- Macros: reusable named scripts.
- Custom Buttons: Navigator buttons that fire programming.
- Screen Saver: touch screen screensaver.
- Communication / Intercom: intercom groups for touch screens, door stations, and the app.
- Push Notification and Email Notification: alerts to the homeowner.
- Access: restrict UI items behind a PIN or by user.
- Backup: scheduled cloud backups.
- History: event history for drivers that support it.
- UI Configuration and Navigation: wallpapers and Navigator behavior.
- Newer OS: Routines and Home Screen (X4), Driver Migration (OS 4.1, for moving lighting to Lux), MultiDisplay Manager (video walls and multi-display rooms).
Scheduler agent
For anything on the clock. Add an event with a name, a fixed time or sunrise/sunset (with offset and optional randomize), a start date, and repeat rules (daily, weekly on chosen days, monthly, yearly) with an optional end date. Then program the event in Programming view under Scheduler.
Gotchas:
- Sunrise and sunset come from the project location and time zone. Wrong ZIP or time zone means wrong times. Check project properties first.
- Randomize shifts the time each day (useful for away lighting) but makes testing confusing. Turn it off while testing.
- A scheduled script still runs when the family is on vacation unless you gate it with a mode variable.
- After an OS update, confirm schedules fire. Early X4 builds had a scheduler reliability bug fixed in OS 4.1.
- Daylight saving changes are handled by the time zone setting; a controller with the wrong time zone will drift an hour twice a year.
Wakeup/Goodnight (Wake/Sleep) agent
Lets the homeowner set a wake time and sleep timer per room from the app or a touch screen. Per room you choose which lights ramp and how fast, which media source and station to play, which shades open, active days, and whether each feature is visible and enabled for the homeowner.
Gotchas:
- The homeowner owns the times. Do not also schedule the same lights in the Scheduler or they will fight.
- The media source must already work in that room (valid path to the room's audio endpoint).
- Wake events are programmable, so you can add actions the agent does not offer (thermostat, coffee maker relay).
- An older Wakeup agent exists on some systems. Use the newer one for new work.
Advanced Lighting Scenes agent
The right way to build lighting scenes. Create a scene, add loads, and set per load: level, ramp rate, delay, and tracking. Scenes can be sequences (steps with timing) and can flash.
Key settings:
- Tracking decides when the scene counts as active: load off, load on, on at a level, or at the scene's final level. Keypad LEDs follow this.
- Toggle scene: the scene to run when a toggle button turns this scene "off" (often an All Off or a walk-off scene).
- Sync this scene: captures current load levels into the scene. Fast for setting a look by eye.
- Active and inactive LED colors for keypads.
Gotchas:
- If an LED never lights, a tracked load is not at its scene level (often a load that another script changed, or a load set to track at a level it never reaches due to ramp or trim).
- Do not drive the same loads from both a scene and per-load programming on the same button.
- Large scenes on big ZigBee meshes can look staggered. Newer lighting supports broadcast scene commands that fire together; older gear sends per-load.
- Test with Activate Scene in the agent before programming buttons.
Announcements agent
Plays an audio file or shows a text message on Navigators when you fire it from programming. Use for doorbell chimes, "garage door left open", or reminders.
Gotchas:
- Audio announcements play in rooms with a working audio path and can interrupt or duck what is playing. Decide per room.
- Keep files short and in a supported format. Upload them in the agent.
- Volume for announcements is separate from normal listening volume on most systems. Set it, or a chime will blast or be inaudible.
- Text announcements depend on Navigators being active. They are not a reliable alert path for someone away from home; use push notifications.
Media Scenes agent
Saves a multi-room music preset: which rooms, which source, and each room's volume. One command starts the whole house on a playlist or turns the scene off.
Gotchas:
- Every room in the scene needs a valid audio path from that source.
- Streaming services that cannot play the same stream in several zones may not behave as a shared group. Use a source that supports multi-zone or a single feed distributed by a matrix amp.
- Rooms joined by the scene may still be controlled individually; a user turning one off does not end the scene in others.
Timer agent
Countdown timers with start, stop, reset, and expired events. Use timers instead of Delays any time the wait must be cancellable or restartable.
Examples: closet light off 10 minutes after door opens (restart on each open), bath fan off 20 minutes after the light goes off, "garage door still open" alert after 15 minutes.
Gotchas:
- Restarting a running timer resets the countdown, which is what you usually want for occupancy.
- Program both the expire action and the cancel condition (stop the timer when the door closes).
- Name timers by purpose so you can find them in programming.
Variables agent
Custom variables for programming state. Common types are Boolean, Number, and String; some versions offer more. Create with New, pick type and name, and set the initial value.
Gotchas:
- Values survive normal restarts. After an abnormal power loss, re-initialize from the project's system startup event.
- Changing a variable fires an event. Programming that reacts to a change and also sets the same variable can loop.
- Name variables by meaning (House Mode, Movie Active), not by device.
Macros and Custom Buttons agents
Macros: a named script you call from anywhere. Program the macro once (Programming > Device Events > macro > When executed). Use for mode changes, All Off, Goodnight, Leaving, and anything triggered from more than one place.
Custom Buttons: buttons on Navigators in a room's menus (for example Comfort or Watch), each with a pressed event to program. Set an icon and name, make sure the button is Visible in the room's Navigator menu settings, and refresh Navigators.
Gotcha: experience buttons and custom buttons can be added Hidden by default. If it does not show, check the room's Navigator visibility, use Apply To for other rooms, and refresh.
Screen Saver agent
Controls the screensaver on touch screens (and on-screen interfaces on systems that still have them): mode (photos, clock, blank), timing, and the photo source.
Gotchas:
- Photo sources must be reachable from the touch screen.
- Too short a timeout annoys customers; too long leaves bright screens on in bedrooms. Night mode or backlight settings may be better for bedrooms.
- Touch screen models behave differently. Older T3 touch screens are not supported going forward on X4 (OS 4.x is their terminal release).
Intercom and the Communication agent
The Communication agent (and the older Intercom setup) defines who can call whom: touch screens, door stations, and the Control4 app (Intercom Anywhere on supported versions). Configure call groups, door station behavior, auto-answer, and do-not-disturb defaults.
Gotchas:
- Intercom depends on a solid network: wired touch screens, multicast-friendly switches, and no client isolation on Wi-Fi for app clients.
- Door station video to phones works through the cloud and needs the right subscription on newer systems.
- Test calls in both directions and from outside the home network at handoff.
Push and email notifications
Push Notification agent: sends alerts to the Control4 app. Create notifications in the agent, then fire them from programming (door left open, leak detected, alarm). This needs the system registered and the cloud subscription the OS version requires.
Email Notification agent: older path that sends email from programming. Treat it as legacy and prefer push. If a customer wants email, check that the agent is configured and test it.
Gotchas:
- Do not alert on every state change. Put a timer or condition in front so customers do not mute the app.
- For an initial state at startup, do not treat it as a change. Many "false alert after reboot" complaints come from programming that fires on the first reported value.
- Confirm which family members have the app and notifications enabled.
X4 agents: Routines, Home Screen, Driver Migration
On X4 (OS 4.0 and later):
- Routines: homeowner-editable automations in the Control4 app. The Routines agent is required on X4. Decide with the customer what they own (routines) versus what you own (Composer programming), and avoid duplicating the same automation in both.
- Home Screen: configures the new X4 home screen and its widgets.
- Driver Migration (OS 4.1): a wizard that moves Gen1, Gen2, and Gen3 lighting and keypads to Lux, carrying properties, scenes (not flashing scenes), keypad buttons, connections, and programming. Add all new devices first. Migrated devices appear as new devices hidden from Navigator, so verify visibility and engraving afterward.
After an OS update, confirm required agents are present. An early X4 issue noted that new required agents were not always added automatically during an update.
