Scheduled Tasks

A Task is a named, triggerable agent invocation. Once created it runs on its trigger (cron, webhook, or lifecycle event), produces a TaskRun with full transcript, and shows up in /tasks in the UI.

Concept: Tasks, Workers & Workflows.

Create a task

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "name": "pr-triage",
    "agent": "default",
    "realm": "development",
    "trigger": { "kind": "schedule", "cron": "*/30 * * * *" },
    "input_template": {
      "instruction": "Triage open PRs in acme/monolith opened in the last 2 hours. Post a summary to Slack #eng-standup.",
      "repo": "acme/monolith"
    },
    "approval_defaults": { "write": "approve" }
  }'

Fields:

• agent — which agent the loop runs as. Usually default. Custom agents register via /agents.
• realm — scopes the tool catalog.
• trigger.kind — schedule | webhook | lifecycle.
• input_template — the message / payload the agent receives on each fire. Supports Handlebars-style substitution of trigger fields (shown below as {{ trigger.* }} inside the code blocks).
• approval_defaults — override the org-wide approval behavior for just this task.

Triggers

Schedule

Standard 5-field cron, UTC.

{ "kind":"schedule", "cron":"*/15 * * * *" }          // every 15 min
{ "kind":"schedule", "cron":"0 9 * * 1-5" }           // weekdays 09:00
{ "kind":"schedule", "cron":"@hourly" }               // named aliases work

Webhook

{ "kind":"webhook" }

Creating the task returns a webhook URL and secret:

{
  "id":"task_…",
  "trigger":{ "kind":"webhook",
              "url":"https://your-host/api/v1/hooks/task_…",
              "secret":"whsec_…" }
}

Send events from anywhere with an HMAC signature:

SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | cut -d' ' -f2)
curl -X POST "$URL" \
  -H "x-agentcy-signature: sha256=$SIG" \
  -H 'content-type: application/json' \
  -d "$BODY"

input_template can reference the payload:

"input_template": {
  "instruction": "A new alert arrived: {{trigger.body.alert_name}}. Diagnose it."
}

See How-To: Webhooks & Triggers.

Lifecycle

Fire on Agentcy's own events:

{ "kind":"lifecycle", "event":"source.sync.failed" }
{ "kind":"lifecycle", "event":"policy.deny", "filter":{"resource.connector":"aws"} }
{ "kind":"lifecycle", "event":"node.created", "filter":{"labels":["Incident"]} }

Useful for reactive automation — page oncall when a sync fails, for example.

Runs

Every fire creates a TaskRun:

curl "http://…/tasks/$TASK_ID/runs?limit=10" -H "authorization: Bearer $TOKEN" | jq

Each run has status, started_at, finished_at, input, output, transcript (messages + tool calls), and cost_usd.

Stream a run's events live (same SSE format as chat):

curl -N "http://…/tasks/$TASK_ID/runs/$RUN_ID/events" -H "authorization: Bearer $TOKEN"

Manual trigger

curl -X POST "http://…/tasks/$TASK_ID/run" \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"input_overrides":{"instruction":"Only check the checkout repo this time."}}'

Great for testing and one-off runs.

Cancel a run

curl -X POST "http://…/tasks/$TASK_ID/runs/$RUN_ID/cancel" -H "authorization: Bearer $TOKEN"

Runs finalize as cancelled within one LLM turn.

Pause / disable

curl -X PATCH "http://…/tasks/$TASK_ID" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"enabled":false}'

Disabled tasks don't fire; pending webhooks return 404 while disabled.

Recommendations

Agentcy will suggest tasks based on patterns it notices (recurring chat questions, graph deltas, failed syncs):

curl "http://…/task-recommendations" -H "authorization: Bearer $TOKEN" | jq

The UI's Tasks page offers a one-click "accept recommendation" button that creates a pre-filled task.

Cost and rate controls

Per-task settings:

{
  "cost_cap_usd_per_day": 5.00,
  "min_interval_secs":    60,
  "max_concurrent_runs":  1
}

• cost_cap_usd_per_day — stop firing once the cap is reached today. Resets at UTC midnight.
• min_interval_secs — drop webhook fires that arrive faster than this.
• max_concurrent_runs — if an earlier run hasn't finished, skip or queue the next (configurable via on_conflict).

Gotchas

• Cron is UTC. Always.
• Webhook secrets don't rotate automatically. Rotate via POST /tasks/:id/rotate-secret.
• Lifecycle fires can be noisy. Use filter to narrow; every unfiltered lifecycle fire runs an LLM.
• "Task" vs. "Pipeline". Tasks run an agent; pipelines run connectors. A task can trigger a pipeline run, but they aren't the same thing.

Next

• How-To: Webhooks & Triggers — the inbound side.
• Concept: Tasks, Workers & Workflows — execution model.
• How-To: Workflows & Orchestrator — if one task isn't enough.