Installation

You need Python 3.12, 3.13 or 3.14, uv, and a MISTRAL_API_KEY. Serving an agent from a worker also needs workflows enabled on that key - see Run modes.

uv init --python 3.12 my_agent && cd my_agent
uv add mistralai-agents
export MISTRAL_API_KEY="<your-key>"

uv init --python 3.12 my_agent && cd my_agent
uv add mistralai-agents
export MISTRAL_API_KEY="<your-key>"

uv run agents --help

uv run agents --help

Head to the Quickstart from here.

uv add follows the newest release candidate. Write the pyproject.toml below instead if you want the version and extras fixed:

# pyproject.toml - replaces the file uv init generated
[project]
name = "my_agent"
version = "0.0.0"
requires-python = ">=3.12"
dependencies = ["mistralai-agents[bashkit,sessions-client]==1.1.0rc4"]

[tool.uv]
# A release candidate is a prerelease, so it is opt-in. Setting it here rather than passing
# --prerelease=allow keeps `uv run` from re-resolving the lockfile on every command.
prerelease = "allow"

# pyproject.toml - replaces the file uv init generated
[project]
name = "my_agent"
version = "0.0.0"
requires-python = ">=3.12"
dependencies = ["mistralai-agents[bashkit,sessions-client]==1.1.0rc4"]

[tool.uv]
# A release candidate is a prerelease, so it is opt-in. Setting it here rather than passing
# --prerelease=allow keeps `uv run` from re-resolving the lockfile on every command.
prerelease = "allow"

uv sync

uv sync

Everything above works with no extras.

uv add "mistralai-agents[bashkit]"

uv add "mistralai-agents[bashkit]"

403 on the wheel metadata, when your default index is a mirror

1.1.0rc4 and the mistralai-vibe-harness it pins were published on the same day. A proxying index that has not ingested them yet answers 403, and uv stops:

error: Failed to fetch: `https://<mirror>/pypi/packages/.../mistralai_agents-1.1.0rc4-py3-none-any.whl.metadata`
  Caused by: HTTP status client error (403 Forbidden)

error: Failed to fetch: `https://<mirror>/pypi/packages/.../mistralai_agents-1.1.0rc4-py3-none-any.whl.metadata`
  Caused by: HTTP status client error (403 Forbidden)

Point the project at public PyPI:

# pyproject.toml
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
default = true

# pyproject.toml
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
default = true

That is enough on a clean machine, but not if UV_DEFAULT_INDEX is exported - an environment variable beats pyproject.toml. [tool.uv.sources] does not rescue it either: sources apply only to your project's own dependencies, and mistralai-vibe-harness is transitive. Install with an inline override instead:

UV_DEFAULT_INDEX=https://pypi.org/simple uv sync

UV_DEFAULT_INDEX=https://pypi.org/simple uv sync

Then use uv run --frozen ... from there on. A plain uv run re-resolves and hits the same 403 even once the venv is correct.

The release is filtered out by an exclude-newer policy

1.1.0rc4 was published 2026-09-21 and pins mistralai-vibe-harness 0.1.4 from the same window, so a cutoff older than that filters both out. Exempt the two packages:

# pyproject.toml
[tool.uv]
# Drop this once your cutoff has moved past 2026-09-22.
exclude-newer-package = { mistralai-agents = false, mistralai-vibe-harness = false }

# pyproject.toml
[tool.uv]
# Drop this once your cutoff has moved past 2026-09-22.
exclude-newer-package = { mistralai-agents = false, mistralai-vibe-harness = false }

Unsetting UV_EXCLUDE_NEWER is not enough on its own, because exclude-newer is usually also set in ~/.config/uv/uv.toml, and that keeps applying. The exclude-newer-package block is what actually works; uv sync --no-config is the escape hatch if you want to ignore your user config wholesale.

Something wrong?

If something does not work as expected, report it on the platform-docs GitHub repository.

Going further