Skip to content

Mistral Agents API

Mistral's hosted Agents and Conversations APIs with built-in tools, MCP connectors, handoffs and FastAPI streaming, using the mistralai Python SDK.

GroupModel-Specific
Current versionPython v3.8.0 / TS v3.5.0
Bonds withPyTs

Mistral’s hosted Agents API. Stored, versioned agents; server-side conversation state; built-in web search, code interpreter, image generation and document retrieval; MCP connectors; and handoffs between agents.

Install

Terminal window
pip install "mistralai[agents]==3.8.0"

Version

Current release: mistralai 3.8.0 · Python 3.10+ · checked 2026-11-19

Best for

Mistral-native assistants with hosted tools and state, MCP-connected agents, EU data residency.

The same API from Node.js, Bun, Deno or the browser with @mistralai/mistralai 3.5.0 (versioned separately from the Python package). It has no RunContext or client-side MCP helpers; the pages show the hand-written equivalents.

import os
from mistralai.client import Mistral # import from mistralai.client, not from mistralai
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = 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"}],
)
response = client.beta.conversations.start(agent_id=agent.id, inputs="What is 15 + 27?")
print(response.outputs[-1].content)
follow_up = client.beta.conversations.append(
conversation_id=response.conversation_id,
inputs="Now double it.",
)
print(follow_up.outputs[-1].content)

Ready? Start Zero → Hero step 1 →


DateVersionChanges
2026-11-053.7.0Bumped from 3.5.0 (3.6.0 and 3.7.0 released since). Added a section on the new beta.webhooks and beta.triggers clients, checked against a httpx2.MockTransport. Existing examples are unaffected: the agents, conversations and libraries modules did not change signature.
2026-10-253.5.0Bumped from 3.4.0 (released 2026-10-23; 3.5.0 on 2026-10-25). The only change is a new "max" value for reasoning_effort; documented it in the overview and the SDK v3 section with an example checked against a httpx2.MockTransport. All 81 Python blocks on these pages parse and their mistralai imports resolve on 3.5.0.
2026-10-253.4.0Bumped from 3.3.0 (released 2026-10-20; 3.4.0 on 2026-10-23). The agents, conversations and libraries modules are unchanged. Added the new stateless client.responses API to the SDK v3 section. Ran every Python block on these pages against a local httpx2.MockTransport on both 3.3.0 and 3.4.0 with identical results, and the scripted-conversation pytest example from the Production page on 3.4.0.
2026-10-253.8.0Third audit, run against a mock HTTP server shaped like the SDK models. Added RunContext behaviour (no turn limit, continue_on_fn_error, run_stream_async needs await), guardrail thresholds, model-card lookups and connector management calls; corrected block_on_error (HTTP 403), NoResponseError (not a MistralError) and the service-account token advice (an explicit api_key outranks the token file); removed unverifiable claims about image-generation billing, prompt caching, the sandbox network and v3 change details; model IDs in code now come from the shared model roles.
2026-10-213.8.0Second pass: corrected OpenTelemetry set-up (opt-in via configure_telemetry), the MCP server transport and the Kubernetes token advice; replaced deprecated agents.list() and connectors.call_tool(); added connector approvals (tool_confirmations), testing, cost and Mistral’s observability APIs; folded the May 2025 history page into the core reference; trimmed the diagrams page and kept one deployment set-up in the production guide.
2026-10-213.8.0Updated for SDK v3 and re-verified every example against the installed package. Rewrote the comprehensive guide as a code reference (diagrams moved to the diagrams page); corrected tool shapes (no config objects, no document_retrieval or mcp tool types), conversation_id usage, and append() (which takes no agent_id); rebuilt the connectors, MCP (connectors, RunContext, mcp 2.x MCPServer) and orchestration guides; replaced retired mistral-medium-2505.
2026-05-272.4.7guardrails and handoff_execution documented.
2026-03-122.0.1SDK v2: imports moved to mistralai.client.
2025-05-27—Agents API launched.