Agent Tasks

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 or the Computers API.

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 — streaming, polling, steering, and writing good instructions
• Web scraping — use agents to scrape complex sites
• Form automation — let agents fill dynamic forms
• Responses API — build your own agent loop with full control