Vai al contenuto principale
Mastra è un framework TypeScript per creare agenti AI, tool e workflow. Collegalo a Venice configurando un endpoint modello personalizzato compatibile con OpenAI.

​
Prerequisiti

​
Creare un progetto Mastra

npm create mastra@latest

pnpm create mastra

yarn create mastra

bunx create-mastra
Aggiungi la tua Venice API key al file .env del progetto generato: 
VENICE_API_KEY=your-venice-api-key
Mantieni .env fuori dal controllo di versione. Non esporre la tua Venice API key in codice lato browser.

​
Creare un agente alimentato da Venice

Crea un agente e punta la configurazione del suo modello all’API 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,
  },
})
Il primo segmento di id è l’etichetta di routing di Mastra. Mastra invia il resto dell’ID del modello, venice-uncensored, a Venice.
Imposta url sull’URL base dell’API mostrato sopra. Non aggiungere /chat/completions; Mastra aggiunge quel percorso.
Registra l’agente nella tua istanza Mastra: 
// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { veniceAgent } from './agents/venice-agent'

export const mastra = new Mastra({
  agents: { veniceAgent },
})
Avvia il server di sviluppo e apri l’URL mostrato nel terminale per testare l’agente in Mastra Studio: 
npm run dev

​
Generare una risposta

Recupera l’agente registrato e chiama 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)

​
Streaming di una risposta

Usa stream() quando vuoi visualizzare l’output man mano che arriva: 
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)
}

​
Aggiungere tool

I tool di Mastra usano schemi Zod per validare i loro input e output. Usa un modello Venice che supporti il function calling quando colleghi tool 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}.`,
    }
  },
})
Collega il tool 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 },
})

​
Generare output strutturato

Passa uno schema Zod tramite structuredOutput per ricevere dati validati: 
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 il modello selezionato non supporta la modalità di output strutturato dell’API, imposta jsonPromptInjection: true all’interno di structuredOutput per fare in modo che Mastra aggiunga lo schema al prompt.

​
Cambiare modello

Per usare un altro modello di testo Venice, mantieni il prefisso di routing venice/ e sostituisci il resto dell’ID del modello: 
model: {
  id: 'venice/qwen3-5-9b',
  url: 'https://api.venice.ai/api/v1',
  apiKey: process.env.VENICE_API_KEY,
}
Sfoglia i modelli Venice disponibili e verifica le loro capacità prima di sceglierne uno per tool calling, vision o output strutturato.

​
Risoluzione dei problemi

Verifica che VENICE_API_KEY sia presente nell’ambiente in cui Mastra viene eseguito, poi riavvia il server di sviluppo dopo aver modificato .env.
Usa l’ID modello esatto mostrato nella pagina dei modelli. In Mastra, prefissalo con venice/, ad esempio venice/venice-uncensored.
Imposta l’URL del modello su https://api.venice.ai/api/v1. Non usare l’endpoint completo /chat/completions.
Scegli un modello che supporti il function calling, descrivi nelle istruzioni quando l’agente deve usare il tool e definisci il tool con createTool().

Documentazione Mastra

Scopri di più su agenti, tool e workflow di Mastra

Modelli Venice

Sfoglia i modelli e le capacità supportate