# Tasks

## Start

`agent.tasks.start(TaskStartParams**kwargs)  -> TaskStartResponse`

**post** `/agent/tasks`

Starts an agent task and returns a task_id immediately.

### Parameters

- `agent_type: Optional[str]`

- `environment_id: Optional[str]`

- `instruction: Optional[str]`

- `kind: Optional[Literal["desktop", "browser"]]`

  - `"desktop"`

  - `"browser"`

- `max_steps: Optional[int]`

- `model: Optional[str]`

- `persistent: Optional[bool]`

- `screenshot_mode: Optional[Literal["url", "base64"]]`

  - `"url"`

  - `"base64"`

- `temperature: Optional[float]`

- `viewport_height: Optional[int]`

- `viewport_width: Optional[int]`

### Returns

- `class TaskStartResponse: …`

  - `status: Optional[str]`

  - `task_id: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.agent.tasks.start()
print(response.task_id)
```

## Start Stream

`agent.tasks.start_stream(TaskStartStreamParams**kwargs)  -> TaskStartStreamResponse`

**post** `/agent/tasks/stream`

Starts an agent task and streams events via SSE (Content-Type: text/event-stream).

### Parameters

- `agent_type: Optional[str]`

- `environment_id: Optional[str]`

- `instruction: Optional[str]`

- `kind: Optional[Literal["desktop", "browser"]]`

  - `"desktop"`

  - `"browser"`

- `max_steps: Optional[int]`

- `model: Optional[str]`

- `persistent: Optional[bool]`

- `screenshot_mode: Optional[Literal["url", "base64"]]`

  - `"url"`

  - `"base64"`

- `temperature: Optional[float]`

- `viewport_height: Optional[int]`

- `viewport_width: Optional[int]`

### Returns

- `str`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
for task in client.agent.tasks.start_stream():
  print(task)
```

## Retrieve Status

`agent.tasks.retrieve_status(strid)  -> TaskRetrieveStatusResponse`

**get** `/agent/tasks/{id}`

Returns the current status/result for a task.

### Parameters

- `id: str`

### Returns

- `class TaskRetrieveStatusResponse: …`

  - `exit_code: Optional[int]`

  - `status: Optional[str]`

  - `task_id: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.agent.tasks.retrieve_status(
    "id",
)
print(response.task_id)
```

## Inject Message

`agent.tasks.inject_message(strid, TaskInjectMessageParams**kwargs)  -> TaskInjectMessageResponse`

**post** `/agent/tasks/{id}/messages`

Injects a message into a running agent task.

### Parameters

- `id: str`

- `message: Optional[str]`

### Returns

- `class TaskInjectMessageResponse: …`

  - `status: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.agent.tasks.inject_message(
    id="id",
)
print(response.status)
```

## Pause

`agent.tasks.pause(strid)  -> TaskPauseResponse`

**post** `/agent/tasks/{id}/pause`

Pauses a running agent task.

### Parameters

- `id: str`

### Returns

- `class TaskPauseResponse: …`

  - `status: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.agent.tasks.pause(
    "id",
)
print(response.status)
```

## Resume

`agent.tasks.resume(strid)  -> TaskResumeResponse`

**post** `/agent/tasks/{id}/resume`

Resumes a paused agent task.

### Parameters

- `id: str`

### Returns

- `class TaskResumeResponse: …`

  - `status: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.agent.tasks.resume(
    "id",
)
print(response.status)
```