Skip to main content
This notebook demonstrates how to build a tool-calling agent with Mastra and run it on ZeroGPU with a single model string. You’ll build Trail Guide, the gear assistant for a small outdoor store called Trail Shop: it checks a live weather forecast, searches the shop’s catalog, and recommends gear with prices and a total. Then you’ll chat with it in Mastra Studio and switch to a different ZeroGPU model in the middle of the conversation. By combining Mastra and ZeroGPU, this notebook walks you through a practical pattern for running real agents with tools and memory on a low-cost model provider, with no provider package at all, because Mastra reads ZeroGPU straight from models.dev. For the full reference, see the Mastra integration guide. For how ZeroGPU’s listing works and which other tools read it, see the Models.dev integration guide. In this notebook, you’ll explore:
  • 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.
This setup not only demonstrates a practical application of tool-calling agents on a low-cost model, but also provides a flexible framework that can be adapted to other real-world scenarios requiring agents that combine live data, your own catalog, and conversation memory to give grounded recommendations.

🎥 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:
That’s every package. @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
See the Mastra integration guide for every way to configure a ZeroGPU model.

🔑 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 with zgpu-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:
Prefer a file? 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:
Mastra publishes the result as its own ZeroGPU provider page, with the same nine models. That’s the whole integration: the endpoint Mastra will call, the variable it reads your key from, and the models you can name as 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 throwaway check.ts in the project root. The only ZeroGPU-specific part is the model string:
check.ts
Behind that one line, Mastra found 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. The model line is the whole ZeroGPU integration:
src/mastra/agents/trail-guide.ts
DeepSeek V4.1 Flash is the model in Mastra’s own ZeroGPU example, and it called both tools in every test run. 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 where ZEROGPU_API_KEY is set, start the dev server:
It’s ready in about 2 seconds. The storage line is normal; it’s LibSQL setting up the in-memory database. Open http://localhost:4111/agents/trail-guide/threads/new to start a chat with Trail Guide.

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 because ZEROGPU_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:
Two rows appear first, GetForecast and SearchProducts: the agent checks the weather, then looks up the catalog. Then the answer streams in. In our tests, DeepSeek V4.1 Flash called both tools and answered in 11 to 14 seconds:
The forecast is live, so the weather sentence and the products the agent picks change from day to day. Seattle usually gives a rainy-gear answer, and any city works.

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:
These are real tool calls with live weather data, decided and summarized by a model running on ZeroGPU. Click the row again to close it. The SearchProducts row works the same way and shows the catalog entries the agent chose from.

Step 10: Switch models mid-chat

Click the model name and pick GPT-5.6 Luna. Then send a follow-up:
The new model picks up the conversation from memory and trims the list. In our tests, GPT-5.6 Luna answered in 10 to 15 seconds:
The exact list changes from run to run; our test runs came back at $218 and $238, both under the budget. Switching models doesn’t need a new key or any code change, because both are ZeroGPU models.

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 about 6,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
You get the same two answers as in Studio. To restart the Studio demo with a clean chat, press Ctrl + C where 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.
This comprehensive setup allows you to adapt and expand the example for various scenarios requiring agents that combine live data, your own catalog, and conversation memory to give grounded recommendations.