> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks

> Create and manage individual units of agent work

A task is a persisted unit of work assigned to one agent. Tasks can run independently or be generated when a [mission](/docs/orchestration/missions) executes.

## Create a task

```typescript theme={null}
const task = await client.createTask({
  title: "Build the authentication endpoint",
  description: "Implement POST /v1/login and add integration tests.",
  assignTo: "backend-dev",
  expectations: [
    { type: "test", command: "pnpm test auth" },
    { type: "file_exists", paths: ["src/routes/login.ts"] }
  ],
  expectedOutcomes: [
    { type: "file", label: "Login route", path: "src/routes/login.ts" }
  ]
});
```

The REST endpoint is `POST /v1/tasks`. It requires `title`, `description`, and `assignTo`; optional fields include `draft`, `loop`, `expectations`, `expectedOutcomes`, `dependsOn`, `group`, `maxDuration`, `retryPolicy`, `notifications`, `sideEffects`, `executionMode`, `sandbox`, and `user`.

`user` is opaque attribution metadata. Polpo persists and propagates it but does not authenticate it.

Use `sandbox.isolation` to choose whether a run can reuse a warm sandbox or must start fresh:

```typescript theme={null}
await client.createTask({
  title: "Run migration tests",
  description: "Apply migrations in isolation and report failures.",
  assignTo: "qa-agent",
  sandbox: { isolation: "fresh" }
});
```

Task and request sandbox policy overrides the agent default. See [Runtime Sandboxes](/docs/platform/runtime-sandboxes).

## Persisted task

The runtime adds fields such as `id`, `status`, `retries`, `maxRetries`, timestamps, `phase`, `result`, `outcomes`, `deadline`, and `priority`. `result` contains process output and the current assessment; older assessments are retained in `assessmentHistory`.

`expectedOutcomes` declare artifacts the agent should produce. Each entry requires `type` and `label`, with optional `description`, `path`, `mimeType`, `required`, and `tags`. Actual `outcomes` are registered at runtime as `file`, `text`, `url`, `json`, or `media` artifacts.

## Dependencies

For a standalone persisted task, `dependsOn` contains task IDs. Inside a mission document, `dependsOn` contains unique task titles because IDs do not exist until mission execution.

## Status and phase

Task statuses are:

```txt theme={null}
draft -> pending -> assigned -> in_progress -> review -> done
                    |             |           |
                    +-------------+-----------+-> awaiting_approval
                                                -> failed -> pending
```

The exact valid transitions are:

| From                | Allowed next states                     |
| ------------------- | --------------------------------------- |
| `draft`             | `pending`                               |
| `pending`           | `assigned`, `awaiting_approval`         |
| `awaiting_approval` | `assigned`, `failed`, `done`, `pending` |
| `assigned`          | `in_progress`, `awaiting_approval`      |
| `in_progress`       | `review`, `failed`, `awaiting_approval` |
| `review`            | `done`, `failed`, `awaiting_approval`   |
| `failed`            | `pending`                               |
| `done`              | none                                    |

`phase` is separate from status and can be `execution`, `review`, `fix`, or `clarification`.

Tasks without expectations or metrics do not enter an LLM quality review merely because they completed; successful execution can transition directly to done. See [Assessment](/docs/orchestration/assessment).

## Retries and side effects

```json theme={null}
{
  "retryPolicy": {
    "escalateAfter": 2,
    "fallbackAgent": "senior-dev",
    "escalateModel": "anthropic/claude-sonnet-4-5"
  },
  "sideEffects": true
}
```

`fallbackAgent` and `escalateModel` apply to escalation retries. They belong to the task or mission task, not the agent config.

When `sideEffects` is true, automatic fix and retry paths are blocked before repeating irreversible work. The task moves to `awaiting_approval` so a human can decide how to continue. It does not imply approval before the first execution.

## Local deployment

Standalone task files live under `.polpo/tasks/*.json`. They are opt-in during deployment:

```bash theme={null}
polpo deploy --include-tasks
```

`polpo deploy --all` also includes them. Mission tasks should normally be authored inside the mission's `data` document instead.

See the [Tasks API](/agent-api/tasks) for update, retry, kill, reassess, queue, force-fail, and activity endpoints.