​
Creating a Browser Session with SDK

The AgentGo SDK provides a simple way to create and manage distributed browser sessions. This guide explains how to use the SDK to create sessions with various configuration options.

​
Prerequisites

Before creating a browser session, make sure you have:

  1. An AgentGo API key (obtain from Developer Settings)
  2. AgentGo SDK installed: npm i @agentgo-dev/sdk

​
Basic Session Creation

Here’s how to create a browser session using the AgentGo SDK:

import { AgentGo } from '@agentgo-dev/sdk';

const client = new AgentGo({
  apiKey: 'your_api_key_here',
});

// Create a basic session
const session = await client.sessions.create();

console.log('Session ID:', session.id);
console.log('Connection URL:', session.connectionUrl);

​
Session Configuration Parameters

The SDK supports the following parameters when creating sessions:

ParameterTypeDescriptionDefault
regionstringGeographic region code (see available regions below)“US”
// Create a session with configuration
const session = await client.sessions.create({
  region: 'us',           // Optional: Geographic region code
});

​
Available Regions

AgentGo supports browser sessions in the following regions:

Europe
Region Codes
Asia
Region Codes
North America
Region Codes
Africa
Region Codes
South America
Region Codes
Oceania
Region Codes

​
Session Management Operations

​
Create Session

const session = await client.sessions.create({
  region: 'us'            // Use lowercase region codes
});

​
List Sessions

const sessions = await client.sessions.list({
  status: 'IDLE',         // Optional: Filter by status (IDLE/RUNNING/EXPIRED)
  region: 'us',           // Optional: Filter by region (use lowercase)
  limit: 20,              // Optional: Max results (1-100)
});

console.log('Active sessions:', sessions.sessions.length);

​
Retrieve Session Details

const sessionDetails = await client.sessions.retrieve('session-id');
console.log('Session status:', sessionDetails.status);
console.log('Session region:', sessionDetails.region);

​
Advanced Configuration Options

When connecting to sessions via Playwright, you can use additional options:

OptionDescriptionDefault
_sessionIdUse specific session IDAuto-generated
_regionGeographic region”US”
_disable_proxyDisable proxy usagefalse (proxy enabled)

These options are used when connecting Playwright to your SDK-created session (covered in the next section).

​
Complete Example

import { AgentGo } from '@agentgo-dev/sdk';

const client = new AgentGo({
  apiKey: 'your_api_key_here',
});

async function createAndManageSession() {
  // Create a session with region selection
  const session = await client.sessions.create({
    region: 'us'            // Use any supported region code
  });

  console.log('Created session:', session.id);
  
  // List all sessions
  const allSessions = await client.sessions.list({
    limit: 10
  });
  
  console.log('Total sessions:', allSessions.sessions.length);
  
  // Get session details
  const details = await client.sessions.retrieve(session.id);
  console.log('Session status:', details.status);
  
  return session;
}

createAndManageSession().catch(console.error);

​
Monitoring Sessions

You can monitor your sessions through the AgentGo dashboard at: https://app.agentgo.live/organization/dev/sessions

The dashboard shows:

  • Session ID and status
  • Creation time and duration
  • Region and resource usage
  • Connection details

Next, learn how to use your session with Playwright for browser automation.

Quick start for AgentGo with Playwright.Using a Browser Session