Collaborate with tasks

Learn how tasks let agents handle one-shot work.

This guide shows how tasks work, where they live, and how to manage them.

What are tasks?

Tasks are one-shot jobs for an agent. A task has an input and a few fields: the input tells the agent what to do, while fields identify, display, track, and manage the task. Most fields are optional or managed by the runtime.

Field	Optional?	Meaning
`id`	Usually auto-generated	Stable task id generated by Toolang. You usually do not need to write it yourself.
`title`	Yes	Optional display title.
`state`	Yes	Task lifecycle state: `active`, `inactive`, or `archived`. Defaults to `active`.
`stage`	Yes	Task progress stage: `todo`, `running`, `done`, or `failed`. Defaults to `todo`.

state controls whether a task is available to run. stage tracks the task’s progress. Only tasks with state: active and stage: todo are picked up for execution.

Tasks are usually stored as Markdown files in the agent home, under ${TOOLANG_ROOT}/agents/<agent>/tasks/. Root-scoped tasks are not supported yet. In a Markdown task, fields go in the frontmatter, and the input goes in the body:

---
id: 3nprht9x
title: Review API changes
state: active
stage: todo
---
 
Review the API changes and summarize risks.

You can also start with a minimal task. Toolang will fill in defaults such as id, state, and stage:

---
title: Review API changes
---
 
Review the API changes and summarize risks.

Tasks are simple Markdown files. You can edit them directly with your favorite editor or manage them with the CLI.

Create and edit tasks

Use these commands to create, edit, and inspect tasks. Here, alice is the agent whose tasks you are managing.

Command	Meaning
`toolang alice task new`	Create a task and open it in your editor.
`toolang alice task edit <id>`	Open an existing task.
`toolang alice task list`	List current tasks.

Retire tasks

Use these commands to take tasks out of execution, bring them back, or remove archived tasks. Again, alice is the agent whose tasks you are managing.

Command	Meaning
`toolang alice task pause <id>`	Temporarily retire a task by setting it to `inactive`.
`toolang alice task resume <id>`	Bring an inactive task back by setting it to `active`.
`toolang alice task archive <id>`	Retire a task and move it into the archive.
`toolang alice task restore <id>`	Restore an archived task as `active`.
`toolang alice task restore <id> --inactive`	Restore an archived task as `inactive`.
`toolang alice task delete <id>`	Permanently delete an archived task.

active tasks can be picked up for execution, inactive tasks are kept but skipped, and archived tasks are retired and hidden from the default list. Delete is destructive and only allowed for archived tasks.

How tasks run

Toolang checks tasks during its pulse scan. Only tasks with state: active and stage: todo are submitted for execution. Before a task starts, Toolang marks it as running to avoid duplicate runs.

When a task runs, Toolang sends the task input to the agent. The agent should update the task before it finishes: set stage: done when the work is complete, or stage: failed when it is blocked, failed, or unfinished. To retry a failed task, edit it back to stage: todo.

Task results are not written back to the task definition. The task file stays focused on the goal, while runtime status, run history, and results are stored separately by Toolang.

Task runs use the task surface. If the agent defines a task thunk, Toolang uses it. Otherwise, it falls back to the runtime default.