Tasks & Scheduling

Tracked units of work — run once, run on a cron, or run when something else finishes.

A task is work with a status, not a conversation. It has a lifecycle you can query, an owner, optional dependencies, and — when you want it — a schedule.

Create a task

const { data: task } = await commons.tasks.create({
  agentId,
  sessionId,
  title: 'Daily briefing',
  description: 'Summarise overnight news in our sectors and email the team.',
  executionMode: 'single',
  cronExpression: '0 8 * * 1-5',
  isRecurring: true,
  createdBy: userId,
  createdByType: 'user',
});

Execution modes

Mode	Behaviour
`single`	One agent run against the description
`workflow`	Runs the workflow named by `workflowId`, with `workflowInputs`
`sequential`	Runs its dependencies in order, then itself

Lifecycle

pending → started → running → completed
                          ↘ failed
                          ↘ cancelled

const { data: task } = await commons.tasks.get(taskId);
// task.status, task.progress, task.resultContent, task.summary, task.errorMessage

Scheduling

cronExpression uses standard five-field cron and is evaluated in UTC. Convert local times yourself — an 8 a.m. Nairobi briefing is 0 5 * * 1-5.

Expression	Fires
`0 8 * * 1-5`	08:00 UTC, weekdays
`/15 * * *`	Every 15 minutes
`0 0 1 * *`	Midnight UTC on the 1st
`0 /6 * *`	Every six hours

Set scheduledFor to an ISO timestamp instead of a cron expression for a one-off future run. nextRunAt and lastRunAt on the task tell you where the schedule stands.

reschedule moves a one-off run; change a recurring schedule with update:

await commons.tasks.reschedule(taskId, { scheduledFor: new Date('2026-09-10T06:00:00Z') });
await commons.tasks.update(taskId, { cronExpression: '0 6 * * 1-5' });

Run, watch, cancel

agc task execute <taskId> --watch
agc task cancel <taskId>
agc task list --agent <agentId>

await commons.tasks.execute(taskId);
 
for await (const event of commons.tasks.stream(taskId)) {
  if (event.type === 'status') console.log(event.status);
  if (event.type === 'completed') console.log(event.output);
}

Dependencies

const { data: gather } = await commons.tasks.create({ /* … */ title: 'Gather data' });
 
await commons.tasks.create({
  agentId,
  sessionId,
  title: 'Write the report',
  executionMode: 'sequential',
  dependsOn: [gather.taskId],
  createdBy: userId,
  createdByType: 'user',
});

A task with unmet dependencies waits rather than failing.

Constraining tools

Point a task at exactly the tools it should use:

await commons.tasks.create({
  // …
  tools: ['webSearch', 'createDocumentFile'],
  toolConstraintType: 'hard',   // hard · soft · none
  toolInstructions: 'Search first, then write the document. Do not email anyone.',
});

hard refuses anything outside the list; soft treats it as a preference.

Timeouts and priority

await commons.tasks.create({
  // …
  timeoutMs: 300_000,
  priority: 8,
});

Give long workflow tasks a timeoutMs — an unbounded task that hangs keeps consuming credits until something stops it.

Tasks vs heartbeats

	Task	Heartbeat
Scope	One defined job	Whatever the agent decides
Schedule	Cron or timestamp	Fixed interval
Result	Stored on the task	A run in a session
Good for	"Send the Monday report"	"Keep an eye on the queue"

Reach for a task first. A heartbeat is the right tool only when the work is genuinely open-ended.

Agents creating tasks

Give an agent createTask and updateTaskProgress and it can queue its own follow-up work:

await commons.agents.update(agentId, {
  commonTools: ['createTask', 'updateTaskProgress'],
});

On this page