Runs & Scheduling

Overview

A run is a single execution of an agent task — from when the agent starts working to when it finishes. The Runs tab provides full visibility into every run: what happened, how long it took, what it cost, and whether it succeeded.

Runs are the audit trail for your agent's work. Every action, message, and decision is captured and reviewable.

The Runs Tab

The Runs tab displays a sortable table of all past and active runs — showing status, trigger type, duration, token usage, and cost at a glance.

Run Detail Drawer

Click any run to open the Run Detail Drawer, which shows:

• Full status timeline (queued → running → completed)
• All chat messages from the run
• Every tool call and action performed
• Screenshots captured during execution
• Token breakdown (input vs. output)
• Duration and cost details
• Error messages (if the run failed)

Run Statuses

Run Types

Runs are triggered from different sources:

Manual (Chat)

When you chat with your agent and it takes action, that's a manual run. You're interacting in real time and can provide additional input as needed.

Action Playback

When you replay saved action sequences (Play All, Play Selected, or Play From Here), each playback session creates a run. This includes data-driven playback where the same sequence runs across multiple data rows. See Actions & Sequences for details.

Queue Processing

When the agent processes items from its queue — either manually triggered or on schedule. Each queue item gets its own run with a dedicated chat session, so you can review exactly how each task was handled.

Scheduled

When the cron system triggers an automatic run based on the agent's configured schedule. This includes both queue processing schedule runs and scheduled job runs (time-based triggers that inject prompts into the queue). The system:

1. Provisions a sandbox automatically
2. Processes queue items up to the configured maximum
3. Each item creates a separate run for traceability
4. The sandbox stays warm for efficiency

Scheduled jobs create their own queue items with a specific prompt — these items are then processed like any other queue item. See Schedule for details on creating time-based triggers.

Scheduling

Scheduling turns your agent into a 24/7 autonomous worker. Configure a schedule and the agent processes its queue at regular intervals without any human intervention.

Setting Up a Schedule

You can set up a schedule two ways:

Through the UI:

1. Open the Queue tab
2. Access Queue Settings
3. Set the schedule interval (every 5 min to every 24 hours)
4. Configure max items per run

Through conversation: Tell your agent: "Set up a schedule to process your queue every 15 minutes, max 5 items per run." The agent uses settings_manager to configure it.

Schedule Intervals

How Scheduled Runs Work

Schedule triggers (e.g., every 15 min)
  → System provisions sandbox automatically
    → Agent processes queue items sequentially
      → Each item gets its own chat session
        → Agent completes or hits time/item limit
          → Sandbox stays warm for next trigger

The key insight: no human needs to "wake" the agent. The system handles sandbox provisioning, execution, and cleanup entirely on its own.

Cost & Token Tracking

Every run tracks resource consumption:

• Input tokens — Tokens sent to the AI model (context, instructions, history)
• Output tokens — Tokens generated by the AI model (responses, tool calls)
• Total tokens — Combined input + output
• Estimated cost — Dollar cost based on the model's pricing

This data helps you:

• Understand which tasks are expensive
• Optimize instructions and skills to reduce token usage
• Budget for scheduled runs over time
• Identify runs that are using more resources than expected

Active Run Banner

When a run is currently in progress, an active run banner appears at the top of the agent page showing:

• Run status (running)
• Duration so far
• A link to view the run details

This provides at-a-glance visibility without navigating to the Runs tab.

Tips & Best Practices

• Review failed runs — Check the error details in the Run Detail Drawer to understand what went wrong
• Start with longer intervals — Begin with hourly schedules and increase frequency as you gain confidence
• Monitor costs — Check run costs regularly, especially for scheduled agents running frequently
• Use the detail drawer — The full message and action history is invaluable for debugging and optimization
• Set item limits — Configure max items per run to prevent unexpectedly long (and expensive) processing sessions
• Let the agent set its schedule — Tell the agent your preferences and it will configure the schedule itself

What's Next?

• Queue — Understand how the queue feeds runs
• Schedule — Create time-based triggers that inject prompts into the queue
• Mail — Set up email-driven task automation
• Agent Settings — Configure sandbox and agent-level settings