---
title: "Mastra: endpoint custom compatibile OpenAI (url) | BroadRouter"
description: "Esegui agenti Mastra su BroadNet Inference con un oggetto model che imposta id, url e apiKey, compreso il doppio prefisso broadnet/ richiesto dall’ID del modello."
url: https://broadrouter.com/it/guides/mastra-openai-compatible/
lang: it
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/guides/mastra-openai-compatible/) (aggiornato il 2026-11-16).

# Usare gli agenti Mastra con BroadNet Inference

Aggiornato 2026-11-16

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](https://mastra.ai/models) e @mastra/core 1.83.0.

## Installazione

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

## Collegare un agente

```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);
```

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

```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"),
});
```

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

```ts
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](https://broadrouter.com/it/pricing/). Per il Vercel AI SDK senza Mastra, vedi [la guida all’AI SDK](https://broadrouter.com/it/guides/vercel-ai-sdk-openai-compatible/).

## 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](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/).
-   **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](https://broadrouter.com/it/guides/errors-and-retries/).

## Termini in questa guida

[Tool calling (chiamata di strumenti)](https://broadrouter.com/it/glossary/tool-calling/)

Il tool calling, detto anche function calling, è una funzionalità delle API LLM in cui il modello restituisce una richiesta strutturata di eseguire una funzione definita dallo sviluppatore, con argomenti JSON. L’applicazione esegue la funzione e rimanda il risultato; il modello non esegue mai codice da solo.

[Pagamento a consumo (pay-as-you-go)](https://broadrouter.com/it/glossary/pay-as-you-go/)

Il pagamento a consumo è un modello di prezzo in cui paghi solo ciò che usi, misurato per unità come token, richieste o minuti di audio, senza abbonamento né impegno minimo. La maggior parte delle API LLM fattura così, da un saldo prepagato o con una fattura periodica.

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

La base URL è l’indirizzo radice fisso di un’API, come https://api.example.com/v1, che un client antepone a ogni percorso di endpoint, come /chat/completions. Negli SDK compatibili con OpenAI, cambiare la base URL, insieme alla chiave API e all’ID del modello, punta lo stesso codice verso un altro provider.

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

La Chat Completions API è l’endpoint HTTP di OpenAI, POST /v1/chat/completions, che riceve il nome di un modello e una lista di messaggi con un ruolo e restituisce il messaggio successivo del modello. La forma della sua richiesta e risposta è diventata il formato comune che riusano provider e SDK compatibili con OpenAI.

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

La concorrenza è il numero di richieste che un client ha in corso nello stesso momento. Le API LLM spesso la limitano per chiave o per piano, separatamente dalle richieste al minuto, perché ogni richiesta aperta occupa capacità GPU finché la sua risposta non è terminata.

[Output strutturato (structured output)](https://broadrouter.com/it/glossary/structured-output/)

L’output strutturato è una funzionalità delle API LLM che vincola la risposta di un modello a un formato indicato dallo sviluppatore, di solito un JSON Schema, così il codice può interpretarla in modo affidabile. È più rigoroso della JSON mode, che garantisce un JSON valido ma non una struttura precisa.

[Rate limit (limite di frequenza)](https://broadrouter.com/it/glossary/rate-limit/)

Un rate limit è un tetto che un’API pone a quanto un client può usarla in un intervallo di tempo, per esempio richieste al minuto o token al minuto. Le richieste oltre il limite vengono rifiutate, di solito con HTTP 429 Too Many Requests, finché l’uso non torna sotto la soglia.

[Streaming](https://broadrouter.com/it/glossary/streaming/)

Lo streaming è un modo di restituire la risposta di un modello linguistico in piccoli pezzi mentre viene ancora generata, invece che in un’unica risposta alla fine. Le API compatibili con OpenAI trasmettono in streaming tramite server-sent event quando la richiesta imposta stream a true.

## 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.

## Guide correlate

-   [Usare il Vercel AI SDK con BroadNet Inference](https://broadrouter.com/it/guides/vercel-ai-sdk-openai-compatible/)
-   [Usare l’SDK Node.js di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-node-sdk/)
-   [Perché un modello di ragionamento restituisce una risposta vuota](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/)
-   [Codici di errore di BroadNet Inference e quando ritentare](https://broadrouter.com/it/guides/errors-and-retries/)
-   [Tutti gli strumenti che funzionano con BroadNet Inference (in inglese)](https://broadrouter.com/integrations/): SDK, agenti di coding, interfacce di chat e strumenti di automazione, con le impostazioni esatte per ciascuno

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

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

**Fonti**

-   [Documentazione di Mastra, Models (endpoint personalizzati compatibili con OpenAI) (verificata il 2026-11-15)](https://mastra.ai/models)
-   [Mastra su GitHub, release di @mastra/core 1.83.0, 2026-11-13 (verificato il 2026-11-15)](https://github.com/mastra-ai/mastra/releases/tag/%40mastra%2Fcore%401.83.0)
-   [Riferimento API di BroadNet Inference (verificato il 2026-11-15) (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-mastra-openai-compatible&utm_content=sources)
