Java SDK - Stagehand

Overview

The Java SDK provides a Java-native interface to Stagehand’s browser automation capabilities. Like the Python SDK, it communicates with the Stagehand API server to leverage the full power of the TypeScript core engine.

The Java SDK is currently under development. This page describes the planned architecture and usage patterns. Check the GitHub repository for the latest status.

Architecture

The Java SDK follows the same client-server architecture as other language SDKs:

┌─────────────────┐
│   Java Client   │
│   (Your Code)   │
└────────┬────────┘
         │ HTTP/REST
         ▼
┌─────────────────┐
│  API Server     │
│  (TypeScript)   │
└────────┬────────┘
         │ CDP
         ▼
┌─────────────────┐
│  Browser        │
│  (Browserbase)  │
└─────────────────┘

Installation

Maven

<dependency>
    <groupId>com.browserbase</groupId>
    <artifactId>stagehand</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

dependencies {
    implementation 'com.browserbase:stagehand:1.0.0'
}

Repository

The Java SDK will be maintained in a dedicated repository:

Java SDK on GitHub

View the Java SDK repository (coming soon)

Quick Start

import com.browserbase.stagehand.Stagehand;
import com.browserbase.stagehand.StagehandConfig;
import com.browserbase.stagehand.models.*;

import java.util.Map;
import java.util.concurrent.CompletableFuture;

public class Example {
    public static void main(String[] args) {
        // Configure Stagehand
        StagehandConfig config = StagehandConfig.builder()
            .env("BROWSERBASE")
            .apiKey(System.getenv("BROWSERBASE_API_KEY"))
            .projectId(System.getenv("BROWSERBASE_PROJECT_ID"))
            .model(ModelConfig.builder()
                .modelName("openai/gpt-4o")
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .build())
            .verbose(1)
            .build();
        
        Stagehand stagehand = new Stagehand(config);
        
        try {
            // Initialize
            stagehand.init().get();
            
            // Navigate
            stagehand.page().goto("https://github.com/browserbase").get();
            
            // Perform action
            ActResult actResult = stagehand
                .act("click on the stagehand repo")
                .get();
            
            System.out.println("Action: " + actResult.getMessage());
            
            // Extract data
            Map<String, Object> schema = Map.of(
                "description", "string",
                "stars", "number"
            );
            
            ExtractResult<?> extractResult = stagehand
                .extract("extract the repository details", schema)
                .get();
            
            System.out.println("Data: " + extractResult.getData());
            
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            stagehand.close();
        }
    }
}

Core API

Stagehand Class

The main entry point for the SDK:

StagehandConfig config = StagehandConfig.builder()
    .env("BROWSERBASE")
    .apiKey("your-api-key")
    .projectId("your-project-id")
    .model(ModelConfig.builder()
        .modelName("openai/gpt-4o")
        .apiKey("your-openai-key")
        .build())
    .verbose(1)
    .selfHeal(true)
    .cacheDir("./cache")
    .build();

Stagehand stagehand = new Stagehand(config);

Methods

act()

Execute actions using natural language:

// Simple action
CompletableFuture<ActResult> future = stagehand.act("click the login button");
ActResult result = future.get();

// With variables
Map<String, String> variables = Map.of(
    "email", "user@example.com"
);

ActOptions options = ActOptions.builder()
    .variables(variables)
    .timeout(5000)
    .build();

stagehand.act("fill the email field with {{email}}", options).get();

extract()

Extract structured data:

Map<String, Object> schema = Map.of(
    "name", "string",
    "email", "string",
    "age", "number"
);

ExtractResult<Map<String, Object>> result = stagehand
    .extract("get user information", schema)
    .get();

Map<String, Object> data = result.getData();
System.out.println("Name: " + data.get("name"));

observe()

Find elements without acting:

CompletableFuture<List<Action>> future = stagehand
    .observe("find all product cards");

List<Action> actions = future.get();
for (Action action : actions) {
    System.out.println("Selector: " + action.getSelector());
    System.out.println("Description: " + action.getDescription());
}

agent.execute()

Run multi-step tasks:

Agent agent = stagehand.agent();

AgentExecuteOptions options = AgentExecuteOptions.builder()
    .maxSteps(10)
    .build();

AgentResult result = agent
    .execute("Search for Java tutorials and extract the top 3 results", options)
    .get();

System.out.println("Message: " + result.getMessage());
for (AgentAction action : result.getActions()) {
    System.out.println("Step: " + action.getType());
}

Configuration

StagehandConfig

StagehandConfig config = StagehandConfig.builder()
    .env("BROWSERBASE")  // or "LOCAL"
    .apiKey("your-api-key")
    .projectId("your-project-id")
    .model(ModelConfig.builder()
        .modelName("openai/gpt-4o")
        .apiKey("your-model-key")
        .temperature(0.7)
        .build())
    .verbose(1)  // 0, 1, or 2
    .systemPrompt("Custom AI instructions")
    .selfHeal(true)
    .cacheDir("./stagehand-cache")
    .domSettleTimeout(30000)
    .build();

ModelConfig

Supported models:

ModelConfig model = ModelConfig.builder()
    .modelName("openai/gpt-4o")  // or claude, gemini, etc.
    .apiKey(System.getenv("MODEL_API_KEY"))
    .temperature(0.7)
    .build();

Async vs Sync

The SDK uses CompletableFuture for async operations:

// Async
CompletableFuture<ActResult> future = stagehand.act("click button");
future.thenAccept(result -> {
    System.out.println(result.getMessage());
});

// Sync (blocking)
ActResult result = stagehand.act("click button").get();

Examples

Web Scraping

public class WebScraper {
    public static void scrapeNews() throws Exception {
        Stagehand stagehand = new Stagehand(config);
        stagehand.init().get();
        
        try {
            stagehand.page().goto("https://news.ycombinator.com").get();
            
            Map<String, Object> schema = Map.of(
                "articles", List.of(Map.of(
                    "title", "string",
                    "url", "string",
                    "points", "number"
                ))
            );
            
            ExtractResult<Map<String, Object>> result = stagehand
                .extract("extract the top 5 articles", schema)
                .get();
            
            @SuppressWarnings("unchecked")
            List<Map<String, Object>> articles = 
                (List<Map<String, Object>>) result.getData().get("articles");
            
            for (Map<String, Object> article : articles) {
                System.out.println(article.get("title") + " - " + 
                                   article.get("points") + " points");
            }
        } finally {
            stagehand.close();
        }
    }
}

Form Automation

public class FormFiller {
    public static void fillForm(String name, String email) throws Exception {
        Stagehand stagehand = new Stagehand(config);
        stagehand.init().get();
        
        try {
            stagehand.page().goto("https://example.com/form").get();
            
            Map<String, String> variables = Map.of(
                "name", name,
                "email", email
            );
            
            stagehand.act("fill the name field with {{name}}", 
                ActOptions.builder().variables(variables).build()).get();
            
            stagehand.act("fill the email field with {{email}}",
                ActOptions.builder().variables(variables).build()).get();
            
            stagehand.act("click the submit button").get();
            
            Map<String, Object> schema = Map.of("message", "string");
            ExtractResult<?> result = stagehand
                .extract("get the success message", schema)
                .get();
            
            System.out.println("Result: " + result.getData());
        } finally {
            stagehand.close();
        }
    }
}

Type Safety

The Java SDK provides strong typing:

// Generic extract with type parameter
ExtractResult<User> result = stagehand
    .extract("get user info", userSchema, User.class)
    .get();

User user = result.getData();
System.out.println(user.getName());

Error Handling

try {
    ActResult result = stagehand.act("click button").get();
} catch (StagehandException e) {
    if (e instanceof ActTimeoutException) {
        System.err.println("Action timed out");
    } else if (e instanceof StagehandAPIException) {
        System.err.println("API error: " + e.getMessage());
    }
} catch (ExecutionException | InterruptedException e) {
    e.printStackTrace();
}

Working with the API Server

The Java SDK requires the Stagehand API server. You can:

Use Browserbase’s hosted API (recommended)
Run the server locally (see Python SDK)

// Custom API endpoint
StagehandConfig config = StagehandConfig.builder()
    .env("LOCAL")
    .apiUrl("http://localhost:3000")
    .build();

Resources

Java SDK Repository

Source code (coming soon)

TypeScript SDK

Reference implementation

Maven Central

Browse packages

API Documentation

Full API reference

Contributing

Interested in contributing to the Java SDK?

SDKs

Documentation Index

​Overview

​Architecture

​Installation

​Maven

​Gradle

​Repository

Java SDK on GitHub

​Quick Start

​Core API

​Stagehand Class

​Methods

​act()

​extract()

​observe()

​agent.execute()

​Configuration

​StagehandConfig

​ModelConfig

​Async vs Sync

​Examples

​Web Scraping

​Form Automation

​Type Safety

​Error Handling

​Working with the API Server

​Resources

Java SDK Repository

TypeScript SDK

Maven Central

API Documentation

​Contributing

Build docs developers (and LLMs) love

Overview

Architecture

Installation

Maven

Gradle

Repository

Quick Start

Core API

Stagehand Class

Methods

act()

extract()

observe()

agent.execute()

Configuration

StagehandConfig

ModelConfig

Async vs Sync

Examples

Web Scraping

Form Automation

Type Safety

Error Handling

Working with the API Server

Resources

Contributing