> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration Mastra

> Construisez des agents, des outils et des workflows TypeScript avec Mastra en utilisant les modèles privés et compatibles OpenAI de Venice.

[Mastra](https://mastra.ai/) est un framework TypeScript pour construire des agents, des outils et des workflows IA. Connectez-le à Venice en configurant un endpoint de modèle personnalisé compatible OpenAI.

## Prérequis

* Node.js 22.18 ou version ultérieure
* Une [clé API Venice](/guides/getting-started/generating-api-key)

## Créer un projet Mastra

<CodeGroup>
  ```bash npm theme={"system"}
  npm create mastra@latest
  ```

  ```bash pnpm theme={"system"}
  pnpm create mastra
  ```

  ```bash yarn theme={"system"}
  yarn create mastra
  ```

  ```bash bun theme={"system"}
  bunx create-mastra
  ```
</CodeGroup>

Ajoutez votre clé API Venice au fichier `.env` du projet généré :

```bash theme={"system"}
VENICE_API_KEY=your-venice-api-key
```

<Warning>
  Ne versionnez pas `.env` dans le gestionnaire de sources. N'exposez pas votre clé API Venice dans du code côté navigateur.
</Warning>

## Créer un agent propulsé par Venice

Créez un agent et pointez sa configuration de modèle vers l'API Venice :

```typescript theme={"system"}
// 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,
  },
})
```

Le premier segment de `id` est le libellé de routage de Mastra. Mastra envoie le reste de l'identifiant de modèle, `venice-uncensored`, à Venice.

<Note>
  Définissez `url` sur l'URL de base de l'API indiquée ci-dessus. N'y ajoutez pas `/chat/completions` ; Mastra ajoute ce chemin.
</Note>

Enregistrez l'agent dans votre instance Mastra :

```typescript theme={"system"}
// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { veniceAgent } from './agents/venice-agent'

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

Démarrez le serveur de développement et ouvrez l'URL affichée dans votre terminal pour tester l'agent dans Mastra Studio :

```bash theme={"system"}
npm run dev
```

## Générer une réponse

Récupérez l'agent enregistré et appelez `generate()` :

```typescript theme={"system"}
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)
```

## Streamer une réponse

Utilisez `stream()` lorsque vous souhaitez afficher la sortie au fur et à mesure de son arrivée :

```typescript theme={"system"}
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)
}
```

## Ajouter des outils

Les outils Mastra utilisent des schémas Zod pour valider leurs entrées et sorties. Utilisez un modèle Venice qui prend en charge le function calling lorsque vous attachez des outils à un agent.

```typescript theme={"system"}
// 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}.`,
    }
  },
})
```

Attachez l'outil à un agent :

```typescript theme={"system"}
// 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 },
})
```

## Générer une sortie structurée

Passez un schéma Zod via `structuredOutput` pour recevoir des données validées :

```typescript theme={"system"}
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 le modèle sélectionné ne prend pas en charge le mode de sortie structurée de l'API, définissez `jsonPromptInjection: true` dans `structuredOutput` pour que Mastra ajoute le schéma au prompt à la place.

## Changer de modèle

Pour utiliser un autre modèle de texte Venice, conservez le préfixe de routage `venice/` et remplacez le reste de l'identifiant de modèle :

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

Parcourez les [modèles Venice disponibles](/models/overview) et vérifiez leurs capacités avant d'en choisir un pour le tool calling, la vision ou la sortie structurée.

## Dépannage

<AccordionGroup>
  <Accordion title="L'API renvoie 401 Unauthorized">
    Vérifiez que `VENICE_API_KEY` est présente dans l'environnement où Mastra s'exécute, puis redémarrez le serveur de développement après avoir modifié `.env`.
  </Accordion>

  <Accordion title="L'API indique que le modèle n'existe pas">
    Utilisez l'identifiant de modèle exact affiché sur la [page des modèles](/models/overview). Dans Mastra, préfixez-le avec `venice/`, par exemple `venice/venice-uncensored`.
  </Accordion>

  <Accordion title="Les requêtes renvoient 404 Not Found">
    Définissez l'URL du modèle sur `https://api.venice.ai/api/v1`. N'utilisez pas l'endpoint complet `/chat/completions`.
  </Accordion>

  <Accordion title="L'agent n'appelle pas son outil">
    Choisissez un modèle qui prend en charge le function calling, décrivez dans ses instructions quand l'agent doit utiliser l'outil, et définissez l'outil avec `createTool()`.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Documentation Mastra" icon="book" href="https://mastra.ai/docs">
    En savoir plus sur les agents, les outils et les workflows Mastra
  </Card>

  <Card title="Modèles Venice" icon="database" href="/models/overview">
    Parcourir les modèles et les capacités prises en charge
  </Card>
</CardGroup>