---
title: Agent Tasks | Lightcone
description: Autonomous AI agents that drive computers to complete tasks from natural language instructions.
---

An **agent task** is an autonomous AI agent that controls a computer session to complete a goal you describe in natural language. You provide an instruction, and the agent sees the screen, decides what to do, and acts — clicking, typing, scrolling, and navigating until the task is done.

Agent Tasks are the highest-level way to use Lightcone — you describe what you want, and the agent handles everything. For more control over each step, see the [Responses API](/guides/responses-api/index.md) or the [Computers API](/guides/computers/index.md).

## Start a task

### Async (fire and forget)

Start a task and get back a `task_id` immediately. Poll for status later.

```
from tzafon import Lightcone


client = Lightcone()


task = client.agent.tasks.start(
    instruction="Go to github.com and find the trending Python repositories",
    kind="browser",
)
print(task.task_id)  # Use this to check status later
```

```
import Lightcone from "@tzafon/lightcone";


const client = new Lightcone();


const task = await client.agent.tasks.start({
  instruction: "Go to github.com and find the trending Python repositories",
  kind: "browser",
});
console.log(task.task_id);
```

### Streaming (real-time events)

Stream events via SSE as the agent works:

```
for event in client.agent.tasks.start_stream(
    instruction="Search for 'machine learning' on Wikipedia and summarize the first paragraph",
    kind="browser",
):
    print(event)
```

```
const stream = await client.agent.tasks.startStream({
  instruction: "Search for 'machine learning' on Wikipedia and summarize the first paragraph",
  kind: "browser",
});


for await (const event of stream) {
  console.log(event);
}
```

## Check task status

```
status = client.agent.tasks.retrieve_status(task.task_id)
print(status.status)     # e.g., "running", "completed"
print(status.exit_code)  # 0 on success
```

```
const status = await client.agent.tasks.retrieveStatus(task.task_id!);
console.log(status.status);
console.log(status.exit_code);
```

## Pause and resume

Pause a running task to intervene or save resources, then resume it:

```
client.agent.tasks.pause(task.task_id)
# ... do something ...
client.agent.tasks.resume(task.task_id)
```

```
await client.agent.tasks.pause(task.task_id!);
// ... do something ...
await client.agent.tasks.resume(task.task_id!);
```

## Inject a message

Send a message to the agent while it’s running to redirect or clarify:

```
client.agent.tasks.inject_message(
    task.task_id,
    message="Focus on the top 3 results only",
)
```

```
await client.agent.tasks.injectMessage(task.task_id!, {
  message: "Focus on the top 3 results only",
});
```

## Configuration options

| Parameter                            | Default                       | Description                                                         |
| ------------------------------------ | ----------------------------- | ------------------------------------------------------------------- |
| `instruction`                        | —                             | Natural language description of what the agent should do (required) |
| `kind`                               | —                             | `"browser"` or `"desktop"` (required)                               |
| `model`                              | `"tzafon.northstar-cua-fast"` | Which model to use for the agent                                    |
| `max_steps`                          | `100`                         | Maximum number of actions the agent can take                        |
| `temperature`                        | `0.2`                         | Model temperature (higher = more creative)                          |
| `screenshot_mode`                    | `"url"`                       | `"url"` or `"base64"` for screenshot delivery                       |
| `viewport_width` / `viewport_height` | `1280` / `720`                | Browser viewport dimensions in pixels                               |
| `persistent`                         | `false`                       | Save session state after task completes                             |
| `environment_id`                     | —                             | Restore a previous session’s state                                  |

For complex tasks, set a higher `max_steps` to give the agent more room to work. For simple tasks, a lower value keeps things fast and focused.

## See also

- [**Run an AI agent**](/guides/run-an-agent/index.md) — streaming, polling, steering, and writing good instructions
- [**Web scraping**](/use-cases/web-scraping/index.md) — use agents to scrape complex sites
- [**Form automation**](/use-cases/form-automation/index.md) — let agents fill dynamic forms
- [**Responses API**](/guides/responses-api/index.md) — build your own agent loop with full control