adding mastra integration + docs (#10)

Author: Kylejeong2

README.md

@@ -48,6 +48,16 @@ Powerful integrations for AgentKit workflows with both Browserbase and Stagehand
 #### [**LangChain Integration**](./examples/integrations/langchain/README.md)  
 Integrate Browserbase with LangChain's ecosystem for advanced AI applications. Build chains that can browse, extract, and interact with web content as part of larger AI workflows.
 
+#### [**Mastra Integration**](./examples/integrations/mastra/README.md)
+Powerful web automation combining Browserbase's Stagehand with Mastra's AI agent framework. Enable your Mastra agents to navigate websites, extract data, and perform complex web interactions through natural language commands.
+
+**Key Features:**
+- AI-powered web navigation and interaction
+- Smart element observation and data extraction  
+- Session management with automatic timeouts
+- Natural language interface to web automation
+- Integration with OpenAI models for intelligent decision-making
+
 #### [**Browser-Use Integration**](./examples/integrations/browser-use/README.md)
 Streamlined browser automation for AI applications with a focus on simplicity and reliability.
 
@@ -98,6 +108,7 @@ integrations/
 │       ├── vercel/              # Vercel AI SDK integration  
 │       ├── stripe/              # Stripe Issuing + automation
 │       ├── langchain/           # LangChain framework integration
+│       ├── mastra/              # Mastra AI agent integration
 │       ├── browser-use/         # Simplified browser automation
 │       ├── braintrust/          # Evaluation and testing tools
 │       ├── agno/                # AI-powered web scraping agents

examples/integrations/mastra/.gitignore

@@ -0,0 +1,9 @@
+output.txt
+node_modules
+dist
+.mastra
+.env.development
+.env
+*.db
+
+memory*

examples/integrations/mastra/README.md

@@ -0,0 +1,91 @@
+# Stagehand & Mastra Integration
+
+A powerful integration that combines the capabilities of [Browserbase's Stagehand](https:/stagehand.dev) with [Mastra](https://mastra.ai/) for advanced web automation, scraping, and AI-powered web interactions.
+
+## Overview
+
+This project enables AI agents to interact with web pages through the Mastra framework using Stagehand's browser automation capabilities. It provides tools for web navigation, element observation, data extraction, and action execution, all orchestrated through Mastra's agent system.
+
+## Features
+
+- **Web Navigation**: Navigate to websites programmatically
+- **Element Observation**: Identify and locate elements on web pages
+- **Action Execution**: Perform actions like clicking buttons or filling forms
+- **Data Extraction**: Extract structured data from web pages
+- **Session Management**: Smart session handling with automatic timeouts and reconnection
+- **AI-Powered Interactions**: Leverage OpenAI models for intelligent web interactions
+
+## Installation
+
+### Prerequisites
+
+- Node.js (v18+)
+- npm or yarn
+- Browserbase account 
+- OpenAI API access
+
+### Setup
+
+1. Clone the repository:
+   ```
+   git clone https://github.com/browserbase/Stagehand-Mastra-App.git
+   cd Stagehand-Mastra-App
+   ```
+
+2. Install dependencies:
+   ```
+   npm install
+   ```
+
+3. Create a `.env` file with your API keys:
+   ```
+   BROWSERBASE_PROJECT_ID=your_project_id
+   BROWSERBASE_API_KEY=your_api_key
+   OPENAI_API_KEY=your_openai_key
+   ```
+
+## Usage
+
+### Running the development server
+
+```
+npm run dev
+```
+
+This will start the Mastra development server, giving you access to the integrated web agent.
+
+## Architecture
+
+### Core Components
+
+1. **Stagehand Session Manager**
+   - Handles browser session initialization and management
+   - Implements automatic session timeouts
+   - Provides error recovery and reconnection logic
+
+2. **Mastra Tools**
+   - `stagehandActTool`: Performs actions on web pages
+   - `stagehandObserveTool`: Identifies elements on web pages
+   - `stagehandExtractTool`: Extracts data from web pages
+
+3. **Web Agent**
+   - AI-powered agent using OpenAI's GPT-4
+   - Provides natural language interface to web automation
+   - Integrates all tools into a unified experience
+
+### Flow Diagram
+
+```
+User Query → Mastra Agent → Stagehand Tools → Browser Interaction → Web Page → Data/Results → Agent Response
+```
+
+## Configuration
+
+The project can be configured through the `.env` file and by modifying the agent instructions in `src/mastra/agents/index.ts`.
+
+## Credits
+
+This project is built with:
+- [Mastra](https://mastra.ai) - AI Agent framework
+- [Stagehand by Browserbase](https:/stagehand.dev) - Browser automation
+- [OpenAI](https://openai.com/) - AI models