Session

A Session is a stateful browser environment where AI agents execute tasks. Sessions maintain browser state, cookies, and context between multiple tasks.

What is a Session?

A persistent browser instance that:

• Executes multiple tasks sequentially
• Maintains login state between tasks
• Preserves cookies and browser state
• Provides real-time viewing via live URL

Key Properties

• id: Unique session identifier
• status: "active" or "stopped"
• liveUrl: Real-time browser viewing URL
• tasks: All tasks executed in this session
• profileId: Profile for browser configuration (optional)

Creating and Managing Sessions

1
import { BrowserUseClient } from "browser-use-sdk";
2
3
const client = new BrowserUseClient({ apiKey: "bu_..." });
4
5
// Create sessions
6
const session = await client.sessions.createSession();
7
const profileSession = await client.sessions.createSession({ profileId: "profile_123" });
8
9
// Manage sessions
10
const sessions = await client.sessions.listSessions();
11
await client.sessions.stopSession(session.id);
12
console.log(`Watch live: ${session.liveUrl}`);

Usage Patterns

Auto-Session (Implicit)

1
// Automatically creates and cleans up session
2
const task = await client.tasks.createTask({
3
    task: "Search for laptop prices on Amazon"
4
});

✅ Simple ❌ No state preservation

Custom Session (Explicit)

1
const session = await client.sessions.createSession({ profileId: "user_profile_123" });
2
3
// Run multiple related tasks
4
const loginTask = await client.tasks.createTask({
5
    sessionId: session.id,
6
    task: "Log into admin.example.com"
7
});
8
9
const dataTask = await client.tasks.createTask({
10
    sessionId: session.id,
11
    task: "Export user data"
12
});
13
14
// Cleanup
15
await client.sessions.stopSession(session.id);

✅ State preservation ✅ Multi-step workflows ❌ Manual cleanup

State Management

What’s Preserved:

• Authentication cookies and tokens
• Local storage and session data
• Browser history and form data
• Downloaded resources and cache

Profile Inheritance:

1
// Session inherits login state from profile
2
const session = await client.sessions.createSession({ profileId: "logged_in_profile" });
3
4
// Already logged in from profile
5
const task = await client.tasks.createTask({
6
    sessionId: session.id,
7
    task: "Check dashboard notifications"
8
});

Real-Time Monitoring

1
// Live viewing
2
console.log(`Watch live: ${session.liveUrl}`);
3
4
// Public sharing
5
const share = await client.sessions.createShare(session.id);
6
console.log(`Public URL: ${share.url}`);

Agent Session vs Browser Session

Browser Session (Standalone): Direct Chrome DevTools Protocol access for custom automation Agent Session (AI-Powered): AI agent environment for natural language task execution

These are separate products serving different use cases.

Best Practices

Use Auto-Session for: Simple tasks, no login, proof of concepts Use Custom Sessions for: Multi-step workflows, authentication, production apps

Session Management:

• Always stop sessions when done
• Use profiles to reduce setup time
• Don’t share live URLs publicly
• Clean up sessions with sensitive data

Next Steps