Skip to content

Mastra

Your Mastra agents, tools and workflows stay as they are. Give the model an address and a key and every call an agent makes goes through the gateway: checked against your policies, charged to the right team and recorded in Request logs, on Claude, Gemini or OpenAI models.

What it is

Mastra is a TypeScript framework for agents and workflows. An agent's model can be given three ways, and two of them take a custom address:

  • A model object with a url (Mastra's own form for OpenAI-compatible endpoints): { id, url, apiKey }. It speaks the OpenAI Chat Completions format, which the gateway accepts at /v1 and translates for Anthropic, Gemini and Vertex AI models.
  • A model from an AI SDK provider (createOpenAI, createAnthropic, createGoogleGenerativeAI with a baseURL): the same providers as the Vercel AI SDK, in the OpenAI, Anthropic or Gemini format.
  • A plain "provider/model" string ("openai/gpt-4o-mini") goes to that provider directly, with its own key: don't use it for calls you want governed.

The two settings

Form Base address Key Value
Model object url apiKey https://<your-gateway>/v1
createOpenAI (@ai-sdk/openai) baseURL apiKey https://<your-gateway>/v1
createAnthropic (@ai-sdk/anthropic) baseURL apiKey https://<your-gateway>/v1 (this provider adds /messages)
createGoogleGenerativeAI (@ai-sdk/google) baseURL apiKey https://<your-gateway>/v1beta

The key is your Vidai key (starts vk_), never a provider's key; keep it in an environment variable such as VIDAI_API_KEY. The OpenAI forms send it as Authorization: Bearer, the Anthropic provider as x-api-key, the Google provider as x-goog-api-key; the gateway accepts all three.

The gateway's address, and the base URL for each kind of SDK, are under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.

A minimal call

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a helpful assistant.",
  model: {
    id: "vidai/claude-sonnet-4.5",       // "vidai/" is only a label; the rest is the model name
    url: "https://<your-gateway>/v1",
    apiKey: process.env.VIDAI_API_KEY,
  },
});

const result = await agent.generate("Say hello in Dutch.");
console.log(result.text);
import { Agent } from "@mastra/core/agent";
import { createOpenAI } from "@ai-sdk/openai";

const vidai = createOpenAI({
  baseURL: "https://<your-gateway>/v1",
  apiKey: process.env.VIDAI_API_KEY,
});

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a helpful assistant.",
  model: vidai.chat("claude-sonnet-4.5"),  // .chat: Chat Completions
});

In the model object, the part of id before the first slash is a label of your choosing; Mastra sends the rest as the model name. Use the OpenAI provider's .chat(...): the provider's default (vidai("…")) uses the Responses API, which the gateway sends to OpenAI models only. Either way, the same code calls gpt-4o-mini or gemini-3.5-flash: the gateway translates the request and the answer.

Streaming

const stream = await agent.stream("Count to five.");
for await (const text of stream.textStream) {
  process.stdout.write(text);
}

A stream from another provider arrives in the format the model speaks. Vidai records the tokens and the cost either way.

Tool calls

Tools made with createTool work on every provider the gateway translates to; each round trip is a call through the gateway.

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

const weatherTool = createTool({
  id: "get-weather",
  description: "Weather for a city",
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => `Sunny in ${city}`,
});

const agent = new Agent({
  id: "weather",
  name: "Weather",
  instructions: "Answer weather questions with the tool.",
  model: { id: "vidai/gpt-4o-mini", url: "https://<your-gateway>/v1", apiKey: process.env.VIDAI_API_KEY },
  tools: { weatherTool },
});

Reading what the gateway did

Find the calls in Request logs: filter by Key or Model; each agent step and tool round trip is its own call. The model that answered, any routing rule or fallback, and the cost are there. To tell agents apart in Request logs and in cost, give each its own key.

Errors

The gateway writes its errors in the format the model speaks; the failed call surfaces as an error with the HTTP status and the gateway's body. Match on the code (x-vidai-error-code, or error.code in the OpenAI body), not the message.

agent.generate throws the AI SDK's own APICallError, which carries the status and the headers:

import { APICallError } from "@ai-sdk/provider";

try {
  await agent.generate("What's the weather in Utrecht?");
} catch (e) {
  const err = APICallError.isInstance(e) ? e : (e as { cause?: unknown })?.cause;
  if (APICallError.isInstance(err)) {
    console.log(err.statusCode, err.responseHeaders?.["x-vidai-error-code"]);
  } else throw e;
}
Status Common gateway codes
401 missing_api_key, invalid_api_key, conflicting_auth_headers
403 api_key_disabled, model_not_allowed, denied_by_routing_rule, content_guardrail_blocked
404 model_not_found, endpoint_not_found
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded
5xx ai_traffic_suspended, fallback_exhausted, upstream_timeout, upstream_unreachable

The full list is in Headers and errors.

Model names

Send the names your organisation has approved, as listed under Models in the Control room (for example gpt-4o-mini, claude-sonnet-4.5, gemini-3.5-flash). GET /v1/models with your key returns exactly the models it may call. See Model names.

What goes through the gateway

Feature Through the gateway
Agents, workflows, streaming, tools, structured output, images (model object, or an AI SDK provider with .chat) Yes, to OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI models
api: "responses" on the model object, or the OpenAI provider's default model OpenAI and Azure OpenAI models only; another provider gets a clear 400
Embeddings (for memory and retrieval) through createOpenAI(...).embedding(...) Yes, to OpenAI and Azure OpenAI embedding models only
"provider/model" strings No: they go to that provider directly

Check it works in a minute

curl -s https://<your-gateway>/v1/chat/completions \
  -H "Authorization: Bearer $VIDAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","max_tokens":5,"messages":[{"role":"user","content":"ping"}]}'

A short answer means the address and key Mastra will use are right. Run your agent once; its calls show in Request logs within seconds.

Good to know

  • The AI SDK underneath retries on its own (twice by default). A fallback chain may already have tried another model before you see an error; lower the retries where you can.
  • The gateway's own 429 has no Retry-After header; back off on your side.
  • Mastra's own model fallbacks (a list of models on the agent) work as usual; the gateway's fallback chains run inside each call, before the first byte.