Skip to main content
Mastra is an open-source TypeScript framework for building AI agents and workflows. It gives you agents with tools and memory, graph-based workflows, structured output, model fallbacks, and Mastra Studio, a local playground where you chat with your agents and inspect every tool call. Its model router takes a single provider/model string and generates its provider registry from models.dev, so every provider listed there works in Mastra without installing a provider package. ZeroGPU is listed on models.dev, which means model: 'zerogpu/deepseek-v4.1-flash' and a ZEROGPU_API_KEY are all it takes to run a Mastra agent on ZeroGPU. ZeroGPU is a compute-efficient inference provider for apps and agents. We run purpose-built small and nano language models across an edge network for the high-volume tasks you run constantly - classification, extraction, moderation, routing, summarization - at ~10x lower latency and 50%+ lower cost than frontier-model workflows. Auto-scaling, with zero GPU infrastructure to manage. Plug in and you’re live.

Overview

This guide covers building Mastra agents on ZeroGPU, for TypeScript developers who want a low-cost, low-latency model provider behind their agents and workflows. You’ll set your key, point an agent at a ZeroGPU model string, and make your first call, then work through every surface Mastra exposes for a provider: the model router string, the OpenAI-compatible config object, unlisted ZeroGPU models, generate() and stream(), tools, memory, structured output, model settings, provider options for reasoning, fallbacks, dynamic model selection, workflows, and Mastra Studio. By the end you’ll have tool-calling agents running on ZeroGPU for well under a cent per answer.

Cookbook

For a runnable, real-world example, see Build a Trail Gear Agent with Mastra and ZeroGPU. It builds a gear assistant for an outdoor store with two tools, a live weather forecast and the shop’s catalog, runs it on DeepSeek V4.1 Flash in Mastra Studio, and then switches to GPT-5.6 Luna mid-conversation. Both answers together cost well under a cent. Check it out to see the model router, tools, memory, and Studio working end to end.
For more worked examples, browse the cookbook index for end-to-end walkthroughs of classification, extraction, and PII workflows on ZeroGPU’s small models.

Video walkthrough

Quickstart

Prerequisites

  • A ZeroGPU API key (starts with zgpu-api-).
  • Node.js 22.13 or later.
  • @mastra/core 1.85.0 or later, the first release whose provider registry includes ZeroGPU.
  • A chat model from the model catalog that models.dev lists. This guide uses deepseek-v4.1-flash, which called every tool reliably in our tests.

Get your ZeroGPU API key

  1. Sign in to the ZeroGPU dashboard.
  2. Open API Keys and click Create key.
  3. Copy the key (starts with zgpu-api-) and export it as ZEROGPU_API_KEY, the variable models.dev lists for ZeroGPU. Mastra reads it automatically for every zerogpu/* model.
You can put the same line in a .env file at your project root instead. mastra dev loads .env.development, .env.local, and .env for you.
.env

Install Mastra

Add Mastra to an existing TypeScript project. @mastra/core holds agents, tools, workflows, and the model router, and the mastra CLI runs Mastra Studio:
To start from scratch instead, npm create mastra@latest scaffolds a new project. Either way, there’s no ZeroGPU package to install.

Your first request

Create an agent with a ZeroGPU model string and call it once:
hello.ts
Mastra looked up zerogpu in its registry, read your key from ZEROGPU_API_KEY, and sent an OpenAI-compatible POST /chat/completions request to https://api.zerogpu.ai/v1, the endpoint models.dev lists for ZeroGPU.

Usage

Every section below follows the same shape: what the surface does, what it calls on ZeroGPU, its parameters, a runnable example, and what you get back.

How Mastra finds ZeroGPU

Mastra’s model router ships a provider registry generated from the models.dev catalog. ZeroGPU’s entry gives the router everything it needs, so there’s no provider to register: These nine ZeroGPU models are in the registry. Prices are USD per 1M tokens, and the reasoning controls are explained in Provider options and reasoning. All nine support tool calling and structured output. For cache prices, input types, and the full catalog metadata, see the Models.dev integration guide. In development, Mastra refreshes the registry from models.dev every hour; in production it uses the registry bundled with your installed @mastra/core unless you set MASTRA_AUTO_REFRESH_PROVIDERS=true. ZeroGPU models that models.dev doesn’t list yet can be added by hand; see Unlisted ZeroGPU models.

Model router string

The simplest way to use ZeroGPU: pass zerogpu/<model-id> as an agent’s model. Mastra resolves the provider, the endpoint, and the key for you, and the string is typed, so your editor autocompletes the nine ZeroGPU model IDs.
TypeScript
Response: every call from this agent goes to ZeroGPU’s gpt-5.4-nano. Change the string to move the agent to any other ZeroGPU model; nothing else changes.

OpenAI-compatible config object

Use an object instead of a string when one agent needs its own key, extra headers, or a different endpoint. Mastra still treats it as a ZeroGPU model.
TypeScript
Response: this agent’s requests carry its own key and the project header, while other agents keep using ZEROGPU_API_KEY. The x-project-id header is optional; leave it out unless you track usage per project.

Unlisted ZeroGPU models

ZeroGPU serves more chat models than models.dev lists. To use one, give Mastra the endpoint yourself with the providerId and modelId form. Model IDs are sent exactly as written, and they’re case-sensitive.
TypeScript
Response: the agent calls LFM2.5-1.2B-Instruct at ZeroGPU’s rates. Give the Llama 3.2 and LFM2.5 models agents without tools: they’re built for fast chat and summarization and reject tool definitions. Prices are from the model catalog in November 2026. When models.dev adds one of these models, switch back to the plain zerogpu/<model-id> string.

agent.generate()

Runs the agent to completion and returns the final answer. When the agent has tools, Mastra loops: each step is one POST /chat/completions call to ZeroGPU, tool calls run locally, and their results go back to the model until it answers.
TypeScript

agent.stream()

Same options as generate(), but returns as soon as ZeroGPU starts responding, so you can show text as it arrives.
TypeScript
Response: the answer prints token by token after the tool steps finish. All nine registry models stream on ZeroGPU.

Tools

Tools let the model fetch data or take actions. Every ZeroGPU model in the registry supports tool calling, so Mastra sends your tool schemas with each request and runs whichever tool the model picks.
src/mastra/tools/search-products.ts
Pass tools to an agent as a map. The keys are the tool names the model sees:
TypeScript
Response: when the model calls a tool, Mastra validates the arguments against inputSchema, runs execute, and sends the result back to ZeroGPU for the next step. In our tests DeepSeek V4.1 Flash called both of the cookbook’s tools on every run. Keep descriptions specific and say in the instructions when each tool should be used.

Memory

Memory keeps a conversation’s history so follow-ups like “Keep it under $250” work. Add Memory from @mastra/memory to the agent and storage to your Mastra instance, then pass a thread and a resource with each call.
src/mastra/index.ts
TypeScript
Response: the second call loads the first exchange from storage, so the model updates the earlier list instead of starting over. Use url: ':memory:' for throwaway demos (history is lost when the process stops) and a file or hosted database for anything you want to keep.

Structured output

Returns a typed object instead of free text. Mastra’s ZeroGPU client sends your schema as a JSON-schema response_format, and every registry model supports it.
TypeScript
Response: result.object is typed from the schema. Small models such as gpt-5.4-nano handle extraction like this well, at a fraction of a chat model’s cost.

Model settings and defaults

Sampling settings for a call, set per call in modelSettings or for every call in the agent’s defaultOptions.
TypeScript
Response: every call starts from these defaults, and options passed to generate() or stream() override them. topK isn’t part of the OpenAI-compatible API, so Mastra drops it with a warning.

Provider options and reasoning

Passes ZeroGPU request fields straight through. Mastra names its ZeroGPU client zerogpu, so fields under providerOptions.zerogpu are merged into the request body. reasoningEffort is the one renamed field: it’s sent as reasoning_effort.
TypeScript
For GPT-5.6 Luna, set only the effort: providerOptions: { zerogpu: { reasoningEffort: 'high' } }. For the Qwen models, toggle thinking with providerOptions: { zerogpu: { chat_template_kwargs: { enable_thinking: true } } }. Response: the run reasons before answering and the reasoning tokens are billed as output. ZeroGPU doesn’t return reasoning text on this API, so result.reasoningText stays empty and Studio shows no thinking blocks.

Model fallbacks

Pass an array of models and Mastra moves to the next one when a model keeps failing. Because every entry can be a ZeroGPU model, one key covers the whole chain.
TypeScript
Response: calls go to DeepSeek V4.1 Flash first. If it errors three times, the same request goes to GPT-5.6 Luna, then GLM-5.3-Flash.

Dynamic model selection

model can be a function that picks a model per request from the request context, for example by customer tier or task size.
TypeScript
Response: pro customers get GPT-5.6 Luna and everyone else gets GPT-5.4 nano, from the same agent and the same key.

Workflows

Workflows chain steps with typed inputs and outputs. createStep(agent) turns an agent into a step that takes { prompt } and returns { text }, so a ZeroGPU agent drops into any workflow.
TypeScript
Response: the agent step runs on ZeroGPU with its tools, and result.result.text holds its answer. Register the workflow in new Mastra({ workflows: { gearList } }) to run it from Studio too.

Mastra Studio (mastra dev)

mastra dev starts a local server for your Mastra instance and opens Mastra Studio, where you chat with agents, watch tool calls, and switch models without editing code.
package.json
Response: open the agent, type a message, and the reply streams in with a row for each tool call. Pick another ZeroGPU model in the picker and the next message goes to it, with the conversation so far kept in memory. In the cookbook, DeepSeek V4.1 Flash called both tools and answered in 11 to 14 seconds, and the GPT-5.6 Luna follow-up took 10 to 15 seconds.

Patterns and recipes

Cheap triage in front of a capable agent. Put a small model on the decision and a stronger one on the answer. A gpt-5.4-nano agent with structured output classifies the request, and only gear questions reach the tool-using agent on deepseek-v4.1-flash:
TypeScript
Think on demand. Keep DeepSeek V4.1 Flash on its fast, thinking-off default for everyday turns, and pass providerOptions: { zerogpu: { thinking: { type: 'enabled' } } } only on requests that need planning, as in Provider options and reasoning. You pay for reasoning tokens only where they help. A fallback chain on one key. List two or three ZeroGPU models in a fallback array. They share ZEROGPU_API_KEY and the same tool definitions, so a failover changes nothing for your tools or your billing setup. Price a run before you scale it. Multiply result.totalUsage by the per-1M prices in the model table. A tool-calling turn that sends about 6,000 input tokens and gets 200 back on DeepSeek V4.1 Flash costs about 6,000 x $0.30/1M + 200 x $1.20/1M = $0.0020, which is why the cookbook’s two answers together cost well under a cent.

At a glance

Troubleshooting

zerogpu/... isn’t accepted as a model, or TypeScript rejects the string. Your @mastra/core predates ZeroGPU’s models.dev listing. Run npm install @mastra/core@latest to get 1.85.0 or later, then restart mastra dev. The agent replies with an error about a missing API key. The process running Mastra can’t see ZEROGPU_API_KEY. Export it in the same terminal before npm run dev, or put it in .env at the project root, then restart. Run [ -n "$ZEROGPU_API_KEY" ] && echo set to check without printing the key. 401 or 403 invalid_api_key on the first message. The key is wrong, revoked, or picked up a stray space when pasted. Create a fresh key in the dashboard and update the variable or .env. Studio’s model picker shows other providers as not connected. That’s expected. Studio lists every provider in Mastra’s registry and marks only the ones whose key variable is set. With just ZEROGPU_API_KEY set, ZeroGPU is the only connected provider. npm run dev says “Another development server instance is already running”. An earlier mastra dev is still running for this folder. Stop it with Ctrl + C in its terminal; if there isn’t one, delete .mastra/dev.lock and run npm run dev again. Chats disappear when you restart mastra dev. Your storage uses url: ':memory:', which keeps threads only while the process runs. Switch LibSQLStore to url: 'file:./mastra.db' to keep them. The agent answers without calling its tools, or recommends products the tool didn’t return. Say in the instructions which tool to call and when, and to recommend only what the tools return. Model choice matters too: in our tests DeepSeek V4.1 Flash called both tools on every run. If the agent stops right after a tool call with no answer, raise maxSteps. model not found for a model that isn’t in the registry. The router only knows the nine listed models. For others, use the providerId and modelId form with url, and send the exact, case-sensitive ID, such as LFM2.5-1.2B-Instruct. An LFM2.5 or Llama 3.2 agent fails as soon as it has tools. These models don’t accept tool definitions. Give them agents without tools, and keep tool-calling agents on a registry model. Production doesn’t see a model that development does. Development refreshes the registry from models.dev every hour, while production uses the registry bundled with your installed @mastra/core. Upgrade @mastra/core, or set MASTRA_AUTO_REFRESH_PROVIDERS=true in production. No thinking blocks appear with reasoning turned on. ZeroGPU doesn’t return reasoning text on the chat completions API, so there’s nothing for Mastra or Studio to show. The model still reasons, and the reasoning tokens are billed as output.

Conclusion

Mastra reads ZeroGPU straight from models.dev, so moving an agent onto ZeroGPU is one model string and one environment variable, with no provider package. Tools, memory, structured output, fallbacks, and Studio all work the same way they do with any other provider, and with ZeroGPU’s low-cost models a tool-calling answer costs a fraction of a cent.

Model Catalog

Browse every model available on ZeroGPU and pick the best fit.

API Reference

Explore the full OpenAI-compatible API surface.

Cookbook

Build a trail gear agent with Mastra on ZeroGPU.

Join Discord

Ask questions and share what you’re building.