Agent lifecycle

Coming soon

agents serve and agents deploy create an agent in the control plane. agents shutdown is how you remove it.

Deploying replaces, it does not update

Each agents deploy writes a new agent and retires the one that held the name. The agent id changes every time. The name is the stable handle, and it is unique per workspace.

Shutting an agent down

Shutdown releases the name and stops new sessions reaching the agent. What happens to the worker depends on who runs it:

	`agents deploy` (managed)	`agents serve` (self-hosted)
Name released	✓	✓
New sessions	refused	refused
The worker process	deleted by Mistral	keeps running
Sessions already open	can no longer be driven	keep working
Coming back	`agents deploy` again	`agents serve` again

When Mistral created the managed worker, the shutdown deletes it. On the self-hosted side though, your self-hosted worker is a process the control plane never owned and cannot stop — it carries on polling the queue.

agents shutdown hello-agent

agents shutdown hello-agent

Agent hello-agent is shut down. Sessions can no longer reach it.
  Its managed deployment hello-agent was deleted.
  Deploy again to bring the agent back, under a new agent id.

Agent hello-agent is shut down. Sessions can no longer reach it.
  Its managed deployment hello-agent was deleted.
  Deploy again to bring the agent back, under a new agent id.

Agent hello-agent is shut down. Sessions can no longer reach it.
  Its worker on agents-sdk-hello-agent is not managed here and is still running.
  Stop that process yourself. Running `agents serve` again re-registers the name.

Agent hello-agent is shut down. Sessions can no longer reach it.
  Its worker on agents-sdk-hello-agent is not managed here and is still running.
  Stop that process yourself. Running `agents serve` again re-registers the name.

:::warning Shutdown cannot be undone There is no restore. Coming back means deploying or serving again, which creates a new agent with a new id. The CLI confirms before it acts; pass --yes to skip the prompt in a script. :::

Sessions that are already open

Shutdown cancels nothing that is running.

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

On a managed agent the worker is gone. Rather than accept work that can never run, the API refuses further commands on those sessions:

409  Agent session <id> cannot accept commands because agent 'hello-agent' was shut down
     and its deployment was deleted

409  Agent session <id> cannot accept commands because agent 'hello-agent' was shut down
     and its deployment was deleted

Let open sessions finish before you shut a managed agent down.

Freeing a name

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

Cannot serve agent: registration failed at https://api.mistral.ai/v2/agents: the name hello-agent is
already bound to another workflow or deployment

Cannot serve agent: registration failed at https://api.mistral.ai/v2/agents: the name hello-agent is
already bound to another workflow or deployment

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

From the API

The CLI resolves the name to an id, then deletes it. Both calls are available to you:

from mistralai.vibe_agents.agents_client import AgentsClient

async with AgentsClient(base_url=server_url, api_key=api_key) as client:
    agent = await client.get_agent_by_name("hello-agent")
    await client.shutdown_agent(agent.agent_id)

from mistralai.vibe_agents.agents_client import AgentsClient

async with AgentsClient(base_url=server_url, api_key=api_key) as client:
    agent = await client.get_agent_by_name("hello-agent")
    await client.shutdown_agent(agent.agent_id)

Over HTTP, against the control-plane URL serve registers against:

GET    https://api.mistral.ai/v2/agents/agents/by-name/hello-agent   → the agent, with its id
DELETE https://api.mistral.ai/v2/agents/agents/{agent_id}            → 204, or 404 if none is active

GET    https://api.mistral.ai/v2/agents/agents/by-name/hello-agent   → the agent, with its id
DELETE https://api.mistral.ai/v2/agents/agents/{agent_id}            → 204, or 404 if none is active

The repeated /agents is correct: the base URL ends in /v2/agents and the SDK appends its own segment. DELETE covers both kinds of agent, and a second one on the same id answers 404.