0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
Commit graph

4 commits

Author SHA1 Message Date
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>
2026-11-09 18:02:27 +00:00
Damien Schneider
dce50dc9a1
chore: unify built-in Gateway naming (#18691)
## Summary

Rename Mastra’s first-party built-in gateway from **“Memory Gateway”**
to **“Gateway”** across live product surfaces, docs, templates, and
Mastra Code.

This is primarily a naming change. Gateway still handles model routing,
while Observational Memory remains a separate capability available
through the hosted service.

## What changed

- **Core:** `MastraGateway.name` and its provider-catalog display name
now use **Gateway**.
- **Playground:** the remote-memory panel uses **Gateway** as the
product name and **Remote** as the status label.
- **Mastra Code:** setup messages, internal symbol names, tests, and
filenames use the current Gateway terminology.
- **Docs and templates:** current product prose uses **Gateway**
consistently.
- **Tests and changesets:** assertions and release notes match the final
naming.

## Compatibility

The rename preserves existing identifiers and contracts:

- `MastraGateway`, gateway id `mastra`, the `mastra/` model prefix, and
`MASTRA_GATEWAY_*` environment variables are unchanged.
- The `X-Memory-Gateway-Authorization` header remains unchanged because
it is a wire contract.
- Persisted `settings.memoryGateway` remains unchanged to avoid a
settings migration.
- Auth-storage keys and default URL string values are unchanged.
- `MEMORY_GATEWAY_PROVIDER` and `MEMORY_GATEWAY_DEFAULT_URL` remain
exported as deprecated aliases of the new `MASTRA_GATEWAY_*` constants.
- `MastraCodeGateway.getMemoryGatewayApiKey()` remains a deprecated
alias and is covered for both normal and detached static calls.
- `/gateway` is the current hidden setup command; legacy
`/memory-gateway` remains accepted as an alias.

This lets current code adopt the Gateway name without breaking existing
consumers, stored configuration, commands, or network integrations.

## Deliberately out of scope

This PR does not change Gateway memory behavior or infer new
capabilities from its display name. It also does not include unrelated
CI hardening or review fixes.

The following accidental branch changes were restored exactly to `main`:

- client-js observability/memory E2E reset and seeding changes
- MongoDB vector metadata validation and its changeset
- generated Temporal fixture formatting drift

## Changesets

- `@mastra/core` — patch: display-name rename
- `mastracode` — patch: setup naming and `/gateway` alias
- `@mastra/code-sdk` — minor: new canonical exports/accessor with
deprecated compatibility aliases

## Validation

Synced normally with `main` through `2d5c85612f`; no force-push was
used.

- `@mastra/core`: dependency graph build passed; 3 focused files / 38
tests passed; typecheck passed.
- `@mastra/code-sdk`: 4 focused files / 83 tests passed; compatibility
accessor regression test passed; typecheck passed.
- `mastracode`: 2 focused files / 31 tests passed; `/gateway` and
legacy-command routing test passed; exact MCP HTTP and hooks-reload E2E
scenarios passed locally; typecheck passed.
- `@mastra/playground-ui`: typecheck passed.
- Scoped ESLint, Prettier, and `git diff --check` passed.
- Fresh GitHub CI ran on head `1e8e307c6c`: 70 successful, 3 skipped, 1
neutral, 0 failed, and 0 pending checks.
- `Mastra Code E2E` passed on retry. The remaining cancelled MongoDB
store job is a pre-existing circular-metadata/Vitest shutdown hang
reproduced on unrelated PRs with the identical MongoDB tree; this PR has
no MongoDB diff. The fix belongs in a separate MongoDB PR.
2026-07-13 17:26:20 +02:00
arctic-char
54ddf79679
Fix Browser Agent template Linux browser dependencies (#18217)
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
2026-06-19 16:32:02 +02:00
arctic-char
c9ce1b28d1
feat(templates): New templates showcasing latest Mastra features (#17425)
## Summary

Adds 5 new project templates under `templates/` that showcase the newest
Mastra features. All templates use Mastra Gateway as the AI provider
(`MASTRA_GATEWAY_API_KEY`) with `mastra/`-prefixed model IDs—no direct
provider API keys needed for LLM access.

### New templates

| Template | Key features | Model | DB |
|---|---|---|---|
| **template-docs-expert** | Provider-native web search via gateway,
observational memory, structured citations | `gpt-5-mini` | LibSQL
(Turso) |
| **template-browser-agent** | AgentBrowser (Playwright), browser tools,
web search fallback | `gpt-5-mini` | LibSQL (Turso) |
| **template-meeting-notes** | Zoom S2S OAuth cloud recordings,
transcription, structured notes, Linear/Notion export, ingest workflow |
`gpt-5.4` | LibSQL (Turso) |
| **template-company-knowledge** | Linear + Notion SDK tools, pgvector
semantic search, knowledge indexing workflow | `gpt-5.4` | PostgreSQL
(Neon) |
| **template-claw-assistant** | Autonomous computer-operating agent:
Workspace + LocalFilesystem + LocalSandbox + AgentBrowser + skills |
`gpt-5.4` | LibSQL (Turso) |

### Design decisions

- **Web search**: Uses `openai.tools.webSearch()` provider tool routed
through Mastra Gateway (OpenRouter-backed). No separate search API key
required.
- **Model tiers**: Reasoning-heavy templates (Claw, Company Knowledge,
Meeting Notes) use `gpt-5.4`; simpler tool-flow templates (Docs Expert,
Browser Agent) use `gpt-5-mini`.
- **Existing template**: `template-browsing-agent` (Stagehand) kept
alongside new `template-browser-agent` (AgentBrowser). Both READMEs
cross-link.
- **Zoom integration**: Server-to-Server OAuth (single-workspace, no
end-user OAuth dance). End-user OAuth is a follow-up.
- **Embeddings**: Company Knowledge template uses `@ai-sdk/openai`
embeddings directly (`OPENAI_API_KEY`) since the gateway doesn't proxy
embeddings.
- **No changeset**: Templates are standalone projects, not pnpm
workspace packages.

### Per template
- [x] `pnpm install --ignore-workspace` succeeds
- [x] `pnpm tsc --noEmit` passes
- [x] Every `process.env.*` documented in `.env.example`
- [x] README setup steps match actual env vars and scripts

## Test plan

Each template typechecks cleanly with `tsc --noEmit`. Full runtime
testing requires platform deployment with injected env vars (gateway
key, DB connection, integration keys).

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

This PR adds five complete example projects (templates) that show
developers how to build AI-powered applications using Mastra's latest
features. These templates work by sending requests through a central
Mastra Gateway instead of using API keys directly, making them simpler
and more secure. Think of it like having instruction manuals that show
you how to assemble different things—one for searching documents, one
for controlling web browsers, one for taking meeting notes, one for
searching company knowledge, and one for an autonomous assistant.

## Overview

Added five production-ready template projects demonstrating
Gateway-first Mastra architectures with structured patterns for agents,
workflows, tools, and storage:

- **template-docs-expert** — Web search-powered documentation expert
agent with observational memory (Turso/LibSQL)
- **template-browser-agent** — AgentBrowser-based autonomous web
navigation with browser tools and web search fallback (Turso/LibSQL)
- **template-meeting-notes** — Zoom S2S OAuth cloud recordings →
structured notes + optional Linear/Notion export via MCP (Turso/LibSQL)
- **template-company-knowledge** — Linear + Notion knowledge indexing
with pgvector semantic search and multi-source lookup workflow
(PostgreSQL/Neon with pgvector)
- **template-claw-assistant** — Autonomous computer agent with sandboxed
workspace, file I/O, shell execution, and browser automation
(Turso/LibSQL)

Each template includes `.env.example`, `.gitignore`, `package.json` with
required dependencies, TypeScript configuration, and comprehensive
README with setup/customization guidance.

## Key Implementation Details

**Model & Gateway Routing:**
- All chat models route through Mastra Gateway using
`mastra/openai/gpt-5.4` (reasoning-heavy) or `gpt-5-mini` (lighter
flows)
- Web search implemented via `openai.tools.webSearch()` routed through
OpenRouter-backed Gateway
- Embedding models (`text-embedding-3-small`) use
`ModelRouterEmbeddingModel` because Gateway does not proxy embeddings
(direct `@ai-sdk/openai` with `OPENAI_API_KEY`)

**Agents & Memory:**
- Structured memory configurations with `lastMessages` retention (10-20
messages depending on template) and `observationalMemory` for implicit
context
- Meeting notes agent includes `meetingNotesOutputSchema` Zod schema for
structured output enforcement
- Knowledge agent includes input normalization (Unicode, whitespace
collapsing) and output redaction (PII/secrets detection)

**Workflows:**
- Meeting notes: `ingestMeetingWorkflow` chains Zoom transcript fetch →
summarization with structured output
- Company knowledge: `indexKnowledgeWorkflow` scheduled every 6 hours,
pulls Linear issues + Notion pages, embeds via Gateway, upserts to
pgvector

**MCP Integration:**
- Meeting notes & company knowledge templates conditionally wire Linear
(HTTP remote) and Notion (stdio subprocess) MCP servers based on
presence of API keys
- Tools dynamically discovered at module load via
`mcpClient.listTools()`

**Storage:**
- LibSQL (Turso): docs-expert, browser-agent, meeting-notes,
claw-assistant templates
- PostgreSQL (Neon) with pgvector: company-knowledge template for
semantic search

**Zoom S2S OAuth:**
- `fetchZoomAccessToken()` caches tokens with expiry-aware refresh
- Three exported tools: `listRecentMeetings`, `getMeetingRecording`,
`fetchZoomTranscript`

## Additional Changes

- **Existing templates**: Removed `defaultOptions: { maxSteps: ... }`
from `template-github-review-agent` and `template-google-sheets` agents
- **Documentation**: Added "Available templates" section to
`docs/src/content/en/reference/templates/overview.mdx` with template
listing
- **Templates README**: Expanded `templates/README.md` with "New
Gateway-first templates" section
- **Changeset**: Added `@mastra/core` minor release documenting Gateway
embedding routing support via `ModelRouterEmbeddingModel`

## Validation

- `pnpm install --ignore-workspace` and `pnpm tsc --noEmit` confirmed to
succeed
- `.env.example` documents all required env vars
- README setup steps align with npm/pnpm scripts
- Runtime testing deferred (requires platform-deployed secrets and DB
connections)
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
2026-06-16 12:26:14 -04:00