---
title: "Mastra custom OpenAI-compatible endpoint (model url)"
description: "Run Mastra agents on BroadNet Inference with a model object that sets id, url and apiKey, including the doubled broadnet/ prefix the model ID needs."
url: https://broadrouter.com/guides/mastra-openai-compatible/
lang: en
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

# Use Mastra agents with BroadNet Inference

Updated 2026-11-16

In a Mastra Agent, set model to an object with url https://inference.broadnet.ai/v1, apiKey from BROADNET\_API\_KEY and id broadnet/broadnet/glm-5.3. Mastra treats the first part of the id as a provider name and strips it, so the doubled prefix sends broadnet/glm-5.3 to BroadNet. Custom URLs use chat completions by default. Use GLM 5.3 or Qwen3.8 27B for tools.

Mastra is a TypeScript framework for AI agents and workflows. Besides its built-in providers, an agent’s `model` can be any OpenAI-compatible endpoint, given as an object with `id` and `url`. BroadNet Inference serves standard chat completions at `https://inference.broadnet.ai/v1`, so it works this way, with one catch in the model ID. BroadRouter is BroadNet’s own site; this follows [Mastra’s models docs](https://mastra.ai/models) and @mastra/core 1.83.0.

## Install

```bash
npm install @mastra/core zod
export BROADNET_API_KEY='your-broadnet-key'
```

## Connect an agent

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

const broadnet = (model: string) => ({
  id: `broadnet/${model}`,              // Mastra strips the first segment
  url: "https://inference.broadnet.ai/v1",
  apiKey: process.env.BROADNET_API_KEY,
});

export const assistant = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a concise assistant.",
  model: broadnet("broadnet/glm-5.3"),     // sends broadnet/glm-5.3
});

const res = await assistant.generate("Give me three names for a Go linting tool.");
console.log(res.text);
```

### Why the doubled prefix

Mastra’s docs say an `id` written as `provider/model` sends a bare model name to the remote, and `gateway/provider/model` keeps the provider in the name. BroadNet’s IDs contain a slash, so they need the longer form. In our test:

| Mastra `id` | Model ID BroadNet received |
| --- | --- |
| `broadnet/glm-5.3` | `glm-5.3` (wrong) |
| `broadnet/broadnet/glm-5.3` | `broadnet/glm-5.3` (right) |

The helper above adds the extra segment for you.

## Tools

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

const weather = createTool({
  id: "get_weather",
  description: "Get the weather for a city",
  inputSchema: z.object({ city: z.string() }),
  execute: async (input) => ({ city: input.city, tempC: 21 }),
});

const agent = new Agent({
  id: "weather",
  name: "Weather",
  instructions: "Use the weather tool to answer.",
  tools: { weather },
  model: broadnet("broadnet/glm-5.3"),
});
```

Use `broadnet/glm-5.3` or `broadnet/qwen3.8-27b` for agents with tools. BroadNet’s docs list tools and structured output for these two models only.

## Streaming

```ts
const stream = await assistant.stream("Explain vector search in two sentences.");
for await (const chunk of stream.textStream) process.stdout.write(chunk);
```

## Settings that matter

-   **`url`** is the base URL, ending in `/v1`. Mastra adds `/chat/completions`.
-   **Don’t add `api: "responses"`.** Mastra’s docs say that switches to `/v1/responses`. BroadNet doesn’t list the Responses API.
-   **Output limit.** DeepSeek V4.1 Flash, GLM 5.3 and Qwen3.8 27B reason before answering, and the reasoning counts toward the output limit. If you cap output tokens, leave 2,000 or more.

## Which model to pick

| Agent | Model |
| --- | --- |
| Tools, structured output, workflows | `broadnet/glm-5.3` |
| Tools plus image input or Arabic text | `broadnet/qwen3.8-27b` |
| Text-only steps on a flat-price plan | `broadnet/deepseek-v4.1-flash` |

[Prices for every model](https://broadrouter.com/pricing/). For the Vercel AI SDK without Mastra, see [the AI SDK guide](https://broadrouter.com/guides/vercel-ai-sdk-openai-compatible/).

## How we tested this

On 2026-11-15 we installed @mastra/core 1.83.0 with Node 24 and ran `generate`, `stream` and a tool agent against a local mock server that speaks BroadNet’s chat-completions shape and returns tool calls. We read the logged requests. Every call went to `/v1/chat/completions` with a Bearer key from `apiKey`. That is how we found the prefix rule in the table above. We had no BroadNet key, so we did not test real model output.

## Troubleshooting

-   **404 or model not found.** The model ID probably lost its prefix. Write the `id` as `broadnet/broadnet/glm-5.3`. Then check that `url` ends in `/v1`. Paid models need a top-up; the $5 credit covers only `broadnet/gemma-4-26b-a4b` and the two Transcribe models.
-   **401.** `BROADNET_API_KEY` isn’t set in the process, or the key is wrong or out of allowance.
-   **Empty replies.** Reasoning used the output budget. [Why answers come back empty](https://broadrouter.com/guides/reasoning-tokens-empty-response/).
-   **429 in workflows with parallel steps.** A pay-as-you-go key allows 30 requests a minute and 4 in flight; a plan session runs one at a time. See [errors and retries](https://broadrouter.com/guides/errors-and-retries/).

## Terms in this guide

[Tool calling](https://broadrouter.com/glossary/tool-calling/)

Tool calling, also called function calling, is an LLM API feature in which the model returns a structured request to run a function the developer has defined, with JSON arguments. The application runs the function and sends the result back; the model never runs code itself.

[Pay-as-you-go](https://broadrouter.com/glossary/pay-as-you-go/)

Pay-as-you-go is a pricing model in which you pay only for what you use, metered per unit such as tokens, requests or audio minutes, with no subscription or minimum commitment. Most LLM APIs bill this way, from a prepaid balance or a periodic invoice.

[AI agent](https://broadrouter.com/glossary/agent/)

An AI agent is a system in which a language model directs its own steps toward a goal: it decides which tools to call, reads the results and repeats until it produces a final answer or hits a limit. A fixed script that calls a model at set points is usually called a workflow instead.

[Structured output](https://broadrouter.com/glossary/structured-output/)

Structured output is an LLM API feature that constrains a model's reply to a format the developer specifies, usually a JSON Schema, so code can parse it reliably. It is stricter than JSON mode, which guarantees valid JSON but not a particular shape.

[Token](https://broadrouter.com/glossary/token/)

A token is the unit of text a language model reads and writes: a word, part of a word, a punctuation mark or a byte sequence produced by the model's tokenizer. LLM APIs count, limit and usually bill usage in tokens.

[Base URL](https://broadrouter.com/glossary/base-url/)

A base URL is the fixed root address of an API, such as https://api.example.com/v1, that a client puts in front of every endpoint path, such as /chat/completions. In OpenAI-compatible SDKs, changing the base URL, together with the API key and model ID, points the same code at a different provider.

[Chat Completions API](https://broadrouter.com/glossary/chat-completions-api/)

The Chat Completions API is OpenAI's HTTP endpoint, POST /v1/chat/completions, that takes a model name and a list of role-tagged messages and returns the model's next message. Its request and response shape became the common format that OpenAI-compatible providers and SDKs reuse.

[Concurrency](https://broadrouter.com/glossary/concurrency/)

Concurrency is the number of requests a client has in flight at the same time. LLM APIs often cap it per key or plan, separately from requests per minute, because each open request holds GPU capacity until its response has finished.

## Questions

### Why does Mastra send glm-5.3 instead of broadnet/glm-5.3?

Mastra reads the model id as provider/model and sends only the part after the first slash. With id broadnet/glm-5.3 it sent glm-5.3 in our test, which BroadNet won't recognise. Write the id as broadnet/broadnet/glm-5.3.

### Should the Mastra url be the base URL or the chat completions URL?

The base URL. Mastra's docs say to use the base URL of the OpenAI-compatible endpoint, so use https://inference.broadnet.ai/v1 without /chat/completions.

### Does Mastra use the Responses API with a custom URL?

Not by default. Mastra's docs say custom endpoints use chat completions unless you add api set to responses. Don't add it for BroadNet, which serves chat completions.

### Do Mastra tools work on BroadNet?

Yes, on a model BroadNet lists with tools, GLM 5.3 or Qwen3.8 27B. In our mock test the agent sent the tool schema, ran the tool and returned the result.

## Related guides

-   [Use the Vercel AI SDK with BroadNet Inference](https://broadrouter.com/guides/vercel-ai-sdk-openai-compatible/)
-   [Use the OpenAI Node.js SDK with BroadNet Inference](https://broadrouter.com/guides/openai-node-sdk/)
-   [Why a reasoning model returns an empty answer](https://broadrouter.com/guides/reasoning-tokens-empty-response/)
-   [BroadNet Inference error codes and when to retry](https://broadrouter.com/guides/errors-and-retries/)
-   [All tools that work with BroadNet Inference](https://broadrouter.com/integrations/): SDKs, coding agents, chat UIs and automation tools, with exact settings for each

Try it on your real workload. New accounts start with $5 of credit for Gemma and transcription. DeepSeek, GLM and Qwen3.8 need a top-up.

[Get started](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=guides-mastra-openai-compatible&utm_content=page-cta) ·

**Sources**

-   [Mastra docs, Models (custom OpenAI-compatible endpoints) (checked 2026-11-15)](https://mastra.ai/models)
-   [Mastra on GitHub, @mastra/core 1.83.0 release, 2026-11-13 (checked 2026-11-15)](https://github.com/mastra-ai/mastra/releases/tag/%40mastra%2Fcore%401.83.0)
-   [BroadNet Inference API reference (checked 2026-11-15)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=guides-mastra-openai-compatible&utm_content=sources)
