---
title: Run an AI Agent | Lightcone
description: Give a natural language instruction and let an AI agent complete the task autonomously.
---

This guide shows how to run an autonomous agent that controls a browser to complete a task. The agent uses a vision model to see the screen and decide what to click, type, or scroll — you just provide the instruction.

**Prerequisites**: Complete the [Quickstart](/guides/quickstart/index.md) and have `TZAFON_API_KEY` set in your environment.

## Start an agent with streaming

Streaming gives you real-time visibility into what the agent is doing:

run\_agent.py

```
from tzafon import Lightcone


client = Lightcone()


for event in client.agent.tasks.start_stream(
    instruction="Go to news.ycombinator.com, find the top story, and tell me what it's about",
    kind="browser",
    model="tzafon.northstar-cua-fast",
    max_steps=20,
):
    print(event)
```

run\_agent.ts

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


const client = new Lightcone();


const stream = await client.agent.tasks.startStream({
  instruction: "Go to news.ycombinator.com, find the top story, and tell me what it's about",
  kind: "browser",
  model: "tzafon.northstar-cua-fast",
  max_steps: 20,
});


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

## Fire and poll

For background tasks, start async and check status periodically:

```
import time


task = client.agent.tasks.start(
    instruction="Navigate to example.com and take a screenshot",
    kind="browser",
)
print(f"Task started: {task.task_id}")


# Poll for completion
while True:
    status = client.agent.tasks.retrieve_status(task.task_id)
    print(f"Status: {status.status}")


    if status.status in ("completed", "failed"):
        print(f"Exit code: {status.exit_code}")
        break


    time.sleep(2)
```

```
const task = await client.agent.tasks.start({
  instruction: "Navigate to example.com and take a screenshot",
  kind: "browser",
});
console.log(`Task started: ${task.task_id}`);


// Poll for completion
while (true) {
  const status = await client.agent.tasks.retrieveStatus(task.task_id!);
  console.log(`Status: ${status.status}`);


  if (status.status === "completed" || status.status === "failed") {
    console.log(`Exit code: ${status.exit_code}`);
    break;
  }


  await new Promise((r) => setTimeout(r, 2000));
}
```

## Steer the agent mid-task

Inject a message to change the agent’s direction while it’s running:

```
task = client.agent.tasks.start(
    instruction="Research the latest AI news",
    kind="browser",
)


# After a few seconds, redirect the agent
import time
time.sleep(5)


client.agent.tasks.inject_message(
    task.task_id,
    message="Actually, focus specifically on news about large language models",
)
```

```
const task = await client.agent.tasks.start({
  instruction: "Research the latest AI news",
  kind: "browser",
});


// Redirect after a delay
await new Promise((r) => setTimeout(r, 5000));


await client.agent.tasks.injectMessage(task.task_id!, {
  message: "Actually, focus specifically on news about large language models",
});
```

## Pause and resume

Pause the agent to save compute, then resume when ready:

```
client.agent.tasks.pause(task.task_id)
print("Agent paused")


# ... later ...


client.agent.tasks.resume(task.task_id)
print("Agent resumed")
```

```
await client.agent.tasks.pause(task.task_id!);
console.log("Agent paused");


// ... later ...


await client.agent.tasks.resume(task.task_id!);
console.log("Agent resumed");
```

## Writing good instructions

The quality of your instruction directly affects agent performance.

**Good instructions:**

- “Go to amazon.com, search for ‘mechanical keyboard’, sort by price low to high, and screenshot the first 3 results”
- “Navigate to github.com/anthropics/claude-code, click on the Issues tab, and count how many open issues there are”

**Vague instructions (avoid):**

- “Find something interesting online”
- “Do some research”

Be specific about the goal, the site, and what constitutes success. The agent works best when it knows exactly what “done” looks like.

## See also

- [**Agent Tasks**](/guides/agent-tasks/index.md) — configuration options, pause/resume, and message injection
- [**Web scraping**](/use-cases/web-scraping/index.md) — agent-powered data extraction
- [**Form automation**](/use-cases/form-automation/index.md) — agent-powered form filling
- [**CUA protocol**](/guides/cua-protocol/index.md) — build your own agent loop for more control