Managed Agents

Managed Agents runs autonomous agents. An agent works on its own for hours or days, picks up where it stopped after a crash, and runs many sessions in parallel, while you stay in control of what it can reach and do.

You define the agent: its model and instructions, its tools, connectors and skills, its environment, and which tool calls need a person's approval. The Agents SDK (mistralai-agents) drives the model and tool loop and records every step in a session.

Running an agent on your computer is easy. Running it in production also takes:

• durable execution, so a task survives a crash and keeps running after your app exits
• infrastructure to run it, and an environment for each session that needs shell or file access
• secrets for the systems its tools call, kept out of your code
• traces, and a record of every step to audit later

Managed Agents provides all of these. You run the agent in your process while you build, then deploy it with Studio: self-hosted on your servers (agents serve), or Mistral-managed (agents deploy).

For a single model request without an agent loop, use Chat completions. For a process with explicit steps, retries and branching, use Workflows.

Install the SDK, set MISTRAL_API_KEY, then run this file with uv run python main.py:

import asyncio

from mistralai import agents

agent = agents.Agent(model="mistral-large-4")
result = asyncio.run(agent.run("Say hello"))
print(result.text)

import asyncio

from mistralai import agents

agent = agents.Agent(model="mistral-large-4")
result = asyncio.run(agent.run("Say hello"))
print(result.text)

The Quickstart gives the agent a tool and chats with it in your terminal.

An agent is a model and a harness. A session records what the agent does, and the environment is the computer it works on:

The agent can also use your tools, MCP servers and connectors: you list them on the agent, and the harness calls them when the model picks one.

One turn goes like this:

1. You send a message to a session.
2. The harness sends the conversation to the model.
3. The model answers, or picks a tool to call.
4. The harness runs the tool and sends the result to the model. Steps 3 and 4 repeat until the model answers.
5. The answer comes back to you as the turn's result.

Everything that happens is recorded in a session, and the session provides a bidirectional channel. Your systems, applications and users can interact with a session live, or inspect it later.

Here is a payment review agent at a bank. It reads the alert, the account history, the KYC profile, the sanctions lists and the news on its own, then waits for an analyst before it opens a case:

The Suspicious payment review example builds an agent like this one, with the bank's systems faked by tools.

Wherever the agent runs, you get:

• Stateful sessions. The session keeps every message, tool call and result, so a follow-up sees the earlier work.
• Control. You add a message to a running turn or interrupt it, and you choose which tool calls need approval, answered by your code or by a person.
• Environments. With a sandbox hosted by Mistral, each session runs its shell commands in its own container, off your servers.

When you deploy with Studio, self-hosted or Mistral-managed, you also get:

• Durable, background execution. A task can run for days. By default, a session ends after 24 hours, or after 4 hours idle, when no turn runs or the turn only waits for you; you can raise both limits. If the machine running it crashes, the turn continues from its last finished model call or tool call, and your app can exit and come back for the result. Mistral stores the session, so you host no database.
• Approvals that outlive your app. The turn waits for the answer, one hour by default, even while your app is closed.
• Tracing. Each turn is a trace in Mistral Studio, with one span per model call and tool call. It needs no setup.

Deploy the agent in Deploy your agent. Run modes compares the three modes.

Found a problem? Tell us in Feedback.