@flink-app/mistral-adapter

Mistral AI adapter for the Flink AI framework. Provides integration with Mistral's models via the Chat Completions API using the official @mistralai/mistralai SDK.

Installation

npm install @flink-app/mistral-adapter
# or
pnpm add @flink-app/mistral-adapter

The @mistralai/mistralai package is included as a dependency, so you don't need to install it separately.

Usage

Basic Setup

import { MistralAdapter } from "@flink-app/mistral-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      default: new MistralAdapter({
        apiKey: process.env.MISTRAL_API_KEY!,
        model: "mistral-large-4-0"
      }),
    },
  },
});

await app.start();

Legacy API (still supported):

// Backward-compatible constructor
new MistralAdapter(process.env.MISTRAL_API_KEY!, "mistral-medium-latest")

Agent Instructions

Define your agent's behavior using the instructions property:

// src/agents/support_agent.ts
export const Agent: FlinkAgentProps = {
  name: "support_agent",
  instructions: "You are a helpful customer support agent.",
  tools: ["get_order_status"],
  model: { adapterId: "default" },
};

How it works:

• Instructions are prepended as a system message to every conversation
• Follows Vercel AI SDK pattern for consistency
• Additional system messages in the conversation are passed through as-is

Multiple Adapters

You can register multiple Mistral adapters with different configurations:

const app = new FlinkApp({
  ai: {
    llms: {
      // Frontier model - best for agentic and coding use cases
      default: new MistralAdapter({
        apiKey: process.env.MISTRAL_API_KEY!,
        model: "mistral-medium-latest"
      }),

      // Efficient model - good balance of capability and cost
      fast: new MistralAdapter({
        apiKey: process.env.MISTRAL_API_KEY!,
        model: "mistral-small-latest"
      }),

      // Code completion specialist
      code: new MistralAdapter({
        apiKey: process.env.MISTRAL_API_KEY!,
        model: "codestral-latest"
      }),
    },
  },
});

Reasoning (Mistral Large 4, Medium 3.5, Small 4)

Mistral's current generation are hybrid instruct-and-reasoning models: the same model answers directly or thinks first, controlled per request with reasoning_effort. The adapter exposes this as the reasoningEffort option:

const adapter = new MistralAdapter({
  apiKey: process.env.MISTRAL_API_KEY!,
  model: "mistral-large-4-0",
  reasoningEffort: "high", // "high" | "none" (+ "minimal" | "low" | "medium" | "xhigh" accepted by the API)
});

How thinking flows through Flink:

• Thinking is streamed as reasoning chunks and surfaced by the agent as reasoning_delta events on fullStream. It is never included in textStream or result.message.
• The trace is stored as a thinking content block on the assistant message and replayed to Mistral on later turns and alongside tool calls. Mistral's docs warn that dropping the trace between turns significantly degrades output quality, so this happens automatically.
• Assistant messages that carry no trace are still sent as plain strings, exactly as before.

for await (const event of response.fullStream) {
  if (event.type === "reasoning_delta") process.stderr.write(event.delta); // model's thinking
  if (event.type === "text_delta") process.stdout.write(event.delta);      // answer
}

Tool calling is unchanged: Mistral Large 4 uses the same tools / tool_calls / role: "tool" Chat Completions format as earlier models, including parallel tool calls.

Structured Output and Tool Choice

An agent's model.structuredOutput is sent as responseFormat: { type: "json_schema", jsonSchema: { name, description, schemaDefinition, strict } } (strict defaults to true). The parsed reply is available as result.structured.

model.toolChoice is sent as toolChoice: "auto", "none" and "required" pass through, { type: "tool", name } becomes { type: "function", function: { name } }. Only sent when the request carries tools.

Debug Logging

const adapter = new MistralAdapter({
  apiKey: process.env.MISTRAL_API_KEY!,
  model: "mistral-medium-latest",
  debug: true // Enable debug logging for this adapter
});

When debug: true, the adapter logs full request parameters and tool call decisions made by the LLM.

Supported Models

This adapter works with all Mistral chat models. As of October 2026:

Mistral Large 4 is in public preview on Mistral's API (released 2026-10-06). Pin the explicit mistral-large-4-0 id rather than a -latest alias.

See the Mistral models overview for the full, up-to-date list of model IDs.

Features

• ✅ Full tool calling support - including parallel tool calls in a single response
• ✅ Reasoning - reasoning_effort for hybrid models; thinking streamed as reasoning_delta, kept out of answer text, and replayed across turns
• ✅ Event-based streaming - via the SDK's chat.stream()
• ✅ Multimodal input - text + image content blocks (https URLs and base64 data URLs)
• ✅ Tool call ID normalization - Mistral requires tool call IDs to be exactly 9 alphanumeric characters; IDs from conversation history that originated with another provider are deterministically remapped
• ✅ Token usage tracking - prompt and completion tokens reported per request
• ✅ Schema sanitization - tool input schemas cleaned for Mistral compatibility

API

MistralAdapter

new MistralAdapter(options: MistralAdapterOptions)
new MistralAdapter(apiKey: string, model: string) // legacy

Exports: MistralAdapter, MistralAdapterOptions, MistralReasoningEffort.

Architecture Notes

Flink Integration

The adapter implements Flink's LLMAdapter interface:

• Flink's instructions → prepended as { role: "system" } message
• Flink's messages → converted to Mistral chat messages (system/user/assistant/tool roles)
• Flink's tool schema → converted to Mistral's function format ({ type: "function", function: {...} })
• Streamed deltas → mapped to Flink's LLMStreamChunk events (text, reasoning, tool_call, usage, done)
• Flink's thinking content blocks ↔ Mistral ThinkChunks ({ type: "thinking", thinking: [{ type: "text", text }], signature? })

Each API call is one turn:

• Flink's AgentRunner handles the multi-turn loop (call API → execute tools → call API again)
• Tool results are sent back as { role: "tool", toolCallId, content } messages

ESM-only SDK

The @mistralai/mistralai SDK v2 is ESM-only. This adapter is compiled to CommonJS (like the rest of the Flink ecosystem) and loads the SDK via a dynamic import(), so it works in both CommonJS and ESM applications without configuration.

Temperature

Temperature is only sent to the API when the agent explicitly configured one — Mistral recommends values between 0.0 and 0.7, and the default varies by model.

Requirements

• Node.js >= 18
• @flink-app/flink >= 2.0.0-alpha.125 (for reasoning stream chunks and thinking content blocks)

License

MIT

Resources

• Mistral AI documentation
• Mistral models overview
• Function calling guide
• Reasoning guide (reasoning_effort, thinking chunks)
• Mistral Large 4 announcement