Install
pip install "mistralai[agents]==3.8.0"Mistral's hosted Agents and Conversations APIs with built-in tools, MCP connectors, handoffs and FastAPI streaming, using the mistralai Python SDK.
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
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 osfrom 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 →
| Date | Version | Changes |
|---|---|---|
| 2026-11-05 | 3.7.0 | Bumped 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-25 | 3.5.0 | Bumped 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-25 | 3.4.0 | Bumped 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-25 | 3.8.0 | Third 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-21 | 3.8.0 | Second 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-21 | 3.8.0 | Updated 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-27 | 2.4.7 | guardrails and handoff_execution documented. |
| 2026-03-12 | 2.0.1 | SDK v2: imports moved to mistralai.client. |
| 2025-05-27 | — | Agents API launched. |