.do
Task Management

Task Lifecycle

Task lifecycle, status tracking, and scheduling for AI agents

Understanding the task lifecycle is essential for effective agent coordination and monitoring. Tasks progress through well-defined stages from creation to completion, with clear status transitions and monitoring capabilities.

Lifecycle Stages

1. Created (pending)

Task is created and waiting for assignment.

What Happens:

  • Task is validated and stored
  • Initial priority assessment
  • Routing to assignment queue

Status: pending

Example:

const task = await $.Task.create({
  task: 'Analyze Q4 revenue trends',
  priority: 'high',
})
// Status: 'pending'
console.log(`Task ${task.taskId} created and pending assignment`)

Duration: Typically seconds to minutes

2. Assigned (assigned)

Agent is assigned and preparing to start work.

What Happens:

  • Best-fit agent selected (auto or manual)
  • Resources allocated
  • Context and requirements loaded
  • Work scheduled in agent's queue

Status: assigned

Example:

const status = await $.Task.get(taskId)
// Status: 'assigned'
console.log(`Assigned to ${status.agentName}, estimated start in ${status.estimatedStart}`)

Duration: Minutes to hours (based on agent availability)

3. In Progress (in_progress)

Agent is actively working on the task.

What Happens:

  • Agent executes work
  • Progress updates sent periodically
  • Intermediate results saved
  • Resource usage monitored

Status: in_progress

Example:

const status = await $.Task.get(taskId)
// Status: 'in_progress'
console.log(`Progress: ${status.progress}%`)
console.log(`Current phase: ${status.currentPhase}`)
console.log(`Estimated completion: ${status.estimatedCompletion}`)

Duration: Minutes to days (depends on task complexity)

Progress Tracking:

// Poll for updates
const checkProgress = setInterval(async () => {
  const status = await $.Task.get(taskId)
  console.log(`${status.progress}% complete - ${status.currentPhase}`)

  if (status.status !== 'in_progress') {
    clearInterval(checkProgress)
  }
}, 30000) // Check every 30 seconds

4. Review (review)

Task completed by agent, under review before finalization.

What Happens:

  • Initial work completed
  • Quality checks performed
  • Deliverables validated
  • Optional human review

Status: review

Example:

const status = await $.Task.get(taskId)
// Status: 'review'
console.log(`Under review, quality score: ${status.quality.score}`)

Duration: Minutes to hours

5. Completed (completed)

Task successfully completed with deliverables ready.

What Happens:

  • All deliverables finalized
  • Quality metrics calculated
  • Results stored and accessible
  • Agent resources released

Status: completed

Example:

const result = await $.Task.get(taskId)
// Status: 'completed'

console.log('Task completed!')
console.log('Summary:', result.result.summary)
console.log('Quality score:', result.quality.score)

// Get deliverables
const deliverables = await $.Task.deliverables(taskId)
deliverables.forEach((d) => {
  console.log(`${d.name}: ${d.downloadUrl}`)
})

Final State: Permanent

6. Blocked (blocked)

Task is waiting on external dependency.

What Happens:

  • Work paused due to dependency
  • Monitoring for dependency resolution
  • Agent resources may be reassigned
  • Notifications sent to stakeholders

Status: blocked

Example:

const status = await $.Task.get(taskId)
// Status: 'blocked'
console.log(`Blocked: ${status.blockReason}`)
console.log(`Waiting for: ${status.dependencies}`)

Recovery:

// Unblock when dependency resolves
await $.Task.update(taskId, {
  status: 'in_progress',
  context: { dependency: 'resolved' },
})

Duration: Variable (until dependency resolves)

7. Failed (failed)

Task failed and requires intervention.

What Happens:

  • Error occurred during execution
  • Partial results may be saved
  • Error details logged
  • Retry or escalation options available

Status: failed

Example:

const status = await $.Task.get(taskId)
// Status: 'failed'
console.log('Task failed:', status.error)
console.log('Failed at phase:', status.failedPhase)

// Retry with updated context
await $.Task.retry(taskId, {
  reassign: true,
  context: { additionalInfo: '...' },
})

Recovery Options:

  • Retry with same agent
  • Retry with different agent
  • Update context and retry
  • Escalate for manual intervention

8. Cancelled (cancelled)

Task was cancelled before completion.

What Happens:

  • Work stopped immediately
  • Partial results discarded
  • Agent resources released
  • Cancellation logged

Status: cancelled

Example:

await $.Task.cancel(taskId, {
  reason: 'Requirements changed, will create new task',
})

const status = await $.Task.get(taskId)
// Status: 'cancelled'
console.log(`Cancelled: ${status.cancelReason}`)

Final State: Permanent

Status Transitions

Valid status transitions:

pending → assigned → in_progress → review → completed
                ↓           ↓          ↓
              cancelled   blocked   failed
                            ↓          ↓
                       in_progress  retry

Scheduling & Priority

Priority Levels

Tasks are scheduled based on priority:

  • urgent - Start immediately, preempt lower priority
  • high - Start within minutes
  • medium - Start within hours (default)
  • low - Start when capacity available

Example:

await $.Task.create({
  task: 'Critical security patch',
  priority: 'urgent', // Will preempt current work
})

Deadlines

Set explicit deadlines for time-sensitive work:

await $.Task.create({
  task: 'Prepare board presentation',
  deadline: '2024-10-30T09:00:00Z',
  priority: 'high',
})

Deadline Handling:

  • Warnings sent as deadline approaches
  • Priority automatically elevated if at risk
  • Escalation if deadline will be missed

Scheduling Strategies

Immediate Execution:

await $.Task.create({
  task: 'Process urgent request',
  priority: 'urgent',
  executeImmediately: true,
})

Deferred Execution:

await $.Task.create({
  task: 'Generate monthly report',
  scheduledStart: '2024-11-01T00:00:00Z',
})

Recurring Tasks:

await $.Task.create({
  task: 'Send weekly performance summary',
  schedule: {
    type: 'recurring',
    frequency: 'weekly',
    dayOfWeek: 'monday',
    time: '09:00',
  },
})

Monitoring & Alerts

Real-Time Monitoring

Monitor task progress in real-time:

// Subscribe to task updates
$.Task.subscribe(taskId, (update) => {
  console.log(`${update.status}: ${update.progress}%`)

  if (update.status === 'completed') {
    console.log('Deliverables ready!')
  }

  if (update.status === 'failed') {
    console.error('Task failed:', update.error)
  }
})

Progress Webhooks

Receive webhook notifications for status changes:

await $.Task.create({
  task: 'Process large dataset',
  webhooks: {
    progress: 'https://api.yourdomain.com/webhooks/task-progress',
    completed: 'https://api.yourdomain.com/webhooks/task-completed',
    failed: 'https://api.yourdomain.com/webhooks/task-failed',
  },
})

Alert Configuration

Configure alerts for specific conditions:

await $.Task.update(taskId, {
  alerts: {
    progressStalled: { threshold: '30 minutes' },
    qualityBelowThreshold: { threshold: 0.8 },
    deadlineRisk: { warnBefore: '2 hours' },
  },
})

Task Duration Estimates

The system provides duration estimates based on:

  • Historical data for similar tasks
  • Agent performance metrics
  • Current workload
  • Task complexity

Example:

const task = await $.Task.create({
  task: 'Analyze customer survey results',
})

console.log(`Estimated duration: ${task.estimatedDuration}`)
console.log(`Estimated completion: ${task.estimatedCompletion}`)

Batch Operations

Manage multiple tasks efficiently:

Bulk Create

const tasks = await $.Task.createBatch([
  { task: 'Process invoice batch 1', data: batch1 },
  { task: 'Process invoice batch 2', data: batch2 },
  { task: 'Process invoice batch 3', data: batch3 },
])

Bulk Status Check

const statuses = await $.Task.getBatch([taskId1, taskId2, taskId3])
statuses.forEach((s) => {
  console.log(`${s.taskId}: ${s.status} (${s.progress}%)`)
})

Task Dependencies

Create dependent task chains:

const research = await $.Task.create({
  task: 'Research market trends',
})

const analysis = await $.Task.create({
  task: 'Analyze research findings',
  dependencies: [research.taskId],
})

const report = await $.Task.create({
  task: 'Create executive report',
  dependencies: [analysis.taskId],
})

Dependency Handling:

  • Dependent tasks wait in pending until dependencies complete
  • Failed dependencies can block or skip dependent tasks
  • Parallel dependencies all must complete

Learn More

Task Categories

Explore task types and categories

Tasks API

Complete API reference

tasks.org.ai

Browse 19,265 standardized tasks

Task Management

Overview and quick start

Task Categories

Major task categories and types for AI agents

Teams Overview

Overview of all 35+ pre-configured agent teams for multi-agent collaboration

On this page

Lifecycle Stages1. Created (pending)2. Assigned (assigned)3. In Progress (in_progress)4. Review (review)5. Completed (completed)6. Blocked (blocked)7. Failed (failed)8. Cancelled (cancelled)Status TransitionsScheduling & PriorityPriority LevelsDeadlinesScheduling StrategiesMonitoring & AlertsReal-Time MonitoringProgress WebhooksAlert ConfigurationTask Duration EstimatesBatch OperationsBulk CreateBulk Status CheckTask DependenciesLearn MoreRelated Resources