Skip to main content

​
Overview

Every task follows a lifecycle from creation through completion (or failure). The lifecycle is designed for accountability — you can see what the agent is working on, what is blocked, and what has been accomplished.

​
Status Flow

​
Status Definitions

StatusDescriptionWho Sets It
pendingTask created, waiting to be startedSystem (on creation)
in_progressAgent is actively workingUser (play button) or agent
completedTask finished successfullyAgent (tasks_complete)
failedTask could not be completedAgent (with error reason)
blockedWaiting on external dependencyAgent (tasks_block)

​
The Dashboard Play Flow

This is the primary task execution workflow:
1

User Clicks Play

The user clicks the play button on a pending task in the dashboard. This triggers:
  1. POST /api/tasks/:id/start — Updates status to in_progress
  2. A chat message is sent to the gateway: “Work on task: [title]”
2

Agent Receives and Works

The agent receives the message and begins working. It can:
  • Use any available tools (exec, browser, memory, etc.)
  • Stream progress updates in the chat
  • Create sub-tasks if needed
3

Agent Completes

When finished, the agent:
  1. Calls the tasks tool with action: complete
  2. Emits [TASK_DONE:title] in the response stream
4

Dashboard Updates

The dashboard updates through two mechanisms:
  • Instant: Parses [TASK_DONE:title] from the stream for immediate UI update
  • Polling: Checks the database every 5 seconds as a backup

​
Heartbeat-Triggered Tasks

The heartbeat system can trigger task work autonomously:
1

Heartbeat fires on schedule

2

Agent checks for pending tasks

3

Picks the highest-priority task

4

Works on it and updates status

This enables the agent to work on tasks even when no user is actively chatting.

​
Task Accountability

Tasks track:
  • Who created it: User, agent, heartbeat, or schedule
  • When each status change happened: Full audit trail
  • Time spent: Duration in each status
  • Completion notes: What the agent did to complete the task

​
Bulk Operations

# Complete all tasks matching a filter
argent tasks complete --status in_progress --older-than 7d

# List overdue tasks
argent tasks list --overdue