BroadRouter

Usar agentes Mastra com a BroadNet Inference

Atualizado em

Em um Agent do Mastra, defina model como um objeto com url https://inference.broadnet.ai/v1, apiKey vinda de BROADNET_API_KEY e id broadnet/broadnet/glm-5.3. O Mastra trata a primeira parte do id como nome do provedor e a remove, então o prefixo duplicado envia broadnet/glm-5.3 para a BroadNet. URLs personalizadas usam chat completions por padrão. Para ferramentas, use GLM 5.3 ou Qwen3.8 27B.

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 id como broadnet/broadnet/glm-5.3. Depois confira se url termina em /v1. Modelos pagos exigem uma recarga; o crédito de $5 cobre só broadnet/gemma-4-26b-a4b e os dois modelos Transcribe.
  • 401. BROADNET_API_KEY nã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.

Perguntas frequentes

Por que o Mastra envia glm-5.3 em vez de broadnet/glm-5.3?

O Mastra lê o id do modelo como provedor/modelo e envia só a parte depois da primeira barra. Com id broadnet/glm-5.3, ele enviou glm-5.3 no nosso teste, e a BroadNet não reconhece esse ID. Escreva o id como broadnet/broadnet/glm-5.3.

A url do Mastra é o base URL ou a URL de chat completions?

O base URL. A documentação do Mastra diz para usar o base URL do endpoint compatível com a OpenAI, então use https://inference.broadnet.ai/v1 sem /chat/completions.

O Mastra usa a Responses API com uma URL personalizada?

Não por padrão. A documentação do Mastra diz que endpoints personalizados usam chat completions, a menos que você adicione api definido como responses. Não adicione isso para a BroadNet, que serve chat completions.

As ferramentas do Mastra funcionam na BroadNet?

Sim, em um modelo que a BroadNet lista com ferramentas, GLM 5.3 ou Qwen3.8 27B. No nosso teste com servidor mock, o agente enviou o schema da ferramenta, executou a ferramenta e devolveu o resultado.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity