Connect Mastra agents to Router One with one model url and one key

Install Mastra and set your credentials

Mastra v1 requires Node.js 22.13.0 or newer, and its docs note that Node.js 22.18.0 and later run TypeScript files directly, which is how this guide runs agent.ts. For a new project, create-mastra builds a starter configured for the model provider you select (OpenAI, Anthropic, Gemini, or xAI), and its --empty flag creates a provider-free scaffold without agents, which is the closer fit here. To add Mastra to an existing project, make sure package.json has "type": "module" and install the packages the Mastra quickstart lists, as below. No AI SDK provider package is needed for the object form used in this guide: @mastra/core bundles the OpenAI-compatible provider it builds from that object. The shell example is for macOS/Linux; replace the placeholder with a Router One key created for this agent. ROUTER_ONE_API_KEY is a name this example chooses and reads explicitly. Mastra does not look up any environment variable for a model that has url set, so the key has to be passed as apiKey, and OPENAI_API_KEY is not needed.

# New project instead: npx create-mastra@latest my-app --empty
npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest
export ROUTER_ONE_API_KEY="sk-your-router-one-key"

Configure Mastra to use the Router One base URL

Save this as agent.ts and run node agent.ts. The model field takes an object instead of a provider/model string. id is split at the first slash: the first segment (custom, the label Mastra's docs use for a custom endpoint) becomes the provider name in Mastra's logs and spans, and everything after it is sent as the model field of the request, so custom/anthropic/claude-sonnet-5 sends anthropic/claude-sonnet-5 and custom/grok-4.6 sends grok-4.6. Replace the placeholder with the exact ID from /models and keep custom/ in front of it. url is the /v1 base URL, not the chat endpoint: the bundled OpenAI-compatible provider appends /chat/completions, so each model call is one POST /v1/chat/completions. apiKey becomes the Authorization: Bearer header. The tool is defined with createTool (id, description, a zod inputSchema, execute) and registered under the key addTool; that key is the function name the model sees in the request's tools field, which is sent with tool_choice auto. generate() returns after the whole loop: with this prompt the first request comes back with a tool call, Mastra runs execute in your process, and a second request returns the answer, so result.steps has two entries and result.usage sums the tokens the API reported for both. maxSteps: 3 caps the loop at three model calls; without it the default is 5. stream() sends the same request with stream: true and yields text through textStream as it arrives. In a Mastra project, keep the Agent under src/mastra/agents and register it in src/mastra/index.ts with new Mastra({ agents: { routerOneAgent } }); the model object is identical.

import { Agent } from "@mastra/core/agent";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

const addTool = createTool({
  id: "add",
  description: "Add two numbers",
  inputSchema: z.object({ a: z.number(), b: z.number() }),
  execute: async ({ a, b }) => ({ sum: a + b }),
});

export const routerOneAgent = new Agent({
  id: "router-one-agent",
  name: "Router One Agent",
  instructions: "You are a concise assistant. Use the add tool for arithmetic.",
  model: {
    // Mastra strips the "custom/" label and sends the rest as the model, e.g. custom/anthropic/claude-sonnet-5
    id: "custom/<exact-model-id-from-/models>",
    url: "https://api.router.one/v1",
    apiKey: process.env.ROUTER_ONE_API_KEY,
  },
  tools: { addTool },
});

// 1. generate(): one POST /v1/chat/completions per step; maxSteps caps the loop (default 5)
const result = await routerOneAgent.generate("What is 2 + 3?", { maxSteps: 3 });
console.log(result.text, result.steps.length, result.usage);

// 2. stream(): the same request with stream: true
const stream = await routerOneAgent.stream("Say hello in five words.");
for await (const chunk of stream.textStream) process.stdout.write(chunk);

Which Mastra setting sends which request

The model object carries the connection; the Agent options decide how many requests a call makes and what each one asks for. The rows below give the value used in this guide, the request it produces, and what to confirm before relying on it.

Budget one agent and reconcile its requests

One generate() or stream() call is a loop: each step is one POST /v1/chat/completions, a step that returns tool calls is followed by another step after Mastra runs the tools, and the loop ends when the model answers without a tool call or maxSteps is reached (default 5). Input tokens grow with every step, because each request resends the instructions, the conversation, and all earlier tool calls and results, so maxSteps bounds the number of requests, not the spend. Retries add requests only if you ask for them: the Agent option maxRetries defaults to 0 in the current API, so a failed call is not repeated; with maxRetries: 2, a persistent 5xx becomes three requests for that step. Retryable means 408, 409, 429, 5xx, or an error that is not an HTTP response; 401, 402, and 404 are never retried. The older generateLegacy() path keeps its own maxRetries with a default of 2. A model array with fallback entries multiplies again, since each entry has its own retry count; the gateway's same-family fallback on 5xx and timeouts happens before a response reaches Mastra, so a client-side list adds requests only when the gateway itself returns an error. Optional features send model requests of their own: structuredOutput with a separate model makes two calls per answer, generateTitle adds a call on the agent's model unless you give it another, and Observational Memory runs background Observer and Reflector agents. Every attempt that reaches the gateway is its own row in Dashboard → Logs with its own request_id, cost, and status. Give each agent a dedicated key with maxSpend: a looping run then gets HTTP 402 at the cap you set, surfaced as AI_APICallError with statusCode 402, and the wallet and your other keys are untouched. result.usage, the per-step usage in result.steps, and the token and cost figures in Mastra's tracing are Mastra's tally and estimate of what the API reported; the charge is what Logs records. Reconcile by key, time, model, and token counts, and keep the request_id when reporting a failure. Router One records model-call metadata; it does not run the agent loop, your tools, workflows, memory, or storage.

Memory, semantic recall, and the embedder stay on your side

Memory is a Mastra feature backed by your own storage: install @mastra/memory and a storage adapter such as @mastra/libsql, and pass resource and thread with each call. Message history then loads the last 10 messages by default (lastMessages) into every request, which raises input tokens per step but adds no request. Semantic recall is disabled by default and needs two more pieces, a vector store and an embedder; the embedder is called on every turn, first to embed the new prompt for the search and afterward to embed the new messages for the index. Router One serves no /v1/embeddings, so do not point the embedder at the gateway: keep it on a provider that offers embeddings, for example ModelRouterEmbeddingModel('openai/text-embedding-3-small') with that provider's own key, or run it locally with fastembed from @mastra/fastembed. Those calls never appear in Dashboard → Logs. Observational Memory is different: its Observer and Reflector are chat-model calls, and when no model is set they default to a Google model resolved through Mastra's model router with a Google API key from your environment, outside the gateway. Its model option takes the same types as an Agent's model, so passing the same id, url, and apiKey object puts those background calls on your Router One key and into Logs. generateTitle likewise accepts a model and otherwise uses the agent's own. Threads, vectors, and working memory stay in the storage you configured; the gateway sees only the messages of each model request.

Which model ID should Mastra send?

Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in Mastra. A catalog listing does not mean the client can use every feature of that model. Give each tool a dedicated API key with a maxSpend cap.

Which API protocol is Mastra using?

OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.

Verify the Mastra call in your request trace

Send a simple text request from Mastra, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.

FAQ