---
title: Task lifecycle
description: Create, poll, and continue asynchronous Research Agent tasks.
sidebar:
  icon: workflow
  hidden: true
---

Every Research Agent interaction is a task. A task preserves its conversation, so you can answer a clarification without starting the research over.

```mermaid
flowchart LR
  A["Create task"] --> B["pending"]
  B --> C{"Result"}
  C --> D["complete"]
  C --> E["failed"]
  C --> F["clarification"]
  F --> G["Continue task"]
  G --> B
```

## Create a task

`POST /api/agents/{agentId}/tasks/create`

The JSON body requires a non-empty `message`.

```json
{
  "message": "18 cubic foot white refrigerator"
}
```

`message` can be a manufacturer part number, a full model designation, or a natural-language product description.

The endpoint returns `202 Accepted` with `status: "pending"`, a stable `taskId`, and the `statusUrl` to poll.

## Poll a task

`GET /api/agents/{agentId}/tasks/{taskId}`

Keep the same bearer token, `agentId`, and `taskId` for every poll. Possible task states are:

| Status | Meaning | Next action |
| --- | --- | --- |
| `pending` | The task is still running, or a newly submitted follow-up has not been answered. | Poll the `statusUrl` again. |
| `complete` | A result or clarification question is available. | Consume the result or answer the question. |
| `failed` | Research did not complete. | Read `error`; decide whether to correct the request and create a new task. |

## Answer a clarification

Research Agent can return a structured question when the request is ambiguous:

```json
{
  "status": "complete",
  "taskId": "<TASK_ID>",
  "taskUrl": "https://agents.sibi.ai/agents/<AGENT_ID>/tasks/<TASK_ID>",
  "context": "I found two possible product families.",
  "question": {
    "question": "Which manufacturer should I research?",
    "options": [
      {
        "label": "Manufacturer A",
        "description": "The model family used in the original installation"
      },
      {
        "label": "Manufacturer B",
        "description": null
      }
    ],
    "allowMultiple": false
  }
}
```

The `complete` status means the current turn finished; the task itself remains reusable. Send the selected answer as a new `message`:

```bash
curl --request POST \
  "https://agents.sibi.ai/api/agents/${RESEARCH_AGENT_ID}/tasks/<TASK_ID>/messages" \
  --header "Authorization: Bearer ${SIBI_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"message":"Manufacturer A"}'
```

The endpoint returns `202 Accepted` and the same task identifiers. Resume polling its `statusUrl`.

## Add attachments

Task creation and continuation accept an optional `attachments` array. Each item requires:

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"file"` | Identifies the attachment as a file. |
| `url` | `string` | An `http(s)` URL or supported `data:` URL. |
| `mediaType` | `string` | The file's media type. |
| `filename` | `string` | The filename presented to Research Agent. |

```json
{
  "message": "Find replacements for the products in this file.",
  "attachments": [
    {
      "type": "file",
      "url": "https://files.example.com/products.csv",
      "mediaType": "text/csv",
      "filename": "products.csv"
    }
  ]
}
```

Supported `data:` URL media types include images, PDF, CSV, legacy Excel, and XLSX. Use hosted `https` URLs for larger files.

> **Task ownership**
>
> A task belongs to the authenticated user that created it. Another user cannot poll or continue the task, even with access to the same agent.