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/v1and translates for Anthropic, Gemini and Vertex AI models. - A model from an AI SDK provider (
createOpenAI,createAnthropic,createGoogleGenerativeAIwith abaseURL): 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-Afterheader; 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.