Saltar al contenido principal
Mastra es un framework de TypeScript para construir agentes de IA, herramientas y flujos de trabajo. Conéctalo a Venice configurando un endpoint de modelo personalizado compatible con OpenAI.

​
Requisitos previos

​
Crear un proyecto de Mastra

npm create mastra@latest

pnpm create mastra

yarn create mastra

bunx create-mastra
Agrega tu clave de API de Venice al archivo .env del proyecto generado: 
VENICE_API_KEY=your-venice-api-key
Mantén .env fuera del control de versiones. No expongas tu clave de API de Venice en código del lado del navegador.

​
Crear un agente impulsado por Venice

Crea un agente y apunta la configuración de su modelo a la API de 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,
  },
})
El primer segmento de id es la etiqueta de enrutamiento de Mastra. Mastra envía el ID de modelo restante, venice-uncensored, a Venice.
Configura url con la URL base de la API mostrada arriba. No agregues /chat/completions; Mastra añade esa ruta.
Registra el agente en tu instancia de Mastra: 
// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { veniceAgent } from './agents/venice-agent'

export const mastra = new Mastra({
  agents: { veniceAgent },
})
Inicia el servidor de desarrollo y abre la URL que se muestra en tu terminal para probar el agente en Mastra Studio: 
npm run dev

​
Generar una respuesta

Obtén el agente registrado y llama a 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)

​
Transmitir una respuesta

Usa stream() cuando quieras mostrar la salida a medida que llega: 
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)
}

​
Agregar herramientas

Las herramientas de Mastra usan esquemas de Zod para validar sus entradas y salidas. Usa un modelo de Venice que admita function calling al adjuntar herramientas a un 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}.`,
    }
  },
})
Adjunta la herramienta a un 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 },
})

​
Generar salida estructurada

Pasa un esquema de Zod a través de structuredOutput para recibir datos 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)
Si el modelo seleccionado no admite el modo de salida estructurada de la API, configura jsonPromptInjection: true dentro de structuredOutput para que Mastra agregue el esquema al prompt en su lugar.

​
Cambiar de modelo

Para usar otro modelo de texto de Venice, mantén el prefijo de enrutamiento venice/ y reemplaza el ID de modelo restante: 
model: {
  id: 'venice/qwen3-5-9b',
  url: 'https://api.venice.ai/api/v1',
  apiKey: process.env.VENICE_API_KEY,
}
Explora los modelos de Venice disponibles y revisa sus capacidades antes de seleccionar uno para tool calling, visión o salida estructurada.

​
Solución de problemas

Confirma que VENICE_API_KEY esté presente en el entorno donde se ejecuta Mastra y luego reinicia el servidor de desarrollo después de cambiar .env.
Usa el ID de modelo exacto que se muestra en la página de modelos. En Mastra, agrégale el prefijo venice/, por ejemplo venice/venice-uncensored.
Configura la URL del modelo como https://api.venice.ai/api/v1. No uses el endpoint completo /chat/completions.
Elige un modelo que admita function calling, describe en las instrucciones cuándo debe usar la herramienta el agente, y define la herramienta con createTool().

Documentación de Mastra

Aprende más sobre los agentes, herramientas y flujos de trabajo de Mastra

Modelos de Venice

Explora los modelos y sus capacidades admitidas