Mastra è un framework TypeScript per agenti e workflow di AI. Oltre ai provider integrati, il model di un agente può essere qualsiasi endpoint compatibile con OpenAI, passato come oggetto con id e url. BroadNet Inference serve chat completions standard su https://inference.broadnet.ai/v1, quindi funziona così, con un’accortezza sull’ID del modello. BroadRouter è il sito di BroadNet; questa guida segue la documentazione dei modelli di Mastra e @mastra/core 1.83.0.
Installazione
npm install @mastra/core zod
export BROADNET_API_KEY='your-broadnet-key'
Collegare un 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);
I commenti nel codice ricordano che Mastra rimuove il primo segmento dell’id e che la chiamata invia broadnet/glm-5.3.
Perché il doppio prefisso
La documentazione di Mastra dice che un id scritto come provider/model invia al server remoto il solo nome del modello, mentre gateway/provider/model mantiene il provider nel nome. Gli ID di BroadNet contengono una barra, quindi serve la forma più lunga. Nel nostro test:
id in Mastra |
ID del modello ricevuto da BroadNet |
|---|---|
broadnet/glm-5.3 |
glm-5.3 (sbagliato) |
broadnet/broadnet/glm-5.3 |
broadnet/glm-5.3 (corretto) |
L’helper qui sopra aggiunge il segmento in più al posto tuo.
Strumenti
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"),
});
Per gli agenti con strumenti usa broadnet/glm-5.3 o broadnet/qwen3.8-27b. La documentazione di BroadNet indica strumenti e output strutturato solo per questi due modelli.
Streaming
const stream = await assistant.stream("Explain vector search in two sentences.");
for await (const chunk of stream.textStream) process.stdout.write(chunk);
Impostazioni che contano
urlè il base URL e finisce con/v1. Mastra aggiunge/chat/completions.- Non aggiungere
api: "responses". La documentazione di Mastra dice che fa passare a/v1/responses. BroadNet non elenca la Responses API. - Limite di output. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta nel limite di output. Se limiti i token di output, lasciane 2.000 o più.
Quale modello scegliere
| Agente | Modello |
|---|---|
| Strumenti, output strutturato, workflow | broadnet/glm-5.3 |
| Strumenti più input di immagini o testo in arabo | broadnet/qwen3.8-27b |
| Passaggi solo testo su un piano a prezzo fisso | broadnet/deepseek-v4.1-flash |
Prezzi di tutti i modelli. Per il Vercel AI SDK senza Mastra, vedi la guida all’AI SDK.
Come l’abbiamo testato
Il 2026-11-15 abbiamo installato @mastra/core 1.83.0 con Node 24 ed eseguito generate, stream e un agente con strumenti contro un mock server locale che riproduce il formato chat completions di BroadNet e restituisce chiamate agli strumenti. Abbiamo letto le richieste registrate. Ogni chiamata è arrivata a /v1/chat/completions con una chiave Bearer presa da apiKey. È così che abbiamo trovato la regola del prefisso riportata nella tabella sopra. Non avevamo una chiave BroadNet, quindi non abbiamo testato l’output reale dei modelli.
Risoluzione dei problemi
- 404 o modello non trovato. Probabilmente l’ID del modello ha perso il prefisso. Scrivi l’
idcomebroadnet/broadnet/glm-5.3. Poi controlla cheurlfinisca con/v1. I modelli a pagamento richiedono una ricarica; il credito di $5 copre solobroadnet/gemma-4-26b-a4be i due modelli Transcribe. - 401.
BROADNET_API_KEYnon è impostata nel processo, oppure la chiave è sbagliata o ha esaurito la quota. - Risposte vuote. Il ragionamento ha consumato il budget di output. Perché le risposte arrivano vuote.
- 429 nei workflow con passaggi paralleli. Una chiave a consumo consente 30 richieste al minuto e 4 in corso contemporaneamente; una sessione di un piano ne esegue una alla volta. Vedi errori e retry.
