docs/usage/getting-started/task.mdx
Task turns a conversation with an agent into trackable work. Instead of chatting in real time and copying results around, you write down what you want, assign it to an agent, and let the agent run it in the background. The agent posts progress, updates the status when it's done, and replies when you leave a comment.
If you've used Linear or GitHub Issues, the mental model is the same — only the assignee is an agent, and the agent actually does the work.
Use a Task when you want an agent to:
For quick, one-shot questions, stay in the regular chat. For anything you'd otherwise track in a todo list or ticket, create a Task.
Every task moves through a small set of statuses:
| Status | Meaning |
|---|---|
| Backlog | Created but not yet picked up by the agent. |
| In Progress | The agent is actively working on the task. |
| Pending Review | The agent finished and is waiting for you to verify the result. |
| Done | You confirmed the result; the task is closed. |
| Canceled | You closed the task before completion. |
The agent moves a task from Backlog to In Progress, then to Pending Review when it thinks the work is done. The transition to Done is yours to make — see Reviewing Results below.
Click Tasks in the left sidebar to open the task list for your workspace.
Click New Task in the top right. Give it a clear title — the agent uses the title and description to understand what you want.
Describe the work the same way you'd describe it to a teammate. Include any links, files, or constraints the agent needs. You can paste images and attach Resources just like in a regular chat.
Pick an agent from the Assignee dropdown. Choose an agent whose capabilities match the task — for example, the Research Agent for reading and summarizing, or a custom agent you've built. You can reassign later if the first agent isn't the right fit.
Pick Run once for a one-off task, or Repeat to put it on a schedule. See One-off vs. Recurring below.
Click Create. The task lands in Backlog, and the agent picks it up shortly after.
</Steps> <Callout type="info"> You can create a Task directly from any chat message — open the message menu and choose **Turn into Task**. The conversation context is carried over automatically. </Callout>While the task is In Progress, the agent posts updates inside the task — every step it takes, every tool call, and every intermediate result. You don't have to watch in real time; open the task whenever you want to see where things stand.
When the agent thinks it's finished, the task moves to Pending Review. Open the task detail page to verify the result. You have two options:
Done and closes out.A Pending Review task never auto-completes; you stay in control of when work is done.
Every task has a comment thread. Use comments to:
The agent reads new comments automatically and follows up. There's no separate "send" — your comment is the instruction.
<Callout type="info"> If the agent is in the middle of a run, your comment is queued until the next checkpoint so it doesn't interrupt mid-step. </Callout>Pages the agent creates during execution — research notes, summaries, drafts, anything written to your workspace — are listed in the Artifacts section of the task detail page. Open, share, or keep editing them directly from there without leaving the task.
Tasks support two schedule modes.
The default. The agent runs the task immediately, posts a result, and moves it to Pending Review for you to confirm. Use this for everything that doesn't need to repeat.
Put the task on a schedule and the agent re-runs it automatically. Each run is appended to the same task as a new entry, so you build up a history you can compare across runs.
Supported intervals:
You can pause, resume, or change the schedule at any time from the task detail page. Pausing keeps history intact; deleting removes the task and its run history.
A few patterns that work well as Tasks: