BroadRouter

Usare gli agenti Mastra con BroadNet Inference

Aggiornato

In un Agent di Mastra imposta model su un oggetto con url https://inference.broadnet.ai/v1, apiKey da BROADNET_API_KEY e id broadnet/broadnet/glm-5.3. Mastra tratta la prima parte dell’id come nome del provider e la rimuove, quindi il doppio prefisso invia broadnet/glm-5.3 a BroadNet. Gli URL personalizzati usano chat completions per default. Per gli strumenti usa GLM 5.3 o Qwen3.8 27B.

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’id come broadnet/broadnet/glm-5.3. Poi controlla che url finisca con /v1. I modelli a pagamento richiedono una ricarica; il credito di $5 copre solo broadnet/gemma-4-26b-a4b e i due modelli Transcribe.
  • 401. BROADNET_API_KEY non è 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.

Domande frequenti

Perché Mastra invia glm-5.3 invece di broadnet/glm-5.3?

Mastra legge l’id del modello come provider/modello e invia solo la parte dopo la prima barra. Con id broadnet/glm-5.3, nel nostro test ha inviato glm-5.3, che BroadNet non riconosce. Scrivi l’id come broadnet/broadnet/glm-5.3.

L’url di Mastra è il base URL o l’URL delle chat completions?

Il base URL. La documentazione di Mastra dice di usare il base URL dell’endpoint compatibile con OpenAI, quindi usa https://inference.broadnet.ai/v1 senza /chat/completions.

Con un URL personalizzato Mastra usa la Responses API?

Non per default. La documentazione di Mastra dice che gli endpoint personalizzati usano chat completions a meno che tu non aggiunga api impostato su responses. Non aggiungerlo per BroadNet, che serve chat completions.

Gli strumenti di Mastra funzionano con BroadNet?

Sì, su un modello per cui BroadNet indica gli strumenti, GLM 5.3 o Qwen3.8 27B. Nel nostro test con il mock l’agente ha inviato lo schema dello strumento, ha eseguito lo strumento e ha restituito il risultato.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity