Overview

Beam combines browser automation with AI capabilities, allowing you to automate complex web tasks using natural language. It integrates language models to interpret tasks, plan actions, and execute them in a browser environment.

Beam is inspired by and builds upon browser-use, an innovative project that pioneered LLM-powered browser automation. Beam is essentially a 1:1 mapping of browser-use's functionality into TypeScript, with the main difference being the underlying tooling:

• Using TypeScript instead of Python
• Built on Mastra instead of Langchain
• Providing the same core functionality with JavaScript ecosystem integration
• Maintaining the same browser automation principles and approach

For a more detailed comparison, see our comparison guide.

Features

• AI-Powered Automation: Define tasks in natural language and let the AI agent handle the execution
• Smart Planning: Uses a planner agent to strategize complex task execution
• Memory Management: Maintains context across actions with configurable memory options
• Vision Capabilities: Can interpret visual elements on web pages
• Secure Navigation: Configurable domain restrictions for security
• Event System: Rich event system for monitoring execution progress
• Extensible Tools: Create and integrate custom tools to enhance the agent's capabilities

Installation

npm install beam

For more detailed installation instructions, see our Installation Guide.

API Keys

Beam requires API keys for whichever language model provider you choose to use:

• OpenAI: Set the OPENAI_API_KEY environment variable or provide it directly to the client
• Anthropic: Set the ANTHROPIC_API_KEY environment variable

Visit the respective provider's website to obtain your API key:

• OpenAI API Keys
• Anthropic API Keys

Quickstart

import { Beam } from "beam";
import { openai } from "@ai-sdk/openai";
import dotenv from "dotenv";
// Load environment variables from .env file
dotenv.config();

async function example() {
  // Initialize Beam with an LLM
  const beam = new Beam({
    llm: openai("gpt-4.1"), // Requires OPENAI_API_KEY in your .env file
    useVision: true,
  });

  beam.on("text", content => process.stdout.write(content));

  await beam.initialize();

  try {
    // Run a task
    const result = await beam.run({
      task: "Go to news.ycombinator.com and summarize the top 3 stories",
    });

    console.log(JSON.stringify(result, null, 2));

    console.log("Task completed successfully!");
  } finally {
    // Close the browser when done
    await beam.close();
  }
}

example().catch(console.error);

Run the example

First, create a .env file in your project root:

OPENAI_API_KEY=your_openai_api_key_here

Then run the script:

# Install dependencies
npm install beam @ai-sdk/openai dotenv

# Run your script (assuming it's saved as example.ts)
npx tsx example.ts

For a more detailed guide, see our Quick Start Guide.

Steel Integration

Steel's cloud browsers crack CAPTCHAs, dodge bots, and track everything—giving Beam agents the stealth and insights they need.

import { Beam } from "beam";
import { openai } from "@ai-sdk/openai";
import dotenv from "dotenv";
// Load environment variables from .env file
dotenv.config();

async function example() {
  // Initialize Beam with Steel integration
  const beam = new Beam({
    llm: openai("gpt-4.1"),
    useSteel: true,
  });

  await beam.initialize({ solveCaptcha: true });

  try {
    await beam.run({
      task: "Search for Browser Agents and summarize the top result",
    });
  } finally {
    await beam.close();
  }
}

example().catch(console.error);

Set your Steel API key in your environment variables:

STEEL_API_KEY=your_steel_api_key

Documentation

Comprehensive documentation is available in the docs directory:

Getting Started

• Installation
• Quick Start
• Core Concepts
• Comparison with browser-use

Core API

• Core API
• Configuration Options
• Browser Integration
• Tools Integration
• Memory System
• Events System

Advanced Usage

• Error Handling & Debugging
• AI SDK Adapter
• Architecture

Examples

Basic Example with Event Handling

import { Beam } from "beam";
import { openai } from "@ai-sdk/openai";

// Note: Requires properly configured environment variables
// See Quickstart section for setup details
async function example() {
  const beam = new Beam({
    llm: openai("gpt-4o"),
    useVision: true,
    maxSteps: 10,
  });

  // Set up event listeners for real-time updates
  beam.on("text", content => process.stdout.write(content)); // Stream text output
  beam.on("tool-call", toolCall => console.log(`Using tool: ${toolCall.toolName}`));
  beam.on("error", error => console.error("Error:", error));
  beam.on("done", result => console.log("Task completed:", result.completed));

  try {
    await beam.initialize();
    await beam.run({
      task: "Go to news.ycombinator.com and summarize the top 3 stories",
    });
  } finally {
    await beam.close();
  }
}

example().catch(console.error);

Using Custom Tools

import { Beam } from "beam";
import { openai } from "@ai-sdk/openai";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

// Note: Requires properly configured environment variables
// See Quickstart section for setup details

// Define a custom tool
const weatherTool = createTool({
  id: "getWeather",
  description: "Get the current weather for a location",
  inputSchema: z.object({
    location: z.string(),
  }),
  execute: async ({ context }) => {
    const { location } = context;
    // Implementation to fetch weather data
    return { location, temperature: "72°F", conditions: "Sunny" };
  },
});

// Initialize Beam with custom tools
const beam = new Beam({
  llm: openai("gpt-4o"),
  tools: {
    custom: {
      getWeather: weatherTool,
    },
  },
});

// Now the agent can use your custom weather tool

For more examples, check the Examples Section.

License

MIT