@mastra/agent-browser 0.1.0-alpha.0 → 0.2.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @mastra/agent-browser
 
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Added `storageState` option and `exportStorageState()` method for lightweight auth persistence (cookies and localStorage). Also kills orphaned Chrome child processes on close to prevent zombies. ([#15194](https://github.com/mastra-ai/mastra/pull/15194))
+
+### Patch Changes
+
+- AgentBrowser with default thread scope now initializes correctly. Previously, calling launch() followed by getPage() would throw "Browser not launched" when no explicit thread ID was provided. ([#15285](https://github.com/mastra-ai/mastra/pull/15285))
+
+- Updated dependencies [[`cbdf3e1`](https://github.com/mastra-ai/mastra/commit/cbdf3e12b3d0c30a6e5347be658e2009648c130a), [`8fe46d3`](https://github.com/mastra-ai/mastra/commit/8fe46d354027f3f0f0846e64219772348de106dd), [`18c67db`](https://github.com/mastra-ai/mastra/commit/18c67dbb9c9ebc26f26f65f7d3ff836e5691ef46), [`8dcc77e`](https://github.com/mastra-ai/mastra/commit/8dcc77e78a5340f5848f74b9e9f1b3da3513c1f5), [`aa67fc5`](https://github.com/mastra-ai/mastra/commit/aa67fc59ee8a5eeff1f23eb05970b8d7a536c8ff), [`fa8140b`](https://github.com/mastra-ai/mastra/commit/fa8140bcd4251d2e3ac85fdc5547dfc4f372b5be), [`190f452`](https://github.com/mastra-ai/mastra/commit/190f45258b0640e2adfc8219fa3258cdc5b8f071), [`7e7bf60`](https://github.com/mastra-ai/mastra/commit/7e7bf606886bf374a6f9d4ca9b09dd83d0533372), [`184907d`](https://github.com/mastra-ai/mastra/commit/184907d775d8609c03c26e78ccaf37315f3aa287), [`0c4cd13`](https://github.com/mastra-ai/mastra/commit/0c4cd131931c04ac5405373c932a242dbe88edd6), [`b16a753`](https://github.com/mastra-ai/mastra/commit/b16a753d5748440248d7df82e29bb987a9c8386c)]:
+  - @mastra/core@1.25.0-alpha.3
+
+## 0.1.0
+
+### Minor Changes
+
+- Add browser automation support with screencast streaming, input injection, and thread isolation ([#14938](https://github.com/mastra-ai/mastra/pull/14938))
+
+  **New Features:**
+  - Browser tools for web automation (navigate, click, type, scroll, extract, etc.)
+  - Real-time screencast streaming via WebSocket
+  - Mouse and keyboard input injection
+  - Thread-scoped browser isolation (`scope: 'thread'`)
+  - State persistence and restoration across sessions
+  - Support for cloud providers (Browserbase, Browser-Use, Browserless)
+
+  **Configuration:**
+
+  ```typescript
+  import { AgentBrowser } from '@mastra/agent-browser';
+
+  const browser = new AgentBrowser({
+    headless: true,
+    scope: 'thread', // Each thread gets isolated browser
+    viewport: { width: 1280, height: 720 },
+  });
+
+  const agent = mastra.getAgent('my-agent', { browser });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`cb15509`](https://github.com/mastra-ai/mastra/commit/cb15509b58f6a83e11b765c945082afc027db972), [`81e4259`](https://github.com/mastra-ai/mastra/commit/81e425939b4ceeb4f586e9b6d89c3b1c1f2d2fe7), [`951b8a1`](https://github.com/mastra-ai/mastra/commit/951b8a1b5ef7e1474c59dc4f2b9fc1a8b1e508b6), [`80c5668`](https://github.com/mastra-ai/mastra/commit/80c5668e365470d3a96d3e953868fd7a643ff67c), [`3d478c1`](https://github.com/mastra-ai/mastra/commit/3d478c1e13f17b80f330ac49d7aa42ef929b93ff), [`2b4ea10`](https://github.com/mastra-ai/mastra/commit/2b4ea10b053e4ea1ab232d536933a4a3c4cba999), [`a0544f0`](https://github.com/mastra-ai/mastra/commit/a0544f0a1e6bd52ac12676228967c1938e43648d), [`6039f17`](https://github.com/mastra-ai/mastra/commit/6039f176f9c457304825ff1df8c83b8e457376c0), [`06b928d`](https://github.com/mastra-ai/mastra/commit/06b928dfc2f5630d023467476cc5919dfa858d0a), [`6a8d984`](https://github.com/mastra-ai/mastra/commit/6a8d9841f2933456ee1598099f488d742b600054), [`c8c86aa`](https://github.com/mastra-ai/mastra/commit/c8c86aa1458017fbd1c0776fdc0c520d129df8a6)]:
+  - @mastra/core@1.22.0
+
 ## 0.1.0-alpha.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,138 @@
+# @mastra/agent-browser
+
+Deterministic browser automation for Mastra agents using [agent-browser](https://github.com/vercel-labs/agent-browser).
+
+## Installation
+
+```bash
+npm install @mastra/agent-browser
+```
+
+## Usage
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { AgentBrowser } from '@mastra/agent-browser';
+
+// Create an AgentBrowser instance
+const browser = new AgentBrowser({
+  headless: true,
+});
+
+// Create an agent with the browser
+const agent = new Agent({
+  name: 'web-agent',
+  instructions: `You are a web automation assistant.
+Use browser_snapshot to see the page structure,
+then interact with elements using their refs (e.g., @e5).`,
+  model: 'openai/gpt-5.4',
+  browser,
+});
+
+// Use the agent to browse the web
+const result = await agent.generate('Go to example.com and click the first link');
+```
+
+## Configuration
+
+```typescript
+const browser = new AgentBrowser({
+  // Run headless (default: true)
+  headless: true,
+
+  // Viewport dimensions
+  viewport: { width: 1280, height: 720 },
+
+  // Default timeout for operations in ms (default: 30000)
+  timeout: 30000,
+
+  // CDP URL for connecting to existing browser
+  cdpUrl: 'ws://localhost:9222',
+
+  // Browser instance scope
+  // Default: 'thread' for local launch, 'shared' when cdpUrl is provided
+  // 'thread': Each thread gets its own browser
+  // 'shared': All threads share one browser
+  scope: 'thread',
+
+  // Screencast settings for Studio
+  screencast: {
+    enabled: true,
+    format: 'jpeg',
+    quality: 80,
+  },
+});
+```
+
+## Tools
+
+AgentBrowser exposes 15 deterministic tools using accessibility tree refs:
+
+### Core Tools
+
+- **browser_goto** - Navigate to a URL
+- **browser_snapshot** - Get accessibility tree with element refs (@e1, @e2, etc.)
+- **browser_click** - Click an element by ref
+- **browser_type** - Type text into an element
+- **browser_press** - Press keyboard keys
+- **browser_select** - Select option from dropdown
+- **browser_scroll** - Scroll the page or element
+- **browser_close** - Close the browser
+
+### Extended Tools
+
+- **browser_hover** - Hover over an element
+- **browser_back** - Go back in browser history
+- **browser_dialog** - Handle browser dialogs (alert, confirm, prompt)
+- **browser_wait** - Wait for element state changes
+- **browser_tabs** - Manage browser tabs (list, new, switch, close)
+- **browser_drag** - Drag and drop elements
+
+### Escape Hatch
+
+- **browser_evaluate** - Execute JavaScript in the page context
+
+## How Refs Work
+
+AgentBrowser uses accessibility tree refs for precise element targeting:
+
+1. Call `browser_snapshot` to get the page structure with refs
+2. Find the element you want to interact with
+3. Use its ref with other tools
+
+```text
+[document] Example Page
+  [banner]
+    [link @e1] Home
+    [link @e2] About
+  [main]
+    [textbox @e3] Search...
+    [button @e4] Submit
+```
+
+```typescript
+// Type in the search box
+{ tool: "browser_type", input: { ref: "@e3", text: "mastra" } }
+
+// Click submit
+{ tool: "browser_click", input: { ref: "@e4" } }
+```
+
+## Comparison with StagehandBrowser
+
+| Feature     | AgentBrowser             | StagehandBrowser             |
+| ----------- | ------------------------ | ---------------------------- |
+| Approach    | Deterministic refs (@e1) | Natural language             |
+| Token cost  | Low                      | Higher (LLM calls)           |
+| Speed       | Fast                     | Slower                       |
+| Reliability | High (exact refs)        | Variable (AI interpretation) |
+| Best for    | Structured workflows     | Unknown/dynamic pages        |
+
+## Documentation
+
+- [agent-browser guide](https://mastra.ai/docs/browser/agent-browser) - Usage guide
+- [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) - API reference
+
+## License
+
+Apache-2.0