Task

A Task is a single automation job executed by an AI agent in a browser environment. Tasks contain your instructions for what the AI should accomplish.

What is a Task?

Examples:

  • “Log into Gmail and count unread emails”
  • “Search for top 10 Hacker News posts and return titles and URLs”
  • “Extract product prices from an e-commerce site”

Key Properties

  • task: Your instruction to the AI agent (max 20,000 characters)
  • llm: AI model ("browser-use-llm", "gemini-flash-latest", "gpt-4.1", "o3", "claude-sonnet-4-20250514", "claude-sonnet-4-5-20250929", etc.)
  • sessionId: Session where task runs (optional - auto-created if not provided)
  • status: started, paused, finished, or stopped
  • output: Final result from the agent
  • inputFiles / outputFiles: Files for input/output

Execution Models

Auto-Session (Simple)

1import { BrowserUseClient } from "browser-use-sdk";
2
3const client = new BrowserUseClient({ apiKey: "bu_..." });
4
5const task = await client.tasks.createTask({
6 task: "Search for top 10 Hacker News posts",
7 llm: "browser-use-llm"
8});
9
10const result = await task.complete();
11console.log(result.output);

Best for: Simple tasks, no login required, proof of concepts

Custom Session (Advanced)

1// Create session
2const session = await client.sessions.createSession({ profileId: "profile_123" });
3
4// Upload credentials file
5const credFile = await client.files.upload("credentials.json");
6
7// Run login task
8const loginTask = await client.tasks.createTask({
9 sessionId: session.id,
10 llm: "browser-use-llm",
11 task: "Log into admin dashboard using uploaded credentials",
12 inputFiles: [credFile.id]
13});
14
15await loginTask.complete();
16
17// Run data task (login state preserved)
18const dataTask = await client.tasks.createTask({
19 sessionId: session.id,
20 llm: "browser-use-llm",
21 task: "Export user data as CSV"
22});
23
24const result = await dataTask.complete();

Best for: Multi-step workflows, login required, related tasks

Task Control

1// Stream progress
2for await (const update of task.stream()) {
3 console.log(`Status: ${update.status}`);
4}
5
6// Control tasks
7await task.pause();
8await task.resume();
9await task.stop();

Files

1// Input files
2const task = await client.tasks.createTask({
3 task: "Analyze the uploaded image",
4 llm: "browser-use-llm",
5 inputFiles: ["screenshot.png"]
6});
7
8// Output files
9const result = await task.complete();
10for (const file of result.outputFiles) {
11 const data = await client.files.download(file.id);
12}

Best Practices

Task Instructions:

  • Be specific: “Extract product names and prices from first page” vs “get product info”
  • Set boundaries: Specify pages to visit, items to process
  • Include context: Mention login requirements, data format

Performance:

  • Use auto-session for simple tasks
  • Reuse sessions for related tasks

Next Steps