Automations
Automations are scheduled or triggered runs of inline prompts or workflows. Use them to run nightly maintenance tasks, fire off a session when a cron fires, or loop a workflow until a condition is met. They turn Polygent into a hands-off automation platform.
Session types an automation can launch
| Session type | Use it for |
|---|---|
| Develop | Inline prompt or workflow — task-focused work |
| Chat | Inline prompt only — conversational |
| Bot | Bot-driven session |
Execution types
| Execution type | What runs |
|---|---|
| Inline | A literal prompt string you provide |
| Workflow | A pre-defined workflow with parameters |
Automation types
| Type | Trigger |
|---|---|
| Manual | Run-now button only — no schedule |
| One-Time | Specific date/time (with a short grace window for past times) |
| Recurring | 5-field cron expression with IANA timezone |
| Loop | Re-execute every time the previous session completes (with a brief backoff on failure) |
| HTTP Trigger | External HTTP request to a unique webhook URL — no schedule |
Options
Per automation:
| Option | Description |
|---|---|
| Auto-Complete Session | Marks the session Done after the run finishes |
| Complete only if no file changes | (Develop only, sub-option of Auto-Complete) Skip completion and leave the session open for review if the agent made file changes |
| Auto-Execute Missed Runs on Startup | If the server was offline when a recurring run was due, fire it on startup |
| Workflow Parameters | Init params for workflow runs |
| Provider Selection | Coding agent provider selection |
| Model Selection | Override the default agent provider model |
| Session Mode Toggles | Code Architecture, UX Enhancement, Edge Cases, Code Review, Verification, Update Tests, Update Docs |
Manual trigger
Even scheduled automations can be Run Now — useful for testing config or kicking off a one-off run without changing the schedule.
HTTP trigger
An HTTP Trigger automation is fired by an external HTTP request to a unique webhook URL — perfect for CI pipelines, GitHub/Azure DevOps webhooks, or any external system that needs to launch a Polygent session on demand.
How it works
When you create an HTTP Trigger automation, Polygent generates a 32-byte cryptographically random token. The token is the secret — treat the webhook URL like an API key. Two endpoints accept the trigger:
| Method | URL | Where the token goes |
|---|---|---|
GET | /api/automations/http-trigger/{token} | In the URL path, or in the Api-Authentication header (omit the {token} segment). The header wins if both are supplied. |
POST | /api/automations/http-trigger | In the Api-Authentication header |
The header form keeps the secret out of URL access logs and browser history — prefer it for production integrations.
Parameters
Querystring parameters and JSON body fields are passed to the automation at execution time. On key collision, the body wins. For Workflow execution they merge into the workflow parameter dictionary (overriding stored defaults); for Inline prompts they substitute {{name}} placeholders.
Response
Both endpoints return a JSON envelope so CI scripts can correlate the run without a follow-up authenticated call:
| Field | Meaning |
|---|---|
success | true when the automation was triggered, false on any failure |
error | Human-readable failure message, or null on success |
sessionId | Newly created session id (or the blocking session's id on a 409) |
sessionUrl | Deep-link to the session UI |
executionId | Automation execution id |
automationName | Name of the automation that handled the request |
unresolvedPlaceholders | For inline-prompt automations only: {{name}} placeholders the caller didn't supply (empty array when all resolved) |
HTTP status codes preserve standard semantics: 401 for missing/invalid auth, 404 for unknown token, 409 when blocked by the concurrent-execution guard (the response body still carries the blocking session's ids so you can deep-link or poll it), 413 for payload too large, and 400 for other client errors.
Token regeneration
Users with automations.manage (or automations.manage_all for others' automations) can regenerate the token from the automation's edit screen. The previous URL stops working immediately.
Key behaviors
- Always enabled — HTTP Trigger automations cannot be disabled (the toggle is hidden, bulk-disable skips them). The token is the on/off switch — regenerate it to invalidate the old URL.
- No background polling — these automations only run when the webhook is hit, so Auto-Complete Session, Auto-Execute Missed Runs, and the schedule fields don't apply.
- No auto-disable on failures — HTTP Trigger automations are exempt from the 3-strike auto-disable rule.
- Concurrent execution guard — by default only one session may be in-flight at a time; subsequent webhook hits get a 409 with the blocking session's ids until it finishes. Enable Allow Parallel Sessions on the automation to bypass the guard entirely.
Execution history
Each run an automation makes is recorded with its trigger source so you can see at a glance whether it was started by the schedule, a user clicking Run Now, or an incoming webhook call. Manual runs also record which user triggered them; webhook runs record a short token fingerprint that lets you correlate the run to which token was used (without exposing the secret).
Executions created before this attribution was introduced will not show a trigger source — that's expected for historical runs.
Auto-disable & failure notifications
Recurring and Loop automations are auto-disabled after 3 consecutive failures (or when the linked Bot or Workflow is removed). One-Time automations are auto-disabled on the very first failure, since the run is single-shot and cannot be retried. In every case the automation's creator receives an inbox notification with the failure reason and a deep link straight into the automation, so silent failures don't go unnoticed for days. Manual and HTTP-triggered automations are exempt — they cannot be auto-disabled.
When a Loop automation's pull request is closed without merging, an inbox notification fires once per iteration to the automation creator (plus the session creator and the linked ticket's assigned developer when applicable). The notification deep-links to the session and includes the closed PR URL, so reviewers' decisions to discard an iteration's work are surfaced immediately. This fires regardless of the failure count and is independent of the 3-strike auto-disable notification.
If a Recurring or Loop automation's scheduled run is skipped because a previous run is still in-flight, the creator receives a single inbox notification on the first skip in the streak. Subsequent skips while the prior run is still active are deduplicated, so a multi-hour stuck session emits one notification — not one per scheduler cycle. The streak resets automatically once a new session starts successfully.
Permissions
| Permission | Capability |
|---|---|
automations.view_own | See your own automations |
automations.view_all | See everyone's automations |
automations.manage | Create / edit / delete your own |
automations.manage_all | Manage anyone's |
Common patterns
Nightly dependency audit
- Type: Recurring (2am daily)
- Execution: Inline prompt — "Run a dependency audit and create tickets for any high-severity findings"
Roll a release branch every Friday
- Type: Recurring
- Execution: Workflow — "Create release branch, bump version, open PR"
Continuous QA loop
- Type: Loop
- Execution: Workflow — "Pick the next ticket from the queue and run QA checks"
- Re-fires every time the previous session completes