O Mastra é um framework TypeScript para agentes e workflows de IA. Além dos provedores nativos, o model de um agente pode ser qualquer endpoint compatível com a OpenAI, passado como um objeto com id e url. A BroadNet Inference serve chat completions padrão em https://inference.broadnet.ai/v1, então funciona assim, com um detalhe no ID do modelo. O BroadRouter é o site da própria BroadNet; este guia segue a documentação de modelos do Mastra e o @mastra/core 1.83.0.
Instalação
npm install @mastra/core zod
export BROADNET_API_KEY='your-broadnet-key'
Conectar um agente
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);
Os comentários no código lembram que o Mastra remove o primeiro segmento do id e que a chamada envia broadnet/glm-5.3.
Por que o prefixo duplicado
A documentação do Mastra diz que um id escrito como provider/model envia ao servidor remoto só o nome do modelo, e que gateway/provider/model mantém o provedor no nome. Os IDs da BroadNet têm uma barra, então precisam da forma mais longa. No nosso teste:
id no Mastra |
ID do modelo que a BroadNet recebeu |
|---|---|
broadnet/glm-5.3 |
glm-5.3 (errado) |
broadnet/broadnet/glm-5.3 |
broadnet/glm-5.3 (certo) |
O helper acima adiciona o segmento extra para você.
Ferramentas
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 ou broadnet/qwen3.8-27b para agentes com ferramentas. A documentação da BroadNet lista ferramentas e saída estruturada só para esses dois modelos.
Streaming
const stream = await assistant.stream("Explain vector search in two sentences.");
for await (const chunk of stream.textStream) process.stdout.write(chunk);
Configurações que importam
urlé o base URL, terminando em/v1. O Mastra adiciona/chat/completions.- Não adicione
api: "responses". A documentação do Mastra diz que isso troca para/v1/responses. A BroadNet não lista a Responses API. - Limite de saída. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e o raciocínio conta para o limite de saída. Se você limitar os tokens de saída, deixe 2.000 ou mais.
Qual modelo escolher
| Agente | Modelo |
|---|---|
| Ferramentas, saída estruturada, workflows | broadnet/glm-5.3 |
| Ferramentas com entrada de imagem ou texto em árabe | broadnet/qwen3.8-27b |
| Etapas só de texto em um plano de preço fixo | broadnet/deepseek-v4.1-flash |
Preços de todos os modelos. Para o Vercel AI SDK sem o Mastra, veja o guia do AI SDK.
Como testamos
Em 2026-11-15 instalamos o @mastra/core 1.83.0 com Node 24 e rodamos generate, stream e um agente com ferramentas contra um servidor mock local que imita o formato de chat completions da BroadNet e devolve chamadas de ferramenta. Lemos as requisições registradas. Todas as chamadas foram para /v1/chat/completions com uma chave Bearer vinda de apiKey. Foi assim que descobrimos a regra do prefixo da tabela acima. Não tínhamos uma chave da BroadNet, então não testamos a saída real dos modelos.
Solução de problemas
- 404 ou modelo não encontrado. Provavelmente o ID do modelo perdeu o prefixo. Escreva o
idcomobroadnet/broadnet/glm-5.3. Depois confira seurltermina em/v1. Modelos pagos exigem uma recarga; o crédito de $5 cobre sóbroadnet/gemma-4-26b-a4be os dois modelos Transcribe. - 401.
BROADNET_API_KEYnão está definida no processo, ou a chave está errada ou ficou sem cota. - Respostas vazias. O raciocínio consumiu o orçamento de saída. Por que as respostas vêm vazias.
- 429 em workflows com etapas paralelas. Uma chave de pagamento por uso permite 30 requisições por minuto e 4 em andamento; uma sessão de plano roda uma de cada vez. Veja erros e novas tentativas.
