Mistral LLM Agent in Node.js
MistralAgent answers with Mistral models through Mistral AI’s API. It works with any speech to text and text to speech. It calls the global endpoint, api.mistral.ai. To keep the agent in Europe, use @micdrop/ai-sdk with a Mistral model set to api.eu.mistral.ai, as in this sovereign voice AI setup.
For a comparison of the Mistral Voice Agents SDK, a custom WebSocket client and a Micdrop pipeline, see how to build a Mistral voice agent with Voxtral 3.
Installation
npm install @micdrop/mistralThe same package also provides a speech to text and a text to speech. The providers page shows what every provider covers.
Usage with MicdropServer
import { MistralAgent } from '@micdrop/mistral'import { MicdropServer } from '@micdrop/server'
const agent = new MistralAgent({ apiKey: process.env.MISTRAL_API_KEY || '', model: 'mistral-medium-latest', // Default model systemPrompt: 'You are a helpful assistant', settings: { reasoningEffort: 'none' }, // Optional, the lowest answers soonest})
// Use with MicdropServernew MicdropServer(socket, { agent, // ... other options})Usage without MicdropServer
import { MistralAgent } from '@micdrop/mistral'
const agent = new MistralAgent({ apiKey: process.env.MISTRAL_API_KEY || '', systemPrompt: 'You are a helpful assistant',})
agent.on('Message', (message) => console.log('Message:', message))
agent.addUserMessage('Hello, what can you do?')
// The answer is a text stream, written as the model generates itagent.answer().on('data', (chunk) => process.stdout.write(chunk))Events
| Event | Payload | Description |
|---|---|---|
Message | MicdropConversationItem | A message, a tool call or a tool result was added to the conversation. |
ToolCall | MicdropToolCall | A tool declared with emitOutput ran, with its parameters and output. |
CancelLastUserMessage | none | The last user message was dropped because it carried no intent. |
SkipAnswer | none | The agent stays silent and waits for the user to finish their sentence. |
EndCall | none | The agent decided that the call is over. |
Failed | none | The agent gave up generating an answer after its retries. |
See the Agent interface for the full contract.
Options
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | Required | Your Mistral AI API key |
model | string | 'mistral-medium-latest' | Mistral AI model to use |
systemPrompt | string | Required | System prompt for the agent |
maxRetry | number | 3 | Maximum number of retries on API failures |
retryDelay | number | 500 | Delay in milliseconds between retries |
maxSteps | number | 5 | Maximum number of steps (for tool calls) |
autoEndCall | boolean | string | false | Auto-detect when user wants to end call |
autoSemanticTurn | boolean | string | false | Handle incomplete user sentences |
autoIgnoreUserNoise | boolean | string | false | Filter meaningless user sounds |
extract | ExtractOptions | undefined | Extract a JSON object from responses |
onBeforeAnswer | function | undefined | Hook called before answer generation, returns true to skip it or a text to answer instead |
settings | object | {} | Additional Mistral AI API parameters |
Cancellation and Retries
When the user interrupts, the request to Mistral is aborted and the unfinished answer stays out of the conversation. A request that fails before writing anything is retried up to maxRetry times, retryDelay apart, unless the answer was cancelled meanwhile. A request cut off after part of the answer reached the stream ends there, and the part already spoken is the answer recorded, so no sentence is ever spoken twice.
Available Models
Mistral AI offers several models you can choose from:
mistral-medium-latest- Answers straight away, the default and the one for a voice callmistral-small-latest- Faster and cheaper, also answers straight awaymistral-large-latest- Most capable, but reasons before every answerministral-8b-latest- Small and fast, for simple conversations
Reasoning
A model that reasons thinks before its first word, which delays every answer. MistralAgent leaves the level to the model, and sets it with settings.reasoningEffort.
For a voice call, use Mistral Medium or Mistral Small. They answer without reasoning when nothing is set, in a few hundred milliseconds, and none makes sure of it. Mistral Large 4 always reasons, even at low, its lowest level: it thinks for over a hundred tokens before the first word of a one sentence answer, which a caller hears as a long silence.
const agent = new MistralAgent({ apiKey: process.env.MISTRAL_API_KEY || '', model: 'mistral-medium-latest', systemPrompt: 'You are a helpful assistant', settings: { reasoningEffort: 'none' },})Settings Object
The settings parameter accepts any additional options from the Mistral AI Chat Completions API:
const agent = new MistralAgent({ apiKey: process.env.MISTRAL_API_KEY || '', systemPrompt: 'You are a helpful assistant', settings: { temperature: 0.7, // Controls randomness (0-1) maxTokens: 1000, // Maximum tokens in response topP: 0.9, // Nucleus sampling parameter randomSeed: 42, // For reproducible outputs safePrompt: false, // Enable/disable safety filtering reasoningEffort: 'none', // How long the model reasons before answering },})Advanced Features
The Mistral Agent supports advanced features for improved conversation handling:
- Auto End Call: Automatically detect when users want to end the conversation
- Semantic Turn Detection: Handle incomplete sentences for natural flow
- User Noise Filtering: Filter out meaningless sounds and filler words
- Extract Value from Answer: Extract structured data from responses
- Tools: Add custom tools to the agent
Listing models
MistralAgent.listModels() returns the chat models that call tools, each one once with its aliases.
const models = await MistralAgent.listModels({ apiKey: process.env.MISTRAL_API_KEY || '',})It returns MicdropModel objects: id, the value the model option takes, then when the provider says it name, description, aliases, languages, reasoning for a model that can reason, and deprecated with its shutdownDate. The list is fetched once, then shared by every call of the process for a day. Pass refresh: true to fetch it again.