- Mastra: An open-source TypeScript framework for building AI agents and workflows, with tools, memory, and Mastra Studio for chatting with agents locally. Its model router generates its providers from models.dev, so
zerogpu/<model-id>works with no extra setup. Here it runs the Trail Guide agent, its two tools, and the chat in Studio. - ZeroGPU: 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.
- Models.dev: An open-source database of AI model specifications, pricing, and capabilities that Mastra builds its model router from. ZeroGPU’s listing supplies the endpoint, the API key variable, and the nine chat models you’ll pick from in Studio.
- Open-Meteo: A free, open weather forecast API that needs no key. The agent’s forecast tool calls it for a live 3-day forecast of wherever the customer is hiking.
🎥 Watch the Video Guide
If you prefer a visual walkthrough, check out the accompanying video guide below:📦 Installation
First, create the project and install Mastra with all its dependencies. You’ll need Node.js 22.13 or later:@mastra/core brings agents, tools, and the model router, @mastra/memory and @mastra/libsql let the agent remember the conversation, and the mastra CLI runs Mastra Studio. This cookbook was built with @mastra/core 1.85.0 and mastra 1.40.1; you need @mastra/core 1.85.0 or later, the first release that includes ZeroGPU.
ZeroGPU needs no SDK here. Mastra already knows ZeroGPU’s endpoint and models from models.dev, so all it needs is your key. Add a TypeScript config so imports with .ts extensions resolve:
tsconfig.json
🔑 Setting Up API Keys
You’ll need to set up your API key for ZeroGPU. This ensures that Mastra can reach ZeroGPU’s models securely. Open-Meteo is free and needs no key, so ZeroGPU’s is the only one. You can go to here to get an API key from ZeroGPU. The key starts withzgpu-api-.
Export it in the terminal you’ll run Mastra from, under the name models.dev lists for ZeroGPU. Mastra picks it up automatically for every zerogpu/* model:
mastra dev also loads a .env file from the project root. Keep a placeholder in .env.example so teammates know which variable to set, and put your real key only in .env:
.env.example
🗂️ Finding ZeroGPU on Models.dev and Mastra
Mastra doesn’t ship a hand-written ZeroGPU integration. Its model router is generated from the models.dev catalog, so ZeroGPU’s listing at models.dev/providers/zerogpu is what puts ZeroGPU in Mastra. You can query the same entry Mastra reads:zerogpu/<model-id>. You’ll start on deepseek-v4.1-flash, listed at $0.30 per 1M input tokens and $1.20 per 1M output tokens, and switch to gpt-5.6-luna ($0.20 in, $1.20 out) later.
🔌 Access Tool-Calling Agents with 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. In this section, we will make one call to a Mastra agent on DeepSeek V4.1 Flash as an example. Create a throwawaycheck.ts in the project root. The only ZeroGPU-specific part is the model string:
check.ts
zerogpu in its registry, read ZEROGPU_API_KEY, and sent the request to https://api.zerogpu.ai/v1/chat/completions. You can delete check.ts now.
🎉 ZeroGPU effortlessly plugs into Mastra straight from its models.dev listing, providing a one-line, no-package model provider for AI integration!
🏕️ Building the Trail Guide Agent with Mastra
This section builds a real agent with two tools and memory, runs it in Mastra Studio, and switches it to a second ZeroGPU model mid-chat. Every model call behind it runs on ZeroGPU. When you’re done, the project looks like this:Step 1: Add the shop’s catalog
Trail Shop sells eight products in five categories. This is the data the agent will search, and the only products it’s allowed to recommend:src/mastra/data/products.ts
Step 2: Build the forecast tool
The first tool turns a place name into coordinates with Open-Meteo’s geocoding API, then fetches a 3-day forecast in Fahrenheit. It labels the days Today, Tomorrow, and the next weekday, so the model doesn’t have to work out dates:src/mastra/tools/get-forecast.ts
Step 3: Build the catalog search tool
The second tool filters the catalog by category and maximum price. Both filters are optional, so the model can also ask for everything and choose for itself:src/mastra/tools/search-products.ts
Step 4: Create the agent
Now the agent itself. The instructions tell it to check the forecast first, then search the catalog, and to answer in a fixed shape: one sentence about the weather, 3 to 4 products, and a total. Themodel line is the whole ZeroGPU integration:
src/mastra/agents/trail-guide.ts
new Memory() is what lets the agent handle a follow-up like “Keep it under $250” later on.
Step 5: Register the agent with Mastra
The Mastra instance is what Studio loads. It registers the agent and gives memory somewhere to store the conversation.:memory: keeps it in memory, so every restart starts with a clean chat:
src/mastra/index.ts
Step 6: Start Mastra Studio
From the terminal whereZEROGPU_API_KEY is set, start the dev server:
Step 7: Look at the model picker
Click the model name under the message box, DeepSeek V4.1 Flash. The list shows all nine ZeroGPU models, straight from models.dev, with ZeroGPU marked as connected becauseZEROGPU_API_KEY is set. The other providers in the picker are the rest of Mastra’s registry; they show as not connected until you set their keys. Click DeepSeek V4.1 Flash again to close the list.
Step 8: Ask for gear
Type this prompt and press Enter. Then keep your hands off for about 15 seconds:Step 9: Inspect the tool call
Click the GetForecast row to open it. The input is what the model sent, and the output is what the tool returned from Open-Meteo:Step 10: Switch models mid-chat
Click the model name and pick GPT-5.6 Luna. Then send a follow-up:Step 11: Check the cost
Both answers together cost well under a cent. Each one is a few model steps, mostly input tokens: the instructions, the tool schemas, and the tool results. You can price any run from the catalog numbers you looked up earlier. A turn that sends about 6,000 input tokens and gets 200 back on DeepSeek V4.1 Flash costs about6,000 x $0.30/1M + 200 x $1.20/1M = $0.0020.
Step 12: Call the agent from code (optional)
Studio is for trying things out. In your app, call the same agent through the Mastra instance and give it a memory thread so follow-ups work:ask.ts
npm run dev is running and start it again: the in-memory storage clears, and the agent is back on DeepSeek V4.1 Flash.
🎉 From one model string, Mastra on ZeroGPU checked a live forecast, searched the shop’s catalog, recommended grounded gear with a total, and then kept the conversation going on a second ZeroGPU model, in about 15 seconds per answer and for well under a cent. Your key is all Mastra needs, so any agent you build next can use any of ZeroGPU’s nine models by name.
🌟 Highlights
This notebook has guided you through setting up and running a Mastra workflow with ZeroGPU for building a tool-calling gear assistant. You can adapt and expand this example for various other scenarios requiring agents that combine live data, your own catalog, and conversation memory to give grounded recommendations. Key tools utilized in this notebook include:- Mastra: An open-source TypeScript framework for building AI agents and workflows, with tools, memory, and Mastra Studio for chatting with agents locally. Its model router generates its providers from models.dev, so
zerogpu/<model-id>works with no extra setup. Here it runs the Trail Guide agent, its two tools, and the chat in Studio. - ZeroGPU: 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.
- Models.dev: An open-source database of AI model specifications, pricing, and capabilities that Mastra builds its model router from. ZeroGPU’s listing supplies the endpoint, the API key variable, and the nine chat models you’ll pick from in Studio.
- Open-Meteo: A free, open weather forecast API that needs no key. The agent’s forecast tool calls it for a live 3-day forecast of wherever the customer is hiking.

