How Agents Work
This page explains the agent system from the platform operator's perspective — what happens when a user runs an agent, how billing enforcement works, and how to monitor usage.
The user flow
User visits Account → AI Agents and sees the agent picker.
- Agents their plan includes are unlocked with a Run button.
- Agents not in their plan are locked with an upgrade prompt.
User clicks an agent, fills in the input form, and clicks Run.
The server validates inputs, checks plan access and monthly limits, then dispatches the job to the queue and returns immediately with a run ID.
The page polls for status every 2 seconds. A spinner and estimated time are shown.
When the run completes, the output renders inline. If notifications are enabled and the user closed the tab, they receive an email.
Completed runs appear in Account → Agent History with their output, token count, and cost.
Billing enforcement
Three checks happen on every run, in order:
1. Plan access check
The user must have an active (or trial) subscription to a plan that includes the agent's entitlement key. If not, they see a 403 with an upgrade link.
2. Monthly run cap
If the plan's entitlement value is a number (e.g. 50), the system counts runs in the current billing period and blocks the request if the cap is reached.
| Entitlement value | Meaning |
|---|---|
null (blank) | Unlimited — no cap enforced |
50 | 50 runs per billing period |
false / 0 | Access denied |
Billing periods are tracked via subscriptions.current_period_start.
3. Concurrent limit
A global per-user limit (configured in Admin → Settings) prevents one user from flooding the queue. Default: 3 simultaneous runs.
Run statuses
| Status | Meaning |
|---|---|
pending | Job is queued, waiting for a worker |
running | Worker has picked it up and is executing |
completed | Finished successfully, output is available |
failed | Execution threw an error |
timeout | Exceeded the configured timeout (default 300s) |
cancelled | User cancelled before execution started |
Failed and timeout runs show the error message to the user. The admin runs log shows the full error and error_code.
Error codes
| Code | Cause |
|---|---|
rate_limit | Provider rate limit hit — try again in a few minutes |
api_error | Provider returned an API error (bad key, model unavailable, etc.) |
timeout | Run exceeded the timeout setting |
validation | Input validation failed (should not reach execution) |
unknown | Uncategorised exception — check the application log |
Tool calls
Some agents use tools during execution — these are actions the AI takes to gather data before generating a final response (e.g. web search, page scraping, API lookups).
Tool calls are recorded in the admin run detail view, showing:
- Which tool was called
- What arguments were passed
- What the tool returned
- How long the tool took
Cost tracking
When input and output token prices are configured in admin settings, every completed run records an estimated_cost_usd value. This is visible in:
- Admin → AI Agents → Runs (column)
- Admin → AI Agents → Run detail page
This is an estimate based on token counts and the rates you configured. Actual charges from your provider may differ slightly due to rounding or pricing changes.
Data retention
Run records (inputs, outputs, tokens, cost) are kept for the number of days configured in Admin → AI Agents → Settings → Keep Run Logs. After that, a daily cleanup job deletes them automatically.
Users can also manually delete individual runs from their history page.