Mastra

Construa agentes, ferramentas e workflows de IA em TypeScript com o Mastra usando os modelos de chat privados, sem censura e compatíveis com OpenAI da Venice como provedor de LLM.

O Mastra é um framework em TypeScript para construir agentes, ferramentas e workflows de IA. Conecte-o à Venice configurando um endpoint de modelo personalizado compatível com OpenAI.

​

Pré-requisitos

• Node.js 22.18 ou superior
• Uma chave de API da Venice

​

Crie um projeto Mastra

npm

npm create mastra@latest

pnpm create mastra

yarn create mastra

bunx create-mastra

Adicione sua chave de API da Venice ao arquivo .env do projeto gerado:

VENICE_API_KEY=your-venice-api-key

Mantenha o .env fora do controle de versão. Não exponha sua chave de API da Venice em código executado no navegador.

​

Crie um agente alimentado pela Venice

Crie um agente e aponte sua configuração de modelo para a API da Venice:

// src/mastra/agents/venice-agent.ts
import { Agent } from '@mastra/core/agent'

export const veniceAgent = new Agent({
  id: 'venice-agent',
  name: 'Venice Agent',
  instructions: `
    You are a concise, privacy-respecting assistant.
    Give accurate answers and say when you are uncertain.
  `,
  model: {
    id: 'venice/venice-uncensored',
    url: 'https://api.venice.ai/api/v1',
    apiKey: process.env.VENICE_API_KEY,
  },
})

O primeiro segmento do id é o rótulo de roteamento do Mastra. O Mastra envia o restante do ID do modelo, venice-uncensored, para a Venice.

Defina url como a URL base da API mostrada acima. Não acrescente /chat/completions; o Mastra adiciona esse caminho.

Registre o agente na sua instância Mastra:

// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { veniceAgent } from './agents/venice-agent'

export const mastra = new Mastra({
  agents: { veniceAgent },
})

Inicie o servidor de desenvolvimento e abra a URL mostrada no seu terminal para testar o agente no Mastra Studio:

npm run dev

​

Gere uma resposta

Recupere o agente registrado e chame generate():

import { mastra } from './src/mastra/index'

const agent = mastra.getAgentById('venice-agent')
const result = await agent.generate(
  'Explain why zero data retention matters in two sentences.',
)

console.log(result.text)
console.log(result.usage)

​

Faça streaming de uma resposta

Use stream() quando quiser exibir a saída conforme ela chega:

const agent = mastra.getAgentById('venice-agent')
const result = await agent.stream(
  'Write a short poem about private AI inference.',
)

for await (const chunk of result.textStream) {
  process.stdout.write(chunk)
}

​

Adicione ferramentas

As ferramentas do Mastra usam schemas Zod para validar suas entradas e saídas. Use um modelo Venice que suporte function calling ao anexar ferramentas a um agente.

// src/mastra/tools/model-info.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const modelInfoTool = createTool({
  id: 'model-info',
  description: 'Returns a short description of a Venice model',
  inputSchema: z.object({
    model: z.string().describe('A Venice model ID'),
  }),
  outputSchema: z.object({
    description: z.string(),
  }),
  execute: async ({ model }) => {
    const descriptions: Record<string, string> = {
      'venice-uncensored': 'A fast, uncensored general-purpose model.',
      'zai-org-glm-5-1': 'A private model for reasoning and tool use.',
    }

    return {
      description: descriptions[model] ?? `No description found for ${model}.`,
    }
  },
})

Anexe a ferramenta a um agente:

// src/mastra/agents/model-guide-agent.ts
import { Agent } from '@mastra/core/agent'
import { modelInfoTool } from '../tools/model-info'

export const modelGuideAgent = new Agent({
  id: 'model-guide-agent',
  name: 'Venice Model Guide',
  instructions: 'Help users choose a Venice model. Use modelInfoTool when needed.',
  model: {
    id: 'venice/zai-org-glm-5-1',
    url: 'https://api.venice.ai/api/v1',
    apiKey: process.env.VENICE_API_KEY,
  },
  tools: { modelInfoTool },
})

​

Gere saída estruturada

Passe um schema Zod via structuredOutput para receber dados validados:

import { z } from 'zod'

const result = await veniceAgent.generate(
  'Compare private and data-retaining AI inference.',
  {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        privacyBenefits: z.array(z.string()),
        recommendation: z.string(),
      }),
    },
  },
)

console.log(result.object)

Se o modelo selecionado não suportar o modo de saída estruturada da API, defina jsonPromptInjection: true dentro de structuredOutput para que o Mastra adicione o schema ao prompt em vez disso.

​

Altere os modelos

Para usar outro modelo de texto da Venice, mantenha o prefixo de roteamento venice/ e substitua o restante do ID do modelo:

model: {
  id: 'venice/qwen3-5-9b',
  url: 'https://api.venice.ai/api/v1',
  apiKey: process.env.VENICE_API_KEY,
}

Navegue pelos modelos Venice disponíveis e verifique suas capacidades antes de escolher um para tool calling, visão ou saída estruturada.

​

Solução de problemas

A API retorna 401 Unauthorized

Confirme que VENICE_API_KEY está presente no ambiente em que o Mastra é executado e reinicie o servidor de desenvolvimento após alterar o .env.

A API informa que o modelo não existe

Use o ID exato do modelo mostrado na página de modelos. No Mastra, prefixe-o com venice/, por exemplo venice/venice-uncensored.

As requisições retornam 404 Not Found

Defina a URL do modelo como https://api.venice.ai/api/v1. Não use o endpoint completo /chat/completions.

O agente não chama sua ferramenta

Escolha um modelo que suporte function calling, descreva nas instruções quando o agente deve usar a ferramenta e defina a ferramenta com createTool().

Documentação do Mastra

Saiba mais sobre agentes, ferramentas e workflows do Mastra

Modelos Venice

Navegue pelos modelos e capacidades suportadas