Run modes

The run mode decides which machine runs your agent's sessions: the agent loop, your tool code and your hooks. You have three options:

Local, in-process: the agent runs inside your program. Each session lives in your process and ends with it.
Self-hosted (agents serve): you run a worker, a long-running process that runs sessions, on your own machine or cluster, and your tool code runs there. Mistral's control plane still stores the sessions and routes each one to a worker, and Mistral serves the model calls.
Mistral-managed (agents deploy): Mistral builds your project from git and runs the worker for you. The sessions behave as when self-hosted, with nothing for you to host.

The agent definition and the session calls are the same in every mode: start_session(), session.run(), turn.result(), turn.steer(), turn.interrupt() and session.cancel().

If you are new to the SDK, or still building the agent, run it locally: there is nothing to set up, and you see each change at once. Deploy it with Studio when a session has to outlive the program that started it: a task that runs for hours, an approval a person answers the next morning, an app that leaves and comes back.

Pick agents serve when your tools must run inside your network, next to your data, or under your own deployment process. Pick agents deploy for everything else in production: the same sessions, with nothing to keep running, at the cost of deploying from a git repository.

Compare the modes

	Local, in-process	Self-hosted	Mistral-managed
Start it with	`agents.Agent(...)` in your code, or `agents chat`	`agents serve`	`agents deploy`
Your app gets the agent with	the `Agent` it builds	`Agent.load_from(agent_name=...)`	`Agent.load_from(agent_name=...)`
What you operate	your program	your program and the `agents serve` process	your program
Your tools run in	your process	your `agents serve` process	Mistral's infrastructure
Where the session is kept	in your process's memory, or on disk with the experimental journal	stored by Mistral	stored by Mistral
Tracing in Mistral Studio	off	on by default, with prompt and completion content	on by default, with prompt and completion content
When the process stops or crashes	the session is gone, unless saved with the experimental journal	the turn usually resumes: see below	the turn usually resumes: see below
Best for	development, tests, scripts	production on infrastructure you control	production with nothing to host

Durability

Deployed, the session is durable: each finished model call and tool call is recorded, and the session outlives the worker. When the worker stops during a turn, the turn usually resumes from its last finished step once a worker is back. It can also fail, or stay Running until its time limit.

Work that was running when the worker stopped has an unknown outcome. A model call is made again. A tool call is not: about a minute later the model gets an error for it, and it may call the tool again. So a tool with side effects can run twice, and must be idempotent: a repeated call with the same input has the same effect as one call. A hook can run again too, so keep hooks idempotent.

A turn runs on a worker. Each finished step goes into the session, which is stored apart from the worker. Here the model asked for the tool refund_order.The worker runs refund_order, and the refund goes through.The worker crashes before it records the tool's result.Another worker picks the turn up from the session. The finished steps are not run again.The tool call that was running is not run again. About 60 seconds later, the model gets an error for it.The model can call the tool again, and the refund goes through twice. Make tools with side effects safe to run twice.Step 1 of 6. A turn runs on a worker. Each finished step goes into the session, which is stored apart from the worker. Here the model asked for the tool refund_order.Rows: the session. The moving square: the step that runs or is recorded.

To make a tool idempotent, send the service it calls an idempotency key derived from the request, such as the order id for a refund. The service recognises a repeated key and returns the first result instead of acting again. Where the service takes no key, first record the key in a store that refuses a second record for it, such as a table with a unique constraint, and act only when your record is new. A plain "was this done?" check is not enough: two calls running at once can both pass it. Anything a tool keeps in the worker's memory, such as a module global or a cache, is lost with the worker.

In your process there is no worker to come back: when the process stops, the session is gone.

Human-in-the-loop. Because the session is durable, it can pause for human input, such as an approval or an answer, and resume when that input arrives, without keeping a process running. Each wait has a time limit, 1 hour by default. See Approval timeout.

Next steps

Local, in-process: run sessions in your process, end local sessions, and keep them after the process exits.
Self-hosted: agents serve: run the agent on your own infrastructure, and check what the CLI loads from your project.
Mistral-managed: agents deploy: deploy to Mistral with your own Dockerfile, secrets, Studio tracing and token usage.
Agent lifecycle: try, operate, update and shut down a deployed agent.
Session lifecycle and listing: end a session, its limits, and list your sessions.