---
title: "Mastra: endpoint compatível com a OpenAI (url) | BroadRouter"
description: "Rode agentes Mastra na BroadNet Inference com um objeto model que define id, url e apiKey, incluindo o prefixo broadnet/ duplicado que o ID do modelo exige."
url: https://broadrouter.com/pt/guides/mastra-openai-compatible/
lang: pt-BR
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/guides/mastra-openai-compatible/) (atualizado em 2026-11-16).

# Usar agentes Mastra com a BroadNet Inference

Atualizado em 2026-11-16

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

## Instalação

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

## Conectar um 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);
```

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

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

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

```ts
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](https://broadrouter.com/pt/pricing/). Para o Vercel AI SDK sem o Mastra, veja [o guia do AI SDK](https://broadrouter.com/pt/guides/vercel-ai-sdk-openai-compatible/).

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

## Termos neste guia

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

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

A base URL é o endereço raiz fixo de uma API, como https://api.example.com/v1, que um cliente coloca antes de cada caminho de endpoint, como /chat/completions. Nos SDKs compatíveis com a OpenAI, trocar a base URL, junto com a chave de API e o ID do modelo, aponta o mesmo código para outro provedor.

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

A Chat Completions API é o endpoint HTTP da OpenAI, POST /v1/chat/completions, que recebe o nome de um modelo e uma lista de mensagens marcadas com papéis e devolve a próxima mensagem do modelo. O formato da requisição e da resposta virou o padrão comum que provedores e SDKs compatíveis com a OpenAI reutilizam.

[Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/)

Concorrência é o número de requisições que um cliente tem em andamento ao mesmo tempo. APIs de LLM muitas vezes a limitam por chave ou por plano, separadamente das requisições por minuto, porque cada requisição aberta ocupa capacidade de GPU até a resposta terminar.

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Saída estruturada (structured output)](https://broadrouter.com/pt/glossary/structured-output/)

Saída estruturada é um recurso de APIs de LLM que restringe a resposta de um modelo a um formato definido pelo desenvolvedor, normalmente um JSON Schema, para que o código consiga interpretá-la de forma confiável. É mais rigorosa que o JSON mode, que garante um JSON válido, mas não uma estrutura específica.

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

## Guias relacionados

-   [Como usar o Vercel AI SDK com a BroadNet Inference](https://broadrouter.com/pt/guides/vercel-ai-sdk-openai-compatible/)
-   [Como usar o SDK Node.js da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-node-sdk/)
-   [Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Códigos de erro da BroadNet Inference e quando tentar de novo](https://broadrouter.com/pt/guides/errors-and-retries/)
-   [Todas as ferramentas que funcionam com a BroadNet Inference (em inglês)](https://broadrouter.com/integrations/): SDKs, agentes de programação, interfaces de chat e ferramentas de automação, com as configurações exatas de cada uma

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

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

**Fontes**

-   [Documentação do Mastra, Models (endpoints personalizados compatíveis com a OpenAI) (conferido em 2026-11-15)](https://mastra.ai/models)
-   [Mastra no GitHub, release do @mastra/core 1.83.0, 2026-11-13 (conferido em 2026-11-15)](https://github.com/mastra-ai/mastra/releases/tag/%40mastra%2Fcore%401.83.0)
-   [Referência da API da BroadNet Inference (conferido em 2026-11-15) (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-mastra-openai-compatible&utm_content=sources)
