Mastra

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

Documentação

Primeiros passos

Texto e chat

Imagem, vídeo e áudio

Ferramentas de API

Agentes e integrações

Ferramentas de código

Ferramentas para agentes

SDKs e frameworks

Pré-requisitos

Crie um projeto Mastra

Crie um agente alimentado pela Venice

Gere uma resposta

Faça streaming de uma resposta

Adicione ferramentas

Gere saída estruturada

Altere os modelos

Solução de problemas

Documentação do Mastra

Modelos Venice

​Pré-requisitos

​Crie um projeto Mastra

​Crie um agente alimentado pela Venice

​Gere uma resposta

​Faça streaming de uma resposta

​Adicione ferramentas

​Gere saída estruturada

​Altere os modelos

​Solução de problemas

Documentação do Mastra

Modelos Venice

Pré-requisitos

Crie um projeto Mastra

Crie um agente alimentado pela Venice

Gere uma resposta

Faça streaming de uma resposta

Adicione ferramentas

Gere saída estruturada

Altere os modelos

Solução de problemas