Agent lifecycle

agents serve and agents deploy create an agent on Mistral. agents chat, agents list and agents logs try and operate it. agents shutdown removes it.

agents chat talks to an agent from the terminal. Without a name, it runs the agent of the project you are in, in this process: nothing deployed, nothing registered.

agents chat              # the project's agent, in this process
agents chat hello-agent  # a deployed agent, by name

agents chat              # the project's agent, in this process
agents chat hello-agent  # a deployed agent, by name

The reply streams as the agent writes it, and each tool call is shown as it runs. When the agent sets permission_mode="ask", the chat asks before each call: answer y to allow it once, a to allow it for the rest of the session, or n to deny it. Ctrl+C interrupts the agent's turn and keeps the session open. Ctrl+D or /exit ends the chat.

To send one message and exit, for a script or a quick check, pass -m:

agents chat hello-agent -m "What is the weather in Paris?"

agents chat hello-agent -m "What is the weather in Paris?"

For an agent with client tools, use a session in your application: agents chat refuses a client tool call, and the turn continues without it.

agents list shows your workspace's agents, how each one runs, and whether it is running:

not observed means Mistral saw nothing running the agent: it is stopped, or its status could not be read.

agents logs prints the latest log lines of an agent that agents deploy runs. --follow keeps printing new ones:

agents logs hello-agent --follow

agents logs hello-agent --follow

Lines that end in [platform] come from Mistral's platform as it starts the agent; the others are what the agent's container prints.

A served agent has no logs here: they are in the terminal that runs agents serve. To filter by level, print JSON or add timestamps, see agents logs.

The agent's name is the stable handle, and it is unique per workspace. Each new commit or new configuration that you deploy under that name writes a new agent, with a new id, and retires the one that held the name:

agents serve tells code apart by the code version: AGENTS_SDK_CODE_VERSION when you set it, for example to the commit your image is built from, else a hash of the project.

A turn that is running when you redeploy can fail, or stay Running until a session limit ends it; redeploy when no turn is running.

Shutdown releases the name and stops new sessions reaching the agent. What happens next depends on who hosts it:

Mistral deletes what it hosts. Your agents serve process is yours: Mistral cannot stop it, and it keeps waiting for sessions.

agents shutdown hello-agent

agents shutdown hello-agent

Shutdown cancels nothing that is running.

On a self-hosted agent your agents serve process is still up, so an open session keeps answering until you stop the process.

On a Mistral-managed agent nothing runs it any more. Rather than accept work that can never run, Mistral refuses further messages on those sessions, and the SDK raises agents.SessionTerminatedError:

Let open sessions finish before you shut a Mistral-managed agent down. Deploying the same name again makes those sessions reachable again, on the new code.

Names are unique per workspace, so a serve that fails like this is usually blocked by an agent an earlier agents deploy created:

Shut that agent down, or serve under a free name with --name hello-agent-dev.

• Self-hosted: agents serve and Mistral-managed: agents deploy: the two ways to deploy an agent.
• Session lifecycle and listing: end and list the sessions of an agent.