How Agents Work

AI Agents in SuiteOp are autonomous entities that monitor event streams from your properties and take actions based on the instructions you give them. They operate within your organization’s permission system, follow configurable budgets, and log every action for full auditability.

Core Concepts

Agents Are Organization Members

When you create an agent, SuiteOp creates a dedicated user identity for it within your organization. This means the agent has its own role and permissions, just like a human team member. The permissions are automatically derived from the tools you enable for the agent — if you give an agent access to task tools, it receives view_tasks and modify_tasks permissions.

Event-Driven Processing

Agents do not run continuously. Instead, they wake up when events occur:

1. An event happens in your account — for example, a thermostat reports an unusual temperature, a guest sends a message, or a task becomes overdue.
2. The event router checks if any agent is assigned to that event type via stream assignments.
3. Events are batched — the system waits a short window (5 seconds by default, configurable) to collect related events before processing them together. This prevents the agent from being triggered separately for each individual event in a rapid sequence.
4. The agent processes the batch — it receives all pending events along with relevant memories (background knowledge), reasons about them, and decides what actions to take.
5. Actions are executed or queued for approval depending on the tool permission mode you configured.

Event Types

Agents can be assigned to listen to the following event types:

Event Type	Description
device.temperature_change	A thermostat or sensor reports a temperature change
device.lock_access	A smart lock is accessed
device.sensor_alert	A sensor triggers an alert (noise, motion, etc.)
device.offline	A device goes offline
reservation.created	A new reservation is created
reservation.checked_in	A guest checks in
reservation.checked_out	A guest checks out
reservation.guest_message	A guest sends a message
task.overdue	A task passes its due date
task.completed	A task is marked as completed

Note

Each event type can only be assigned to one agent per organization. This prevents conflicting actions from multiple agents responding to the same event.

Sessions

Each time an agent processes a batch of events, it creates a session. A session records:

• The events that were processed
• The system prompt and memories loaded into context
• The agent’s reasoning and summary of what it did
• Every tool call (action) made during the session
• Token usage and processing duration

Sessions are the primary way you audit and debug agent behavior. You can view session details including the full chain of events, reasoning, and actions taken.

Agent Statuses

An agent can be in one of three statuses:

Status	Meaning
Active	The agent is running and will process events assigned to it
Paused	The agent is stopped and will not process events (sandbox events are still allowed)
Budget Exceeded	The agent has hit its daily or monthly token limit and is automatically paused

Budget Controls

Every agent has two token limits:

• Daily token limit — maximum tokens the agent can consume per calendar day (default: 5,000,000)
• Monthly token limit — maximum tokens per calendar month (default: 50,000,000)

When an agent hits either limit, its status is automatically set to Budget Exceeded and it stops processing events until the limit resets. You can monitor usage on the agent’s detail page.

Follow-Up Chains

Agents can schedule follow-up checks. For example, if an agent adjusts a thermostat because of an unusual temperature reading, it might schedule a follow-up in 15 minutes to verify the temperature has returned to normal.

Follow-up chains have a maximum depth of 3 to prevent runaway loops.

Caution

Agents operate with real permissions and can take real actions in your account. Always start with the sandbox to test an agent’s behavior before assigning it to live event streams.