0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/templates/template-browser-agent
Justin Levine b22ffc39a7
feat(templates): read the model from AGENT_MODEL in Browser Agent (#29748)
## Description

Browser Agent now reads its chat model from `AGENT_MODEL` and falls back
to `mastra/openai/gpt-5-mini`, so nothing changes until Mastra Platform
sets it. This lets Platform's template form offer a model choice
(PLTFRM-3312). Web search now uses the Gateway web search tool from
docs-expert instead of OpenAI's provider tool, so it works on any model
and the agent's instructions stay true.

## Related issue(s)

Linear PLTFRM-3316

## Type of change

- [x] New feature (non-breaking change that adds functionality)

## Checklist

- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

Verified: `mastra build` passes and `tsc` is clean against the published
packages.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

## ELI5
The Browser Agent can now use a model selected with `AGENT_MODEL`. If
the setting is empty, it uses `mastra/openai/gpt-5-mini`. The agent’s
web-search tool uses the Mastra Gateway, regardless of the selected
agent model.

## Changes
- Added `AGENT_MODEL` and example model IDs to `.env.example`.
- Updated the Browser Agent to trim `AGENT_MODEL` and use the default
model when the setting is empty.
- Added a Gateway-backed `webSearchTool` that returns an answer and
deduplicated source URLs.
- Removed `@ai-sdk/openai` from the template dependencies.

## Validation
- Build and test results: not available.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
History 2026-11-09 18:02:27 +00:00
..
src/mastra feat(templates): read the model from AGENT_MODEL in Browser Agent (#29748) 2026-11-09 18:02:27 +00:00
.env.example feat(templates): read the model from AGENT_MODEL in Browser Agent (#29748) 2026-11-09 18:02:27 +00:00
.gitignore feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00
package.json feat(templates): read the model from AGENT_MODEL in Browser Agent (#29748) 2026-11-09 18:02:27 +00:00
pnpm-workspace.yaml feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00
README.md feat(templates): read the model from AGENT_MODEL in Browser Agent (#29748) 2026-11-09 18:02:27 +00:00
tsconfig.json feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00

Browser Agent

A browser-using agent built on @mastra/agent-browser. It wraps Playwright with a snapshot+refs pattern — the model sees a stable ID for each element instead of brittle CSS selectors — and auto-wires browser tools (browser_goto, browser_click, browser_type, browser_snapshot, etc.) onto the agent. Also has web_search for tasks that don't need a live page.

If you'd rather use Stagehand / Browserbase (AI-driven element detection, cloud-hosted browsers), see template-browsing-agent instead.

Demo

This demo runs in Mastra Studio, but you can connect this agent to your React, Next.js, or Vue app using the Mastra Client SDK or agentic UI libraries like AI SDK UI, CopilotKit, or Assistant UI.

Prerequisites

  • A Gateway API key.
  • A Turso database URL + auth token (or swap to :memory: for ephemeral local runs).
  • Playwright Chromium is installed by the playwright-chromium package during dependency install. On Linux root runtimes, the template runs playwright install-deps chromium before the first local browser launch. You can set BROWSER_CDP_URL for a hosted Chrome/Browserbase/Browserless instance instead.

Quickstart 🚀

  1. Add your API keys
    • Copy .env.example to .env and fill it in. Set BROWSER_HEADLESS=false if you want to watch the agent click around locally.
    • For server deployments, leave BROWSER_SKIP_INSTALL_DEPS=false so Linux Chromium system dependencies are installed before first browser use, or set BROWSER_CDP_URL to a hosted browser endpoint.
  2. Start the dev server

Ask things like:

How it works

In src/mastra/agents/browser-agent.ts, the agent registers a Gateway-backed search tool independently of its chat model:

import { webSearchTool } from '../tools/web-search';

const browser = new AgentBrowser({
  headless: true,
  ...(process.env.BROWSER_CDP_URL ? { cdpUrl: process.env.BROWSER_CDP_URL, scope: 'shared' } : {}),
});

export const browserAgent = new Agent({
  // …
  browser,
  tools: { web_search: webSearchTool },
});

Passing browser to the agent automatically registers the full browser toolset (browser_goto, browser_snapshot, browser_click, browser_type, browser_scroll, browser_screenshot, etc.) on the agent. The template installs Playwright's Linux system dependencies before first local browser launch when running as root; set BROWSER_CDP_URL to connect to a remote browser instead.

Making it yours

  • Add a session profile. AgentBrowser({ profile: '/path/to/profile' }) persists cookies, logins, and localStorage between runs.
  • Use a remote browser. Set BROWSER_CDP_URL to attach to a Browserbase, Browserless, or hosted Chrome instance instead of launching locally.
  • Drop tools you don't want. AgentBrowser({ excludeTools: ['browser_screenshot'] }) is useful when targeting a text-only model.
  • Swap the model. Any mastra/<provider>/<model> id works. The browser tools are provider-agnostic.

Agent Editor

This template enables the code-backed Agent Editor with new MastraEditor({ source: 'code', codePath: 'mastra/editor' }). Edits made in Studio are written as deterministic JSON overrides under mastra/editor/agents/, so Mastra Platform can open GitHub pull requests for agent changes instead of only saving them to the database.

About Mastra templates

Mastra templates are ready-to-use projects that show what you can build. Use the platform-created repository as your starting point, then customize it for your app.

Want to contribute? See the Mastra contributing guide.