Skip to main content
A task is a unit of coding work the platform runs for you in a sandbox. You describe what you want; specialist agents plan, build, and render it; you review the result and send it to your developers.

​
The lifecycle

1

Start

start_task(project_id, workspace_id, instruction) returns a task_id immediately and status = running. The work executes in the background - don’t block waiting on the call.
2

Poll

Poll get_task(project_id, task_id). Report progress as you go. The task is done when its status is terminal (COMPLETED / DISCARDED) or when it needs your input.
3

Review

get_task_messages shows what the agent said and did. get_task_pr_diff returns the unified git diff - the “Files Changed” view - so you can pull the changes into the editor even before a PR exists.
4

Iterate

Reply or redirect with continue_task(project_id, task_id, instruction). If a run is going the wrong way, stop_task cancels the in-flight agent so you can continue with new guidance.
5

Ship

When the user has approved the changes, complete_task finalizes the task and opens or updates the pull request. This is the irreversible “send to devs” action - only call it on approval.
complete_task is a real handoff: it opens/updates a PR for your developers. Treat it like clicking Send to Devs in Studio - call it only when the user has explicitly approved the changes.

​
Versions

A task can produce multiple versions of its output. get_task shows the active version; checkout_task_version switches to another; get_task_pr_diff(version=N) diffs a specific one. To throw away sandbox changes without deleting the task, use discard_task_changes.

​
Working with tasks

  • list_tasks - all your tasks for a project, most recently active first.
  • rename_task - set the human-facing title.
  • archive_task - hide a task (non-destructive; the PR is untouched).
  • update_task_env - re-sync a running task’s sandbox after you change project env vars.

​
The plan (spec) document

Before building, you can shape the plan the agent follows:
  • list_spec_versions / get_task_spec_version - read the versioned plan document.
  • update_spec_content - edit the latest plan in place.
  • create_spec_version - save a new plan version, keeping history.

​
Agent transparency

To see exactly what ran: list_agent_histories lists one row per agent run/turn, and get_agent_history_detail returns the full message and tool-call trace for a single run.
Load the built-in walkthrough any time with load_autonomy_skill name="tasks".