Skip to content
Lightcone Lightcone
Dashboard
Guides
Run an AI Agent

Run an AI Agent

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 and have TZAFON_API_KEY set in your environment.

Start an agent with streaming

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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”

See also

Section titled “See also”