> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisepilot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Runners

> Deploy skills as autonomous agents with triggers, output targets, and guardrails.

# Runners

Runners are the automation layer on top of skills. While a skill defines *what* the AI does (instructions, data, tools), a runner defines *when*, *where*, and *how autonomously* it executes.

## What is a Runner?

A runner wraps a skill with:

* **Trigger** — When it runs (scheduled, event-driven, or manual)
* **Output targets** — Where results go (AI insights, work items, etc.)
* **Autonomy level** — How much human review is required
* **Guardrails** — Token budget, iteration limit, timeout

Runners execute headlessly — no chat UI, no streaming. They use the same AI tools and context as workspace chat, but write results directly to the platform.

## Creating a Runner

Navigate to **Tools > Runners** and click **New Runner**.

### Required Fields

| Field             | Description                                           |
| ----------------- | ----------------------------------------------------- |
| **Name**          | Slug identifier (e.g., `weekly-seo-audit`)            |
| **Display Title** | Human-readable name                                   |
| **Role**          | Agent role category (Monitor, Analyst, Planner, etc.) |
| **Skill**         | Which published skill to execute                      |
| **Trigger Type**  | When the runner fires                                 |

### Trigger Types

| Type                 | Description                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------- |
| **Scheduled (Cron)** | Runs on a cron schedule (e.g., `0 9 * * 1` = Mondays at 9am UTC)                         |
| **Event**            | Runs when a system event occurs (e.g., another runner completes, a work item is created) |
| **Manual**           | Only runs when you click "Run Now" or trigger via API                                    |

#### Event-Triggered Runners

Event-triggered runners listen for system events and execute automatically. Configure:

* **Event Type** — Which event to listen for (e.g., `runner.completed`, `work_item.created`)
* **Event Filter** (optional) — Only trigger for specific sources (e.g., only when a specific runner completes)

Common event types:

* `runner.completed` — After another runner finishes (use filter to target specific runners)
* `work_item.created` — When a new work item is created by any source
* `content_opportunity.created` — When a content idea is discovered

### Output Targets

Choose where the runner's output goes. A runner can write to multiple targets.

| Target                  | Description                                                           | Status    |
| ----------------------- | --------------------------------------------------------------------- | --------- |
| **AI Insight**          | Creates an insight for review in the experiments panel                | Available |
| **Work Item**           | Creates a task in the revenue inbox                                   | Available |
| **Content Opportunity** | Creates an entry in the content planner                               | Available |
| **Slack Message**       | Sends a notification to Slack (requires webhook URL in output config) | Available |
| **Content Asset**       | Creates a draft blog/page in the content library                      | Available |
| **Fibery Task**         | Creates a task in Fibery (requires API integration)                   | Planned   |

### Autonomy Levels

| Level                   | Behavior                                        |
| ----------------------- | ----------------------------------------------- |
| **Automatic**           | Outputs applied without human review            |
| **Semi-Auto** (default) | Outputs staged for review before being acted on |
| **Manual**              | Human must explicitly initiate and review       |

### Guardrails

| Setting            | Default     | Description                                   |
| ------------------ | ----------- | --------------------------------------------- |
| **Max Tokens**     | 128,000     | Cumulative token budget across all iterations |
| **Max Iterations** | 10          | Maximum tool-calling loop iterations          |
| **Timeout**        | 300 seconds | Hard cutoff for execution time                |

### Model Selection

Each role has a default model, but you can override it per runner:

| Roles     | Default Model | Notes                                                          |
| --------- | ------------- | -------------------------------------------------------------- |
| All roles | Claude Sonnet | High-quality output with reliable tool usage and evidence fill |

### Chain Config

Runners can automatically trigger other runners when they complete:

* **On Complete** — Runner names to trigger after a successful run
* **On Error** — Runner names to trigger after a failed run

Chained runners receive context from their parent, including output summaries and any work items or opportunities created. Chain depth is limited to 10 levels.

## Managing Runners

The runners table shows all your runners with:

* **Status** — Active or Disabled (toggle with the play/pause button)
* **Last Run** — When the runner last executed
* **Result** — Success, failure, or timeout

### Run History

Click any runner to open the detail panel. The **Recent Runs** section shows:

* Status and duration of each run
* Token usage and estimated cost
* Full output text (expandable)
* Errors for failed runs
* Tools used and output targets written
* Quality rating (thumbs up/down)

### Events Browser

Switch to the **Events** tab on the runners page to see the event queue. You can:

* Filter by status (pending, processing, done, failed)
* Filter by event type
* Expand events to see their payload and which runners they triggered
* Retry failed events

### Running Manually

Click the **Run Now** button on any runner to queue an immediate execution. The run will be picked up within 5 minutes by the runner executor.

## External Triggers

Runners can be triggered externally via the API:

```bash theme={null}
curl -X POST https://your-app.com/api/v1/runners/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runner_id": "uuid-here"}'
```

Check run status:

```bash theme={null}
curl https://your-app.com/api/v1/runners/runs/RUN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Deterministic Runners

Not every runner uses AI. Some runners execute entirely without an AI model — they perform data sync, deduplication, pattern detection, and other algorithmic tasks using built-in platform logic.

<Info>
  Deterministic runners have **zero AI cost** and complete nearly instantly. They appear in run history alongside AI-powered runners, but always show **\$0.00** under cost.
</Info>

Key characteristics:

* **No skill required** — The logic is built into the platform, not authored as a skill
* **Same triggers** — Schedule them on a cron, fire them on an event, or run them manually
* **Same output targets** — They can create work items, insights, or content opportunities just like AI runners
* **Reliable and cheap** — Because there's no model involved, they never time out due to token limits and cost nothing to run

Examples of tasks handled by deterministic runners: syncing external data sources, deduplicating discovered content, computing scoring rollups, and detecting recurring charge patterns in invoice data.

## Tips

* **Start with manual triggers** to verify a runner works before scheduling it
* **Use semi-auto autonomy** until you trust the runner's outputs
* **Keep timeouts under 240s** — the platform enforces a 300-second hard limit
* **Monitor token costs** in the run history to right-size your token budget