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.
6

Track the PR

After Send to Devs the task sits at sent while the PR is open with the dev. Call refresh_pr_status(project_id) when the user asks about their PR to reconcile against the live PR state - the task then flips to merged (the dev merged it) or closed_by_dev (they closed it without merging). get_task already runs this refresh itself for a sent task, so a plain poll picks it up too. Don’t poll refresh_pr_status on a loop.
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. To see a finished version, use get_version_preview_url - it serves a published build, so the link keeps working after the sandbox is gone. The live-sandbox surfaces (get_task_preview_url, get_storybook_url) are a different thing: they show whatever is checked out in the task’s sandbox right now, not a version.

​
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).
  • Env var changes reach a task’s sandbox on its next run - there is no live re-sync.

​
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: get_task_messages returns the chat timeline with typed parts - the agent’s reasoning, every tool call (name, args, result), version cards, and any pending approval or question cards with their tool_call_ids.
Load the built-in walkthrough any time with load_autonomy_skill name="tasks".