## 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
|
|
|---|---|---|
| .. | ||
| src/mastra | ||
| .env.example | ||
| .gitignore | ||
| package.json | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| tsconfig.json | ||
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-chromiumpackage during dependency install. On Linux root runtimes, the template runsplaywright install-deps chromiumbefore the first local browser launch. You can setBROWSER_CDP_URLfor a hosted Chrome/Browserbase/Browserless instance instead.
Quickstart 🚀
- Add your API keys
- Copy
.env.exampleto.envand fill it in. SetBROWSER_HEADLESS=falseif you want to watch the agent click around locally. - For server deployments, leave
BROWSER_SKIP_INSTALL_DEPS=falseso Linux Chromium system dependencies are installed before first browser use, or setBROWSER_CDP_URLto a hosted browser endpoint.
- Copy
- Start the dev server
- Run
npm run devand open localhost:4111.
- Run
Ask things like:
- "Open https://news.ycombinator.com and tell me the top three stories right now."
- "Search Wikipedia for the GDP of France in 2024 and report the figure with a source."
- "Go to https://www.npmjs.com/package/zod and list the dependencies in the latest version."
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_URLto 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.