Tasks, Workers & Workflows

Agentcy has three related-but-distinct execution systems:

System	What it is	Lives in
Scheduled Tasks	Cron-style recurring agent runs or webhook handlers	agentcy-tasks
Workers	Out-of-process job queue for heavy/long work	agentcy-worker (+ agentcy-worker-bin)
Workflows / Orchestrator	Multi-agent graphs of steps (optional, via OpenFang)	agentcy-api::routes::orchestration_gateway

If you just want to say "run this agent every 15 minutes", you want Tasks. If you want an ingestion run to not block an API request, you want Workers. If you want a visual DAG of agents handing work to each other, you want Workflows.

Scheduled Tasks

A Task is a named, triggerable agent invocation.

{
  "name": "pr-triage-agent",
  "agent": "backlog-triager",
  "realm": "development",
  "trigger": { "kind": "schedule", "cron": "*/30 * * * *" },
  "input": { "repo": "acme/monolith", "since_hours": 1 }
}

Triggers: schedule (cron), webhook (inbound URL), lifecycle (platform events). See Channels & Triggers for the full trigger model.

Task runs

Every fire produces a TaskRun with:

• status: pending → running → succeeded / failed / cancelled
• full input payload (resolved from the trigger)
• transcript of the agent run (messages + tool calls)
• artifacts produced
• policy audit entries

Query via GET /api/v1/tasks/:id/runs. The UI's /tasks page is the full UX; see How-To: Scheduled Tasks.

Cancellation

POST /api/v1/tasks/:id/runs/:run_id/cancel sets an atomic cancel flag. The agent loop checks it between turns and after every tool call, unwinds, and finalizes as cancelled.

Recommendations

GET /api/v1/task-recommendations returns Agentcy's suggestions of tasks to create based on recurring chat questions, graph patterns, and connector state. The UI surfaces them as a list you can one-click accept.

Workers

Workers are Tokio processes that consume Redis streams. They exist to:

• Run long ingestion syncs without blocking the API.
• Execute tool calls that themselves take minutes (big graph traversals, Remotion renders, long agent loops).
• Survive API restarts (jobs persist in Redis).

Enable with AGENTCY_FEATURES_WORKERS=true and run the daemon:

# Self-hosted
cargo run --release -p agentcy-worker-bin
# or Docker
docker compose --profile workers up -d

Workers register with the API via a token (WORKER_TOKEN). The API enqueues jobs onto Redis streams keyed by queue name (ingest, render, agent, …). Workers claim with consumer groups (one per queue), lease for WORKER_LEASE_TTL (default 300s), and emit heartbeats. If a worker dies, its lease expires and another picks up.

Queues

Queue	What lands here
ingest	Pipeline step executions
agent	Scheduled task agent runs (when workers are on)
render	Remotion video renders, long artifact generations
voice	Voice session transcription / synthesis batches
graph-maintenance	Compaction, prune, realm migration

Enqueue programmatically from a handler:

state.workers.enqueue(Job::agent_run(task_id, input)).await?;

Observability

Worker state is exposed at GET /api/v1/workers/status:

{
  "workers": [
    { "id":"wrk_01","queues":["ingest","graph-maintenance"],"last_heartbeat":"…" }
  ],
  "queues": {
    "ingest": { "depth": 3, "inflight": 1, "oldest_pending_s": 12 },
    "render": { "depth": 0, "inflight": 0 }
  }
}

Logs stream to the API's /activity feed too, so operators see worker failures next to API errors.

Workflows & Orchestrator

Workflows are DAGs of agent invocations. You wire:

[ ingest docs ]──►[ summarize ]──►┐
                                   ├──►[ compose response ]──►[ send to Slack ]
[ query graph ]──►[ rank findings ]─┘

Each node has its own agent, tool catalog, input/output schema, and policy context. The orchestrator runs the graph, streams intermediate state to the UI, and persists the full run.

Workflows live under the Orchestrator feature (requires AGENTCY_FEATURES_ORCHESTRATOR=true and the OpenFang sidecar). The UI editor is at /orchestrator/workflows/[id]/edit — full-screen React Flow + properties panel.

Endpoints:

• GET/POST /api/v1/orchestrator/workflows
• POST /api/v1/orchestrator/workflows/:id/run
• GET /api/v1/orchestrator/workflows/:id/runs

See How-To: Workflows & Orchestrator.

How they relate

• A Task can be backed by a Worker (recommended for non-trivial work) or run inline in the API process (fine for quick tasks).
• A Workflow is triggered the same way as a Task (cron, webhook, lifecycle) but is internally a multi-step DAG.
• Heavy tool calls inside a chat can be enqueued to a Worker behind an approval, so the user gets "working on it…" and a result later (via the SSE stream reconnect).

Gotchas

• Without workers, long syncs block the API process. Fine for dev, bad for prod. Turn workers on.
• Cron is UTC. If you rely on "business hours" policies, normalize to UTC in the trigger and check timezone in the policy.
• Task runs count against LLM spend. Every task fire runs an agent loop. Use a cheaper model and narrower tool catalog for high-frequency tasks.
• Orchestrator is optional. Don't reach for it for 1- or 2-step flows — use a single Task instead.

Next

• How-To: Scheduled Tasks — the primary pattern for recurring work.
• How-To: Workflows & Orchestrator — multi-agent graphs.
• Concept: Channels & Triggers — how tasks get fired.
• Reference: REST API — /tasks, /workers, /orchestrator details.