Skip to content
MiTs

Mistral Agents API (TypeScript)

Mistral'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

Terminal window
npm install @mistralai/mistralai@3.5.0 zod

Version

@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.

  • Same API, camelCase names. Every Python keyword argument has a camelCase property: agent_id → agentId, handoff_execution → handoffExecution, tool_configuration → toolConfiguration, library_ids → libraryIds. The SDK converts to the wire format for you.
  • One request object per call. Methods take a single object. Where an endpoint has both a path parameter and a body, the body is nested: append({ conversationId, conversationAppendRequest: { inputs } }), update({ agentId, updateAgentRequest: { ... } }), restart({ conversationId, conversationRestartRequest: { fromEntryId, inputs } }). The compiler catches a flattened body.
  • Typed unions you can narrow. 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.
  • Validated at runtime. Requests are parsed with the SDK’s Zod schemas before they are sent (a bad request throws SDKValidationError without a network call), and responses are parsed on the way back.
  • Everything returns a promise. There are no separate async twins and no context manager; streams are async iterables.

The HTTP API is fully covered, but the Python SDK’s agent helpers in mistralai.extra have no TypeScript counterpart:

PythonTypeScript
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 approvalNot 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_modelresponseFormatFromZodObject 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.


DateVersionChanges
2026-10-253.3.0Bumped 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-253.2.0Bumped 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-253.5.0Re-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-213.5.0First TypeScript edition. All examples type-checked with tsc --strict and request shapes validated against the SDK’s Zod schemas.