Tasks — assign work to your agents

A task is a job you hand to an agent to run in the background instead of watching it work turn by turn in chat. Open Agent Builder → Tasks, pick an agent, describe what you want, and start it. Low-risk steps run on their own; anything that needs your judgement waits for you under Waiting on you. You’ll get a notification when a task needs your OK or has finished, so you only need to check back when there’s something to act on.

Tasks don’t loosen your safety settings. A background run still uses the approval gate: low-risk tools run automatically, but anything medium- or high-risk pauses under “Waiting on you” until you approve it — exactly as it would in a live chat.

Overview

The Tasks screen has three tabs:

  • Active — tasks currently running or queued for the next WP-Cron pass
  • Waiting on you — tasks paused on a medium- or high-risk step, waiting for your approval before they can continue
  • Done — finished tasks, including cancelled and failed ones, with their result and the steps the agent took to get there

[screenshot: Tasks screen with the Active tab open, showing a running task and its progress]

A Tasks card on the Agent Builder dashboard shows your current counts at a glance — how many are active, how many are waiting on you, and how many finished recently — with a link straight into the Tasks screen. An inbox badge in the wp-admin admin bar shows a live count of tasks that need your attention, from anywhere in wp-admin.

[screenshot: Tasks card on the Agent Builder dashboard]

[screenshot: the admin-bar inbox badge showing a pending count]

How background runs work

A task runs in the background via WP-Cron, not in your browser tab, so you can close the page and come back later. A few things worth knowing:

  • A task acts with the permissions of the administrator who assigned it — it can’t do anything that user couldn’t do themselves.
  • The approval gate still applies: low-risk tools run automatically, medium- and high-risk steps pause under Waiting on you until approved.
  • Runs survive PHP time limits — a task that needs more time than a single request allows picks back up on the next scheduled run instead of stalling.
  • Every run is recorded with its owner, the steps it took, tokens used, and its result, and is linked from the audit log.

Because background runs depend on WP-Cron firing reliably, Agent Builder adds a Site Health check for it — see the FAQ below if Tasks seem slow to start.

How to

Assign a task to an agent

  1. Go to Agent Builder → Tasks
  2. Click New Task
  3. Choose which agent should do the work
  4. Describe the job in plain English — what you want done and any constraints
  5. Start the task — it moves to the Active tab and begins running on the next WP-Cron pass

[screenshot: the New Task form with an agent selected and a task description entered]

Respond to a task waiting on you

  1. Open Tasks and switch to Waiting on you (or click the admin-bar inbox badge)
  2. Open the task and review the step it wants to take, and why it needs approval
  3. Approve it to let the task continue, or reject it to stop that step
  4. The task resumes automatically once approved, and the decision is logged

Cancel or retry a task

  1. Find the task in Active (to cancel) or Done (to retry a failed or cancelled one)
  2. Click Cancel to stop a running task immediately, or Retry to start a finished one again from scratch
  3. A retried task creates a new run — the original stays in Done for reference

[screenshot: Done tab showing a finished task’s result and step-by-step history]

FAQ

How is a task different from chatting with an agent?

Chat is a live conversation — you’re present, turn by turn. A task is a job you hand off: you describe it once, the agent works on it in the background, and you’re only pulled back in when it needs your approval or has a result.

What happens if a task takes longer than a single request?

It resumes on the next scheduled run instead of stalling. Background runs are designed to survive PHP time limits, so a long task simply picks up where it left off.

My tasks seem slow to start — what should I check?

Tasks depend on WP-Cron firing regularly. If your site has low traffic, WordPress’s default “visit-triggered” cron can run infrequently. Agent Builder’s Site Health check flags stuck runs and WP-Cron health issues. For reliable background runs, add define('DISABLE_WP_CRON', true); to wp-config.php and set up a real system cron job that runs roughly every minute, e.g. calling wp cron event run --due-now.

Can a task do things I’m not allowed to do myself?

No. A task runs with the permissions of the administrator who assigned it, so it’s bound by the same WordPress capabilities you have. The approval gate applies on top of that for anything medium- or high-risk.

Will I get notified, or do I have to keep checking the Tasks screen?

You’ll be notified — through the notifications inbox, the admin-bar badge, and (depending on your setting) email — when a task is waiting on you or has finished. See Notifications and activity email for how to control that.

Related docs