Agent Sandbox

The sandbox lets you inject simulated events into an agent and observe how it responds — without affecting live operations, except when a tool is set to Auto (Auto tools will execute real actions). Use it to validate your agent’s configuration, refine its instructions, and build confidence before assigning it to real event streams.

Why Use the Sandbox

Test before going live — verify that your agent handles events correctly before it processes real data
Iterate on instructions — refine the agent’s system prompt and skills by observing its reasoning
Validate tool permissions — confirm that the right tools are set to Auto vs. Ask
Debug unexpected behavior — reproduce specific scenarios to understand why an agent acted a certain way

Using the Sandbox

Open the agent’s sandbox

Navigate to the agent’s detail page and select the Sandbox tab.
Configure the event

Fill in the sandbox event form:
- Event Type — select the type of event to simulate (e.g., device.temperature_change, reservation.guest_message)
- Property (optional) — associate the event with a specific property. This affects which skills are activated if you have property-scoped skills.
- Entity Type (optional) — the type of entity this event relates to (e.g., device, reservation, task)
- Entity ID (optional) — the specific entity’s ID
- Payload — a JSON object with the event data. The structure depends on the event type.
Inject the event

Click Inject Event to send the event to the agent. Unlike live events, sandbox events are processed immediately with no batch delay.
Review the session

After the agent processes the event, a new sandbox session appears. You can review:
- Reasoning — the agent’s summary of what it observed and decided
- Actions — every tool call the agent made, with arguments and results
- Events — the events that were processed in this session
- Token usage — how many tokens the session consumed
Iterate

Adjust the agent’s system prompt, skills, or tool permissions based on the results, then inject another event to test the changes.

Sandbox Sessions

Sandbox sessions are tracked separately from live sessions. You can view a list of all sandbox sessions for an agent, making it easy to compare behavior across configuration changes.

Each sandbox session shows:

When it was created
The session status (running, completed, or failed)
How many events were in the batch
Total token usage
The agent’s reasoning summary

Example Payloads

Here are example payloads for common event types:

Temperature change

{
  "deviceId": "device-uuid-here",
  "deviceName": "Living Room Thermostat",
  "currentTemperature": 85,
  "targetTemperature": 72,
  "unit": "fahrenheit"
}

Guest message

{
  "reservationId": "reservation-uuid-here",
  "guestName": "Jane Smith",
  "message": "Is there a way to get extra towels?",
  "propertyName": "Oceanview Suite"
}

Task overdue

{
  "taskId": "task-uuid-here",
  "taskName": "Pre-arrival inspection",
  "dueDate": "2026-03-28T14:00:00Z",
  "assigneeName": "John Doe",
  "propertyName": "Downtown Loft"
}