Beam
AI-powered browser agent for web automation
Overview •
Features •
Installation •
Quickstart •
Documentation •
Examples •
License
## 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](https://github.com/browser-use/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](docs/getting-started/comparison.md).
## 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
```bash
npm install beam
```
For more detailed installation instructions, see our [Installation Guide](docs/getting-started/installation.md).
## 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](https://platform.openai.com/api-keys)
- [Anthropic API Keys](https://console.anthropic.com/settings/keys)
## Quickstart
```typescript
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:
```bash
# 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](docs/getting-started/quick-start.md).
## Steel Integration
Steel's cloud browsers crack CAPTCHAs, dodge bots, and track everything—giving Beam agents the stealth and insights they need.
```typescript
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](docs) directory:
### Getting Started
- [Installation](docs/getting-started/installation.md)
- [Quick Start](docs/getting-started/quick-start.md)
- [Core Concepts](docs/getting-started/core-concepts.md)
- [Comparison with browser-use](docs/getting-started/comparison.md)
### Core API
- [Core API](docs/core/core-api.md)
- [Configuration Options](docs/core/configuration-options.md)
- [Browser Integration](docs/core/browser-integration.md)
- [Tools Integration](docs/core/tools.md)
- [Memory System](docs/core/memory.md)
- [Events System](docs/core/events.md)
### Advanced Usage
- [Error Handling & Debugging](docs/advanced/error-handling.md)
- [AI SDK Adapter](docs/advanced/ai-sdk-adapter.md)
- [Architecture](docs/advanced/architecture.md)
## Examples
### Basic Example with Event Handling
```typescript
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
```typescript
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](docs/examples/index.md).
## License
MIT