# Mastra + Tabstack

> Give your Mastra agents reliable web access. Schema-enforced extraction, research, generation, and browser automation as native Mastra tools.

Category: Agent Frameworks
Language: TypeScript
Package: `@tabstack/mastra`
Canonical URL: https://tabstack.ai/integrations/mastra

## Why Mastra + Tabstack

Wiring web access into an agent usually means hand-rolled fetches, HTML parsing, and prompt gymnastics to coax structured data out of messy text. [`@tabstack/mastra`](https://www.npmjs.com/package/@tabstack/mastra) replaces that with a hosted API exposed as typed `createTool` definitions: define the shape with Zod and get that shape back, with JS-heavy pages rendered server-side and one key for extraction, research, generation, and automation.

## Quickstart

Install the adapter and set your key:

```bash
npm install @tabstack/mastra @mastra/core zod

export TABSTACK_API_KEY="your-key-here"
```

`@mastra/core` (v1 or later) and `zod` are peer dependencies, so your app's single instance of each is shared. `tabstackTools` is a named object keyed by tool name, ready to spread into an `Agent`:

```ts
import { Agent } from "@mastra/core/agent";
import { tabstackTools } from "@tabstack/mastra";

const agent = new Agent({
  id: "web-researcher",
  name: "Web Researcher",
  instructions: "Answer questions with current information, and always cite your sources.",
  model: "anthropic/claude-sonnet-4-6",
  tools: tabstackTools,
});

const result = await agent.generate("What are Vercel's pricing plans, with sources?");
console.log(result.text);
```

Want a subset? Every tool is exported individually:

```ts
import { Agent } from "@mastra/core/agent";
import { extractPageContentTool, researchQuestionTool, toolNames } from "@tabstack/mastra";

const agent = new Agent({
  id: "web-researcher",
  name: "Web Researcher",
  instructions: "Summarize pages and research questions.",
  model: "anthropic/claude-sonnet-4-6",
  tools: {
    [toolNames.researchQuestion]: researchQuestionTool,
    [toolNames.extractPageContent]: extractPageContentTool,
  },
});
```

For a custom key, base URL, or a shared client, build the tools explicitly:

```ts
import { createTabstackMastraTools } from "@tabstack/mastra";

const tools = createTabstackMastraTools({ apiKey: process.env.MY_KEY });
// or pass an SDK client you already have: createTabstackMastraTools({ client })
```

## The tools

| Tool | What it does |
| --- | --- |
| `extract_structured_data` | Pull specific fields from a URL into a JSON shape you define. |
| `extract_page_content` | Fetch a page as clean markdown. |
| `research_question` | Synthesized answer with cited sources across multiple pages. |
| `generate_structured_data` | Fetch a page, then AI-transform it into derived or reshaped JSON. |
| `automate_browser_task` | Run a multi-step, natural-language browser task. |

The model fills the inputs in, but the shapes are worth knowing: `extract_structured_data` takes `url` and `json_schema_json` (a JSON-encoded JSON Schema string), `extract_page_content` takes `url`, `research_question` takes `query`, `generate_structured_data` takes `url`, `instructions`, and `json_schema_json`, and `automate_browser_task` takes `task` plus optional `url`, `guardrails`, `data`, `country`, `max_iterations`, and `max_validation_attempts`.

## Optional inputs

The model can pass these for finer control, and they are sent to Tabstack only when present:

- `extract_structured_data`, `extract_page_content`, `generate_structured_data`: `effort` (`"min"`, `"standard"`, or `"max"`, where `"max"` suits JS-heavy pages), `nocache` to bypass the cache, and `country` as an ISO 3166-1 alpha-2 code for geotargeted fetches.
- `research_question`: `mode` (`"fast"` or `"balanced"`) and `nocache`.

## Good to know

- **`automate_browser_task` runs non-interactively.** It does not pause for human-in-the-loop form input, so it never blocks. It returns the final answer plus the data it extracted and the pages it visited.
- Failed calls throw `TabstackToolError`, a normalized message plus an HTTP `status` for API errors. Mastra surfaces this in the tool result.
- Tool names, descriptions, and inputs match the `@tabstack/langchain` and Python `langchain-tabstack` packages, so behavior is consistent across frameworks and languages.

## Common use cases

- Give a Mastra agent cited, multi-source answers from the live web.
- Pull structured fields off a page into a Zod-defined shape.
- Geotarget a fetch by country to see region-specific pricing or availability.
- Keep tool names consistent across your TypeScript and Python agents.

## Next steps

- [Adapter on GitHub](https://github.com/Mozilla-Ocho/tabstack-integrations-typescript)
- [@tabstack/mastra on npm](https://www.npmjs.com/package/@tabstack/mastra)
- [Mastra docs](https://mastra.ai)
- [Get an API key](https://console.tabstack.ai/signup)

---

- All integrations: https://tabstack.ai/integrations
- Agent quickstart, every endpoint in one file: https://tabstack.ai/agents.md
- Full documentation: https://docs.tabstack.ai/