0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/templates/template-docs-expert
Justin Levine 5b8c65005c
feat(templates): read the model from AGENT_MODEL in Docs Expert (#29746)
## Description

Docs Expert 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).

## Related issue(s)

Linear PLTFRM-3314

## 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 against the published packages. `tsc` is
clean.


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

## ELI5

The Docs Expert template can now use a model chosen through
`AGENT_MODEL`. If the setting is missing or contains only whitespace, it
uses `mastra/openai/gpt-5-mini`.

## Changes

- Added `AGENT_MODEL` to the template’s `.env.example`, with example
model IDs and the default.
- Updated `docsExpert` to use the trimmed `AGENT_MODEL` value or the
default.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
History 2026-11-09 18:01:54 +00:00
..
src/mastra feat(templates): read the model from AGENT_MODEL in Docs Expert (#29746) 2026-11-09 18:01:54 +00:00
.env.example feat(templates): read the model from AGENT_MODEL in Docs Expert (#29746) 2026-11-09 18:01:54 +00:00
.gitignore feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00
package.json chore: unify built-in Gateway naming (#18691) 2026-07-13 17:26:20 +02:00
README.md chore: unify built-in Gateway naming (#18691) 2026-07-13 17:26:20 +02:00
tsconfig.json feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00

Docs Expert

A research assistant that answers questions about libraries, APIs, and documentation by searching the live web and citing its sources. It uses a Mastra web_search tool routed through the Gateway/OpenRouter web search — no extra search API key needed.

The agent uses observational memory so it learns what docs and topics you've asked about, building persistent context over time. All state is persisted to Turso (libSQL).

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 — proxies to OpenAI, Anthropic, Google, etc. behind a single key.
  • A Turso database (URL + auth token) for storage. A free dev tier is fine; in-memory libSQL works too if you swap the URL to :memory:.

Quickstart 🚀

  1. Add your API keys
    • Copy .env.example to .env and fill in your keys.
  2. Start the dev server

Ask things like:

  • "What's the current API for openai.tools.webSearch() in @ai-sdk/openai?"
  • "Compare pgvector HNSW vs IVFFlat indexes for cosine similarity."
  • "What changed in Node 22 LTS vs 20 LTS?"

Making it yours

  • Swap the model. Change the agent model or the web_search tool's Gateway model independently. The tool calls Gateway's OpenRouter-compatible web-search server tool, so it does not need an OpenAI, Exa, or Tavily key.
  • Tighten the system prompt. Constrain the agent to a single docs domain (e.g. "only answer about Mastra") and require it to refuse unrelated questions.
  • Add structured output. Set structuredOutput on the agent or call generate({ output: z.object({ answer: z.string(), sources: z.array(...) }) }) to force JSON with citations.
  • Persist conversations. This template already wires Memory + Turso, so threads survive restarts.

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.