mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 07:30:43 +00:00
docs(tasks): rewrite with Tabs for quick start and AccordionGroup for CLI reference and runtime relationships
This commit is contained in:
Vincent Koc
@@ -5,12 +5,14 @@ read_when:
|
||||
- Debugging delivery failures for detached agent runs
|
||||
- Understanding how background runs relate to sessions, cron, and heartbeat
|
||||
title: "Background tasks"
|
||||
sidebarTitle: "Background tasks"
|
||||
---
|
||||
|
||||
> **Looking for scheduling?** See [Automation & Tasks](/automation) for choosing the right mechanism. This page covers **tracking** background work, not scheduling it.
|
||||
<Note>
|
||||
Looking for scheduling? See [Automation & Tasks](/automation) for choosing the right mechanism. This page covers **tracking** background work, not scheduling it.
|
||||
</Note>
|
||||
|
||||
Background tasks track work that runs **outside your main conversation session**:
|
||||
ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations.
|
||||
Background tasks track work that runs **outside your main conversation session**: ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations.
|
||||
|
||||
Tasks do **not** replace sessions, cron jobs, or heartbeats — they are the **activity ledger** that records what detached work happened, when, and whether it succeeded.
|
||||
|
||||
@@ -24,48 +26,63 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat
|
||||
- ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
|
||||
- Each task moves through `queued → running → terminal` (succeeded, failed, timed_out, cancelled, or lost).
|
||||
- Cron tasks stay live while the cron runtime still owns the job; chat-backed CLI tasks stay live only while their owning run context is still active.
|
||||
- Completion is push-driven: detached work can notify directly or wake the
|
||||
requester session/heartbeat when it finishes, so status polling loops are
|
||||
usually the wrong shape.
|
||||
- Completion is push-driven: detached work can notify directly or wake the requester session/heartbeat when it finishes, so status polling loops are usually the wrong shape.
|
||||
- Isolated cron runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
|
||||
- Isolated cron delivery suppresses stale interim parent replies while
|
||||
descendant subagent work is still draining, and it prefers final descendant
|
||||
output when that arrives before delivery.
|
||||
- Isolated cron delivery suppresses stale interim parent replies while descendant subagent work is still draining, and it prefers final descendant output when that arrives before delivery.
|
||||
- Completion notifications are delivered directly to a channel or queued for the next heartbeat.
|
||||
- `openclaw tasks list` shows all tasks; `openclaw tasks audit` surfaces issues.
|
||||
- Terminal records are kept for 7 days, then automatically pruned.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# List all tasks (newest first)
|
||||
openclaw tasks list
|
||||
<Tabs>
|
||||
<Tab title="List and filter">
|
||||
```bash
|
||||
# List all tasks (newest first)
|
||||
openclaw tasks list
|
||||
|
||||
# Filter by runtime or status
|
||||
openclaw tasks list --runtime acp
|
||||
openclaw tasks list --status running
|
||||
# Filter by runtime or status
|
||||
openclaw tasks list --runtime acp
|
||||
openclaw tasks list --status running
|
||||
```
|
||||
|
||||
# Show details for a specific task (by ID, run ID, or session key)
|
||||
openclaw tasks show <lookup>
|
||||
</Tab>
|
||||
<Tab title="Inspect">
|
||||
```bash
|
||||
# Show details for a specific task (by ID, run ID, or session key)
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Cancel and notify">
|
||||
```bash
|
||||
# Cancel a running task (kills the child session)
|
||||
openclaw tasks cancel <lookup>
|
||||
|
||||
# Cancel a running task (kills the child session)
|
||||
openclaw tasks cancel <lookup>
|
||||
# Change notification policy for a task
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
```
|
||||
|
||||
# Change notification policy for a task
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
</Tab>
|
||||
<Tab title="Audit and maintenance">
|
||||
```bash
|
||||
# Run a health audit
|
||||
openclaw tasks audit
|
||||
|
||||
# Run a health audit
|
||||
openclaw tasks audit
|
||||
# Preview or apply maintenance
|
||||
openclaw tasks maintenance
|
||||
openclaw tasks maintenance --apply
|
||||
```
|
||||
|
||||
# Preview or apply maintenance
|
||||
openclaw tasks maintenance
|
||||
openclaw tasks maintenance --apply
|
||||
|
||||
# Inspect TaskFlow state
|
||||
openclaw tasks flow list
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Task flow">
|
||||
```bash
|
||||
# Inspect TaskFlow state
|
||||
openclaw tasks flow list
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## What creates a task
|
||||
|
||||
@@ -77,17 +94,22 @@ openclaw tasks flow cancel <lookup>
|
||||
| CLI operations | `cli` | `openclaw agent` commands that run through the gateway | `silent` |
|
||||
| Agent media jobs | `cli` | Session-backed `video_generate` runs | `silent` |
|
||||
|
||||
Main-session cron tasks use `silent` notify policy by default — they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session.
|
||||
<AccordionGroup>
|
||||
<Accordion title="Notify defaults for cron and media">
|
||||
Main-session cron tasks use `silent` notify policy by default — they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session.
|
||||
|
||||
Session-backed `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished video itself. If you opt into `tools.media.asyncCompletion.directSend`, async `music_generate` and `video_generate` completions try direct channel delivery first before falling back to the requester-session wake path.
|
||||
Session-backed `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished video itself. If you opt into `tools.media.asyncCompletion.directSend`, async `music_generate` and `video_generate` completions try direct channel delivery first before falling back to the requester-session wake path.
|
||||
|
||||
While a session-backed `video_generate` task is still active, the tool also acts as a guardrail: repeated `video_generate` calls in that same session return the active task status instead of starting a second concurrent generation. Use `action: "status"` when you want an explicit progress/status lookup from the agent side.
|
||||
|
||||
**What does not create tasks:**
|
||||
|
||||
- Heartbeat turns — main-session; see [Heartbeat](/gateway/heartbeat)
|
||||
- Normal interactive chat turns
|
||||
- Direct `/command` responses
|
||||
</Accordion>
|
||||
<Accordion title="Concurrent video_generate guardrail">
|
||||
While a session-backed `video_generate` task is still active, the tool also acts as a guardrail: repeated `video_generate` calls in that same session return the active task status instead of starting a second concurrent generation. Use `action: "status"` when you want an explicit progress/status lookup from the agent side.
|
||||
</Accordion>
|
||||
<Accordion title="What does not create tasks">
|
||||
- Heartbeat turns — main-session; see [Heartbeat](/gateway/heartbeat)
|
||||
- Normal interactive chat turns
|
||||
- Direct `/command` responses
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Task lifecycle
|
||||
|
||||
@@ -115,23 +137,14 @@ stateDiagram-v2
|
||||
|
||||
Transitions happen automatically — when the associated agent run ends, the task status updates to match.
|
||||
|
||||
Agent run completion is authoritative for active task records. A successful
|
||||
detached run finalizes as `succeeded`, ordinary run errors finalize as
|
||||
`failed`, and timeout or abort outcomes finalize as `timed_out`. If an operator
|
||||
already cancelled the task, or the runtime already recorded a stronger terminal
|
||||
state such as `failed`, `timed_out`, or `lost`, a later success signal does not
|
||||
downgrade that terminal status.
|
||||
Agent run completion is authoritative for active task records. A successful detached run finalizes as `succeeded`, ordinary run errors finalize as `failed`, and timeout or abort outcomes finalize as `timed_out`. If an operator already cancelled the task, or the runtime already recorded a stronger terminal state such as `failed`, `timed_out`, or `lost`, a later success signal does not downgrade that terminal status.
|
||||
|
||||
`lost` is runtime-aware:
|
||||
|
||||
- ACP tasks: backing ACP child session metadata disappeared.
|
||||
- Subagent tasks: backing child session disappeared from the target agent store.
|
||||
- Cron tasks: the cron runtime no longer tracks the job as active.
|
||||
- CLI tasks: isolated child-session tasks use the child session; chat-backed
|
||||
CLI tasks use the live run context instead, so lingering
|
||||
channel/group/direct session rows do not keep them alive. Gateway-backed
|
||||
`openclaw agent` runs also finalize from their run result, so completed runs
|
||||
do not sit active until the sweeper marks them `lost`.
|
||||
- CLI tasks: isolated child-session tasks use the child session; chat-backed CLI tasks use the live run context instead, so lingering channel/group/direct session rows do not keep them alive. Gateway-backed `openclaw agent` runs also finalize from their run result, so completed runs do not sit active until the sweeper marks them `lost`.
|
||||
|
||||
## Delivery and notifications
|
||||
|
||||
@@ -145,9 +158,7 @@ When a task reaches a terminal state, OpenClaw notifies you. There are two deliv
|
||||
Task completion triggers an immediate heartbeat wake so you see the result quickly — you do not have to wait for the next scheduled heartbeat tick.
|
||||
</Tip>
|
||||
|
||||
That means the usual workflow is push-based: start detached work once, then let
|
||||
the runtime wake or notify you on completion. Poll task state only when you
|
||||
need debugging, intervention, or an explicit audit.
|
||||
That means the usual workflow is push-based: start detached work once, then let the runtime wake or notify you on completion. Poll task state only when you need debugging, intervention, or an explicit audit.
|
||||
|
||||
### Notification policies
|
||||
|
||||
@@ -167,96 +178,93 @@ openclaw tasks notify <lookup> state_changes
|
||||
|
||||
## CLI reference
|
||||
|
||||
### `tasks list`
|
||||
<AccordionGroup>
|
||||
<Accordion title="tasks list">
|
||||
```bash
|
||||
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
|
||||
```
|
||||
Output columns: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary.
|
||||
|
||||
Output columns: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary.
|
||||
</Accordion>
|
||||
<Accordion title="tasks show">
|
||||
```bash
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
|
||||
### `tasks show`
|
||||
The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary.
|
||||
|
||||
```bash
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="tasks cancel">
|
||||
```bash
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary.
|
||||
For ACP and subagent tasks, this kills the child session. For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
|
||||
|
||||
### `tasks cancel`
|
||||
</Accordion>
|
||||
<Accordion title="tasks notify">
|
||||
```bash
|
||||
openclaw tasks notify <lookup> <done_only|state_changes|silent>
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="tasks audit">
|
||||
```bash
|
||||
openclaw tasks audit [--json]
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
Surfaces operational issues. Findings also appear in `openclaw status` when issues are detected.
|
||||
|
||||
For ACP and subagent tasks, this kills the child session. For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
|
||||
| Finding | Severity | Trigger |
|
||||
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `stale_queued` | warn | Queued for more than 10 minutes |
|
||||
| `stale_running` | error | Running for more than 30 minutes |
|
||||
| `lost` | warn/error | Runtime-backed task ownership disappeared; retained lost tasks warn until `cleanupAfter`, then become errors |
|
||||
| `delivery_failed` | warn | Delivery failed and notify policy is not `silent` |
|
||||
| `missing_cleanup` | warn | Terminal task with no cleanup timestamp |
|
||||
| `inconsistent_timestamps` | warn | Timeline violation (for example ended before started) |
|
||||
|
||||
### `tasks notify`
|
||||
</Accordion>
|
||||
<Accordion title="tasks maintenance">
|
||||
```bash
|
||||
openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw tasks notify <lookup> <done_only|state_changes|silent>
|
||||
```
|
||||
Use this to preview or apply reconciliation, cleanup stamping, and pruning for tasks and Task Flow state.
|
||||
|
||||
### `tasks audit`
|
||||
Reconciliation is runtime-aware:
|
||||
|
||||
```bash
|
||||
openclaw tasks audit [--json]
|
||||
```
|
||||
- ACP/subagent tasks check their backing child session.
|
||||
- Cron tasks check whether the cron runtime still owns the job.
|
||||
- Chat-backed CLI tasks check the owning live run context, not just the chat session row.
|
||||
|
||||
Surfaces operational issues. Findings also appear in `openclaw status` when issues are detected.
|
||||
Completion cleanup is also runtime-aware:
|
||||
|
||||
| Finding | Severity | Trigger |
|
||||
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `stale_queued` | warn | Queued for more than 10 minutes |
|
||||
| `stale_running` | error | Running for more than 30 minutes |
|
||||
| `lost` | warn/error | Runtime-backed task ownership disappeared; retained lost tasks warn until `cleanupAfter`, then become errors |
|
||||
| `delivery_failed` | warn | Delivery failed and notify policy is not `silent` |
|
||||
| `missing_cleanup` | warn | Terminal task with no cleanup timestamp |
|
||||
| `inconsistent_timestamps` | warn | Timeline violation (for example ended before started) |
|
||||
- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
|
||||
- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
|
||||
- Isolated cron delivery waits out descendant subagent follow-up when needed and suppresses stale parent acknowledgement text instead of announcing it.
|
||||
- Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary. Terminal failed runs announce failure status without replaying captured reply text.
|
||||
- Cleanup failures do not mask the real task outcome.
|
||||
|
||||
### `tasks maintenance`
|
||||
</Accordion>
|
||||
<Accordion title="tasks flow list | show | cancel">
|
||||
```bash
|
||||
openclaw tasks flow list [--status <status>] [--json]
|
||||
openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
Use these when the orchestrating Task Flow is the thing you care about rather than one individual background task record.
|
||||
|
||||
Use this to preview or apply reconciliation, cleanup stamping, and pruning for
|
||||
tasks and Task Flow state.
|
||||
|
||||
Reconciliation is runtime-aware:
|
||||
|
||||
- ACP/subagent tasks check their backing child session.
|
||||
- Cron tasks check whether the cron runtime still owns the job.
|
||||
- Chat-backed CLI tasks check the owning live run context, not just the chat session row.
|
||||
|
||||
Completion cleanup is also runtime-aware:
|
||||
|
||||
- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
|
||||
- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
|
||||
- Isolated cron delivery waits out descendant subagent follow-up when needed and
|
||||
suppresses stale parent acknowledgement text instead of announcing it.
|
||||
- Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary. Terminal failed runs announce failure status without replaying captured reply text.
|
||||
- Cleanup failures do not mask the real task outcome.
|
||||
|
||||
### `tasks flow list|show|cancel`
|
||||
|
||||
```bash
|
||||
openclaw tasks flow list [--status <status>] [--json]
|
||||
openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
Use these when the orchestrating Task Flow is the thing you care about rather
|
||||
than one individual background task record.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Chat task board (`/tasks`)
|
||||
|
||||
Use `/tasks` in any chat session to see background tasks linked to that session. The board shows
|
||||
active and recently completed tasks with runtime, status, timing, and progress or error detail.
|
||||
Use `/tasks` in any chat session to see background tasks linked to that session. The board shows active and recently completed tasks with runtime, status, timing, and progress or error detail.
|
||||
|
||||
When the current session has no visible linked tasks, `/tasks` falls back to agent-local task counts
|
||||
so you still get an overview without leaking other-session details.
|
||||
When the current session has no visible linked tasks, `/tasks` falls back to agent-local task counts so you still get an overview without leaking other-session details.
|
||||
|
||||
For the full operator ledger, use the CLI: `openclaw tasks list`.
|
||||
|
||||
@@ -274,9 +282,7 @@ The summary reports:
|
||||
- **failures** — count of `failed` + `timed_out` + `lost`
|
||||
- **byRuntime** — breakdown by `acp`, `subagent`, `cron`, `cli`
|
||||
|
||||
Both `/status` and the `session_status` tool use a cleanup-aware task snapshot: active tasks are
|
||||
preferred, stale completed rows are hidden, and recent failures only surface when no active work
|
||||
remains. This keeps the status card focused on what matters right now.
|
||||
Both `/status` and the `session_status` tool use a cleanup-aware task snapshot: active tasks are preferred, stale completed rows are hidden, and recent failures only surface when no active work remains. This keeps the status card focused on what matters right now.
|
||||
|
||||
## Storage and maintenance
|
||||
|
||||
@@ -294,44 +300,55 @@ The registry loads into memory at gateway start and syncs writes to SQLite for d
|
||||
|
||||
A sweeper runs every **60 seconds** and handles three things:
|
||||
|
||||
1. **Reconciliation** — checks whether active tasks still have authoritative runtime backing. ACP/subagent tasks use child-session state, cron tasks use active-job ownership, and chat-backed CLI tasks use the owning run context. If that backing state is gone for more than 5 minutes, the task is marked `lost`.
|
||||
2. **Cleanup stamping** — sets a `cleanupAfter` timestamp on terminal tasks (endedAt + 7 days). During retention, lost tasks still appear in audit as warnings; after `cleanupAfter` expires or when cleanup metadata is missing, they are errors.
|
||||
3. **Pruning** — deletes records past their `cleanupAfter` date.
|
||||
<Steps>
|
||||
<Step title="Reconciliation">
|
||||
Checks whether active tasks still have authoritative runtime backing. ACP/subagent tasks use child-session state, cron tasks use active-job ownership, and chat-backed CLI tasks use the owning run context. If that backing state is gone for more than 5 minutes, the task is marked `lost`.
|
||||
</Step>
|
||||
<Step title="Cleanup stamping">
|
||||
Sets a `cleanupAfter` timestamp on terminal tasks (endedAt + 7 days). During retention, lost tasks still appear in audit as warnings; after `cleanupAfter` expires or when cleanup metadata is missing, they are errors.
|
||||
</Step>
|
||||
<Step title="Pruning">
|
||||
Deletes records past their `cleanupAfter` date.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
**Retention**: terminal task records are kept for **7 days**, then automatically pruned. No configuration needed.
|
||||
<Note>
|
||||
**Retention:** terminal task records are kept for **7 days**, then automatically pruned. No configuration needed.
|
||||
</Note>
|
||||
|
||||
## How tasks relate to other systems
|
||||
|
||||
### Tasks and Task Flow
|
||||
<AccordionGroup>
|
||||
<Accordion title="Tasks and Task Flow">
|
||||
[Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
|
||||
|
||||
[Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
|
||||
See [Task Flow](/automation/taskflow) for details.
|
||||
|
||||
See [Task Flow](/automation/taskflow) for details.
|
||||
</Accordion>
|
||||
<Accordion title="Tasks and cron">
|
||||
A cron job **definition** lives in `~/.openclaw/cron/jobs.json`; runtime execution state lives beside it in `~/.openclaw/cron/jobs-state.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications.
|
||||
|
||||
### Tasks and cron
|
||||
See [Cron Jobs](/automation/cron-jobs).
|
||||
|
||||
A cron job **definition** lives in `~/.openclaw/cron/jobs.json`; runtime execution state lives beside it in `~/.openclaw/cron/jobs-state.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications.
|
||||
</Accordion>
|
||||
<Accordion title="Tasks and heartbeat">
|
||||
Heartbeat runs are main-session turns — they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly.
|
||||
|
||||
See [Cron Jobs](/automation/cron-jobs).
|
||||
See [Heartbeat](/gateway/heartbeat).
|
||||
|
||||
### Tasks and heartbeat
|
||||
|
||||
Heartbeat runs are main-session turns — they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly.
|
||||
|
||||
See [Heartbeat](/gateway/heartbeat).
|
||||
|
||||
### Tasks and sessions
|
||||
|
||||
A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that.
|
||||
|
||||
### Tasks and agent runs
|
||||
|
||||
A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status — you do not need to manage the lifecycle manually.
|
||||
</Accordion>
|
||||
<Accordion title="Tasks and sessions">
|
||||
A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that.
|
||||
</Accordion>
|
||||
<Accordion title="Tasks and agent runs">
|
||||
A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status — you do not need to manage the lifecycle manually.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Related
|
||||
|
||||
- [Automation & Tasks](/automation) — all automation mechanisms at a glance
|
||||
- [Task Flow](/automation/taskflow) — flow orchestration above tasks
|
||||
- [Scheduled Tasks](/automation/cron-jobs) — scheduling background work
|
||||
- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
|
||||
- [CLI: Tasks](/cli/tasks) — CLI command reference
|
||||
- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
|
||||
- [Scheduled Tasks](/automation/cron-jobs) — scheduling background work
|
||||
- [Task Flow](/automation/taskflow) — flow orchestration above tasks
|
||||
|
||||
Reference in New Issue
Block a user