Install
npm install @mistralai/mistralai@3.5.0 zodMistral's hosted Agents and Conversations APIs from TypeScript with @mistralai/mistralai: agents, conversations, streaming, built-in tools, function calling, handoffs, MCP connectors and error handling.
The Mistral Agents API from TypeScript. The same hosted service as the Python guide — stored, versioned agents; server-side conversation state; built-in web search, code interpreter, image generation and document libraries; MCP connectors; handoffs — called through the official @mistralai/mistralai client.
Install
npm install @mistralai/mistralai@3.5.0 zodVersion
@mistralai/mistralai 3.5.0 · Node.js (active LTS), Bun, Deno or browsers · checked 2026-11-19
Best for
Node services, serverless functions and front-end back ends that want Mistral-hosted agents and state.
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });
const agent = await client.beta.agents.create({ model: "mistral-medium-latest", name: "assistant", instructions: "You are a helpful assistant. Search the web for anything time-sensitive.", tools: [{ type: "web_search" }],});
const response = await client.beta.conversations.start({ agentId: agent.id, inputs: "What is 15 + 27?",});console.log(response.outputs.at(-1));
const followUp = await client.beta.conversations.append({ conversationId: response.conversationId, conversationAppendRequest: { inputs: "Now double it." },});console.log(followUp.outputs.at(-1));The package is ESM-first and the examples use top-level await, so run them as ES modules ("type": "module" in package.json, or .mts files) with "module": "NodeNext" in tsconfig.json. npx tsx file.ts is the quickest way to try one.
agent_id → agentId, handoff_execution → handoffExecution, tool_configuration → toolConfiguration, library_ids → libraryIds. The SDK converts to the wire format for you.append({ conversationId, conversationAppendRequest: { inputs } }), update({ agentId, updateAgentRequest: { ... } }), restart({ conversationId, conversationRestartRequest: { fromEntryId, inputs } }). The compiler catches a flattened body.response.outputs is a union of message.output, tool.execution, function.call and agent.handoff entries; checking entry.type narrows it. Streaming events narrow the same way on event.data.type.SDKValidationError without a network call), and responses are parsed on the way back.The HTTP API is fully covered, but the Python SDK’s agent helpers in mistralai.extra have no TypeScript counterpart:
| Python | TypeScript |
|---|---|
RunContext and conversations.run_async() (schemas from Python functions, automatic tool loop) | Not available. Write the loop yourself; it is about fifteen lines and shown on the tools page. |
Client-side MCP (mistralai.extra.mcp, stdio/SSE servers driven by RunContext) | Not available. Bridge a local server yourself with @modelcontextprotocol/sdk, or register it as a connector. connectors.mcpClient() opens an MCP client to a registered connector through Mistral’s gateway. |
DeferredToolCallsException for human approval | Not available as a helper. Server-side approval for connector tools works through toolConfirmations; for your own functions, your loop decides whether to run them. |
response_format_from_pydantic_model | responseFormatFromZodObject from @mistralai/mistralai/extra/structChat.js, and chat.parse() with a Zod schema. |
Concepts that do not depend on the language — which models to use, how handoff graphs behave, connector security — are covered in more depth in the Python pages: models, orchestration patterns and connectors.
| Date | Version | Changes |
|---|---|---|
| 2026-10-25 | 3.3.0 | Bumped from 3.2.0 (released 2026-10-23; 3.3.0 on 2026-10-25). The only change is a new "max" value for reasoningEffort, noted on the Agents and Conversations page. All 38 TypeScript blocks compile under tsc --strict against 3.3.0, and an agent created with reasoningEffort: "max" was run against a mocked fetch. |
| 2026-10-25 | 3.2.0 | Bumped from 3.1.0 (released 2026-10-20; 3.2.0 on 2026-10-23). All 36 TypeScript blocks compile under tsc --strict against both versions with no errors, and the scripted-conversation test from the Production page passes on 3.2.0. 3.2.0 adds client.responses (stateless Responses API; see the Python guide). |
| 2026-10-25 | 3.5.0 | Re-checked all 37 TypeScript blocks with tsc --strict and ran them against a mock server. Noted that an explicit apiKey (even an empty string) outranks MISTRAL_SA_TOKEN_PATH; replaced the unsupported “Node.js 20+” claim; model IDs in code now come from the shared model roles. |
| 2026-10-21 | 3.5.0 | First TypeScript edition. All examples type-checked with tsc --strict and request shapes validated against the SDK’s Zod schemas. |