{"id":44584914,"url":"https://github.com/browserbase/convex-stagehand","last_synced_at":"2026-02-14T06:01:37.941Z","repository":{"id":334816769,"uuid":"1139576865","full_name":"browserbase/convex-stagehand","owner":"browserbase","description":"Component for using Stagehand in Convex apps","archived":false,"fork":false,"pushed_at":"2026-02-03T19:29:29.000Z","size":301,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T08:39:31.580Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/browserbase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T06:18:41.000Z","updated_at":"2026-02-03T19:29:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/browserbase/convex-stagehand","commit_stats":null,"previous_names":["browserbase/convex-stagehand"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/browserbase/convex-stagehand","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fconvex-stagehand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fconvex-stagehand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fconvex-stagehand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fconvex-stagehand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/browserbase","download_url":"https://codeload.github.com/browserbase/convex-stagehand/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fconvex-stagehand/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29438637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T05:24:35.651Z","status":"ssl_error","status_checked_at":"2026-02-14T05:24:34.830Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-14T06:01:02.089Z","updated_at":"2026-02-14T06:01:37.934Z","avatar_url":"https://github.com/browserbase.png","language":"TypeScript","readme":"# convex-stagehand\n\nAI-powered browser automation for Convex applications. Extract data, perform actions, and automate workflows using natural language - no Playwright knowledge required.\n\n## Features\n\n- **Simple API** - Describe what you want in plain English\n- **Type-safe** - Full TypeScript support with Zod schemas\n- **Session management** - Reuse browser sessions across multiple operations\n- **Agent mode** - Autonomous multi-step task execution\n- **Powered by Stagehand** - Uses the [Stagehand](https://github.com/browserbase/stagehand) REST API\n\n## Quick Start\n\n### 1. Install the Component\n\n```bash\nnpm install @browserbasehq/convex-stagehand zod\n```\n\n### 2. Configure Convex\n\nAdd the component to your `convex/convex.config.ts`:\n\n```typescript\nimport { defineApp } from \"convex/server\";\nimport stagehand from \"convex-stagehand/convex.config\";\n\nconst app = defineApp();\napp.use(stagehand, { name: \"stagehand\" });\n\nexport default app;\n```\n\n### 3. Set Up Environment Variables\n\nAdd these to your [Convex Dashboard](https://dashboard.convex.dev) → Settings → Environment Variables:\n\n| Variable | Description |\n|----------|-------------|\n| `BROWSERBASE_API_KEY` | Your Browserbase API key |\n| `BROWSERBASE_PROJECT_ID` | Your Browserbase project ID |\n| `MODEL_API_KEY` | Your LLM provider API key (OpenAI, Anthropic, etc.) |\n\n### 4. Use the Component\n\n```typescript\nimport { action } from \"./_generated/server\";\nimport { Stagehand } from \"convex-stagehand\";\nimport { components } from \"./_generated/api\";\nimport { z } from \"zod\";\n\nconst stagehand = new Stagehand(components.stagehand, {\n  browserbaseApiKey: process.env.BROWSERBASE_API_KEY!,\n  browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID!,\n  modelApiKey: process.env.MODEL_API_KEY!,\n});\n\nexport const scrapeHackerNews = action({\n  handler: async (ctx) =\u003e {\n    return await stagehand.extract(ctx, {\n      url: \"https://news.ycombinator.com\",\n      instruction: \"Extract the top 5 stories with title, score, and link\",\n      schema: z.object({\n        stories: z.array(z.object({\n          title: z.string(),\n          score: z.string(),\n          link: z.string(),\n        }))\n      })\n    });\n  }\n});\n```\n\n## API Reference\n\n### `startSession(ctx, args)`\n\nStart a new browser session. Returns session info for use with other operations.\n\n```typescript\nconst session = await stagehand.startSession(ctx, {\n  url: \"https://example.com\",\n  browserbaseSessionId: \"optional-existing-session-id\",\n  options: {\n    timeout: 30000,\n    waitUntil: \"networkidle\",\n    domSettleTimeoutMs: 2000,\n    selfHeal: true,\n    systemPrompt: \"Custom system prompt for the session\",\n  }\n});\n// { sessionId: \"...\", browserbaseSessionId: \"...\", cdpUrl: \"wss://...\" }\n```\n\n**Parameters:**\n- `url` - The URL to navigate to\n- `browserbaseSessionId` - Optional: Resume an existing Browserbase session\n- `options.timeout` - Navigation timeout in milliseconds\n- `options.waitUntil` - When to consider navigation complete: `\"load\"`, `\"domcontentloaded\"`, or `\"networkidle\"`\n- `options.domSettleTimeoutMs` - Timeout for DOM to settle before considering page loaded\n- `options.selfHeal` - Enable self-healing capabilities for more robust automation\n- `options.systemPrompt` - Custom system prompt to guide the AI's behavior during the session\n\n**Returns:**\n```typescript\n{\n  sessionId: string;           // Use with other operations\n  browserbaseSessionId?: string; // Store to resume later\n  cdpUrl?: string;             // For advanced Playwright/Puppeteer usage\n}\n```\n\n---\n\n### `endSession(ctx, args)`\n\nEnd a browser session.\n\n```typescript\nawait stagehand.endSession(ctx, { sessionId: session.sessionId });\n```\n\n**Parameters:**\n- `sessionId` - The session to end\n\n**Returns:** `{ success: boolean }`\n\n---\n\n### `extract(ctx, args)`\n\nExtract structured data from a web page using AI.\n\n```typescript\n// Without session (creates and destroys its own)\nconst data = await stagehand.extract(ctx, {\n  url: \"https://example.com\",\n  instruction: \"Extract all product names and prices\",\n  schema: z.object({\n    products: z.array(z.object({\n      name: z.string(),\n      price: z.string(),\n    }))\n  }),\n});\n\n// With existing session (reuses session, doesn't end it)\nconst data = await stagehand.extract(ctx, {\n  sessionId: session.sessionId,\n  instruction: \"Extract all product names and prices\",\n  schema: z.object({ ... }),\n});\n```\n\n**Parameters:**\n- `sessionId` - Optional: Use an existing session\n- `url` - The URL to navigate to (required if no sessionId)\n- `instruction` - Natural language description of what to extract\n- `schema` - Zod schema defining the expected output structure\n- `options.timeout` - Navigation timeout in milliseconds\n- `options.waitUntil` - When to consider navigation complete: `\"load\"`, `\"domcontentloaded\"`, or `\"networkidle\"`\n\n**Returns:** Data matching your Zod schema\n\n---\n\n### `act(ctx, args)`\n\nExecute browser actions using natural language.\n\n```typescript\n// Without session\nconst result = await stagehand.act(ctx, {\n  url: \"https://example.com/login\",\n  action: \"Click the login button and wait for the page to load\",\n});\n\n// With existing session\nconst result = await stagehand.act(ctx, {\n  sessionId: session.sessionId,\n  action: \"Fill in the email field with 'user@example.com'\",\n});\n```\n\n**Parameters:**\n- `sessionId` - Optional: Use an existing session\n- `url` - The URL to navigate to (required if no sessionId)\n- `action` - Natural language description of the action to perform\n- `options.timeout` - Navigation timeout in milliseconds\n- `options.waitUntil` - When to consider navigation complete\n\n**Returns:**\n```typescript\n{\n  success: boolean;\n  message: string;\n  actionDescription: string;\n}\n```\n\n---\n\n### `observe(ctx, args)`\n\nFind available actions on a web page.\n\n```typescript\nconst actions = await stagehand.observe(ctx, {\n  url: \"https://example.com\",\n  instruction: \"Find all clickable navigation links\",\n});\n// [{ description: \"Home link\", selector: \"a.nav-home\", method: \"click\" }, ...]\n```\n\n**Parameters:**\n- `sessionId` - Optional: Use an existing session\n- `url` - The URL to navigate to (required if no sessionId)\n- `instruction` - Natural language description of what actions to find\n- `options.timeout` - Navigation timeout in milliseconds\n- `options.waitUntil` - When to consider navigation complete\n\n**Returns:**\n```typescript\nArray\u003c{\n  description: string;\n  selector: string;\n  method: string;\n  arguments?: string[];\n}\u003e\n```\n\n---\n\n### `agent(ctx, args)`\n\nExecute autonomous multi-step browser automation using an AI agent. The agent interprets the instruction and decides what actions to take.\n\n```typescript\n// Agent creates its own session\nconst result = await stagehand.agent(ctx, {\n  url: \"https://google.com\",\n  instruction: \"Search for 'convex database' and extract the top 3 results with title and URL\",\n  options: { maxSteps: 10 },\n});\n\n// Agent with existing session\nconst result = await stagehand.agent(ctx, {\n  sessionId: session.sessionId,\n  instruction: \"Fill out the contact form and submit\",\n  options: { maxSteps: 5 },\n});\n```\n\n**Parameters:**\n- `sessionId` - Optional: Use an existing session\n- `url` - The URL to navigate to (required if no sessionId)\n- `instruction` - Natural language description of the task to complete\n- `options.cua` - Enable Computer Use Agent mode\n- `options.maxSteps` - Maximum steps the agent can take\n- `options.systemPrompt` - Custom system prompt for the agent\n- `options.timeout` - Navigation timeout in milliseconds\n- `options.waitUntil` - When to consider navigation complete\n\n**Returns:**\n```typescript\n{\n  actions: Array\u003c{\n    type: string;\n    action?: string;\n    reasoning?: string;\n    timeMs?: number;\n  }\u003e;\n  completed: boolean;\n  message: string;\n  success: boolean;\n}\n```\n\n## Examples\n\n### Simple extraction (automatic session)\n\n```typescript\nconst news = await stagehand.extract(ctx, {\n  url: \"https://news.ycombinator.com\",\n  instruction: \"Get the top 10 stories with title, points, and comment count\",\n  schema: z.object({\n    stories: z.array(z.object({\n      title: z.string(),\n      points: z.string(),\n      comments: z.string(),\n    }))\n  })\n});\n```\n\n### Manual session management\n\nUse session management when you need to perform multiple operations while preserving browser state (cookies, login, etc.):\n\n```typescript\n// Start a session\nconst session = await stagehand.startSession(ctx, {\n  url: \"https://google.com\"\n});\n\n// Perform multiple operations in the same session\nawait stagehand.act(ctx, {\n  sessionId: session.sessionId,\n  action: \"Search for 'convex database'\"\n});\n\nconst data = await stagehand.extract(ctx, {\n  sessionId: session.sessionId,\n  instruction: \"Extract the top 3 results\",\n  schema: z.object({\n    results: z.array(z.object({\n      title: z.string(),\n      url: z.string(),\n    }))\n  })\n});\n\n// End the session when done\nawait stagehand.endSession(ctx, { sessionId: session.sessionId });\n```\n\n### Autonomous agent\n\nLet the AI agent figure out how to complete a complex task:\n\n```typescript\nconst result = await stagehand.agent(ctx, {\n  url: \"https://www.google.com\",\n  instruction: \"Search for 'best pizza in NYC', click on the first result, and extract the restaurant name and address\",\n  options: { maxSteps: 10 }\n});\n\nconsole.log(result.message); // Summary of what the agent did\nconsole.log(result.actions); // Detailed log of each action taken\n```\n\n### Resume session across Convex actions\n\nStore the `browserbaseSessionId` to resume sessions across different Convex action calls:\n\n```typescript\n// Action 1: Start session and return browserbaseSessionId\nexport const startBrowsing = action({\n  handler: async (ctx) =\u003e {\n    const session = await stagehand.startSession(ctx, {\n      url: \"https://example.com/login\"\n    });\n    // Store browserbaseSessionId in your database\n    return session.browserbaseSessionId;\n  }\n});\n\n// Action 2: Resume session later\nexport const continueBrowsing = action({\n  args: { browserbaseSessionId: v.string() },\n  handler: async (ctx, args) =\u003e {\n    const session = await stagehand.startSession(ctx, {\n      url: \"https://example.com/dashboard\",\n      browserbaseSessionId: args.browserbaseSessionId,\n    });\n    // Continue using the same browser instance\n    return await stagehand.extract(ctx, {\n      sessionId: session.sessionId,\n      instruction: \"Extract user data\",\n      schema: z.object({ ... }),\n    });\n  }\n});\n```\n\n## Configuration Options\n\n### AI Model\n\nBy default, the component uses `openai/gpt-4o`. You can use any model supported by the [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers) that supports structured outputs:\n\n```typescript\nconst stagehand = new Stagehand(components.stagehand, {\n  browserbaseApiKey: process.env.BROWSERBASE_API_KEY!,\n  browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID!,\n  modelApiKey: process.env.ANTHROPIC_API_KEY!, // Use Anthropic\n  modelName: \"anthropic/claude-3-5-sonnet-20241022\",\n});\n```\n\nFor the full list of supported models and providers, see the [Stagehand Models documentation](https://docs.stagehand.dev/configuration/models).\n\n## Requirements\n\n- [Browserbase](https://browserbase.com) account and API key\n- LLM provider API key (see [supported models](https://docs.stagehand.dev/configuration/models))\n- Convex 1.29.3 or later\n\n## How It Works\n\nThis component uses the [Stagehand REST API](https://stagehand.stldocs.app/api) to power browser automation. Each operation:\n\n1. Starts a cloud browser session via Browserbase (or reuses an existing one)\n2. Navigates to the target URL\n3. Uses AI to understand the page and perform the requested operation\n4. Optionally ends the session and returns results\n\nWith session management, you control when sessions start and end, allowing you to maintain browser state across multiple operations.\n\n## Development\n\n### Component Structure\n\nThe component exposes its API through Convex's component system. All functions are in a single `lib.ts` module:\n\n```\ncomponent.lib.\u003cfunction\u003e\n```\n\nFor example:\n- `component.lib.startSession` - Start a browser session\n- `component.lib.endSession` - End a browser session\n- `component.lib.extract` - Extract data from web pages\n- `component.lib.act` - Perform browser actions\n- `component.lib.observe` - Find interactive elements\n- `component.lib.agent` - Autonomous multi-step automation\n\nThe `Stagehand` client class wraps these internal paths to provide a clean user API:\n\n```typescript\n// User calls:\nstagehand.extract(ctx, {...})\n\n// Internally calls:\nctx.runAction(component.lib.extract, {...})\n```\n\n### Building the Component\n\nTo build the component locally:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build with Convex codegen (generates component API)\nnpm run build:codegen\n\n# Or just build TypeScript\nnpm run build:esm\n```\n\nThe component requires a Convex deployment to generate proper component API types (`_generated/component.ts`).\n\n### Example App\n\nCheck out the full example app in the [`example/`](./example) directory:\n\n```bash\ngit clone https://github.com/browserbase/convex-stagehand\ncd convex-stagehand/example\nnpm install\nnpm run dev\n```\n\nThe example includes:\n- HackerNews story extraction with AI\n- Type-safe data extraction using Zod schemas\n- Database persistence with Convex\n- Real-time updates and automatic refresh\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserbase%2Fconvex-stagehand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrowserbase%2Fconvex-stagehand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserbase%2Fconvex-stagehand/lists"}