Quickstart

Start by building an agent that runs in your own Python process: it calls Mistral only for the model, so you can try it before deploying. You can later deploy it with Studio (self-hosted or Mistral-managed): see Run modes. The agents init command below creates a project with a working agent, and a tool is a Python function you add to it. If you prefer to add the SDK to a project you already have, see Manual installation.

• uv: step 1 runs agents init with uv's uvx.
• Permission to create a Mistral API key in your workspace. agents init opens the API keys page of Mistral Studio and writes the key to the project's .env as MISTRAL_API_KEY.

Run agents init to create an agent project in a new folder named after the agent.

uvx --python 3.12 --from mistralai-agents agents init hello-agent
cd hello-agent

uvx --python 3.12 --from mistralai-agents agents init hello-agent
cd hello-agent

Then it asks for your API key: it opens the API keys page of Mistral Studio so you can create one, or takes a key you paste, and writes it to .env. .gitignore keeps .env out of git. Last, it offers to create a git repository and commit the project. Pass --yes to skip the questions: it installs uv if it is missing, commits at once (unless the folder is inside another git repository) and leaves .env empty, so put your key there before step 2.

pyproject.toml pins mistralai-agents to the version that ran init, with its extras. In Python, you import it as from mistralai import agents. The agent is in main.py. It has one tool, get_weather, which returns fixed text:

from mistralai import agents

@agents.tool
async def get_weather(city: str) -> dict[str, str]:
    """Weather for a city."""
    return {"weather": f"sunny in {city}"}

agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Tell us the weather in a city.",
    tools=[get_weather],
)

from mistralai import agents

@agents.tool
async def get_weather(city: str) -> dict[str, str]:
    """Weather for a city."""
    return {"weather": f"sunny in {city}"}

agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Tell us the weather in a city.",
    tools=[get_weather],
)

The model reads the tool's name, its docstring and its typed parameters to decide when to call it. The agents command line looks for agent in main.py. Add the agent's own dependencies with uv add.

Replace main.py with this version. It adds the highlighted lines: import asyncio and a main() function that sends one message and prints the answer:

import asyncio

from mistralai import agents

@agents.tool
async def get_weather(city: str) -> dict[str, str]:
    """Weather for a city."""
    return {"weather": f"sunny in {city}"}

agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Tell us the weather in a city.",
    tools=[get_weather],
)

async def main() -> None:
    result = await agent.run("What's the weather in Paris?")
    print(result.text)

if __name__ == "__main__":
    asyncio.run(main())

import asyncio

from mistralai import agents

@agents.tool
async def get_weather(city: str) -> dict[str, str]:
    """Weather for a city."""
    return {"weather": f"sunny in {city}"}

agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Tell us the weather in a city.",
    tools=[get_weather],
)

async def main() -> None:
    result = await agent.run("What's the weather in Paris?")
    print(result.text)

if __name__ == "__main__":
    asyncio.run(main())

Run it. --env-file .env reads the key that agents init wrote:

uv run --env-file .env python main.py

uv run --env-file .env python main.py

agent.run starts a session, sends the message, and returns the turn's result when the agent has answered. The model called get_weather, then wrote the answer from its result. To send more than one message in the same conversation, see Sessions.

agents chat loads the same main.py and opens a chat in your terminal. To give it your key, run it with uv run --env-file .env, or export MISTRAL_API_KEY in your shell.

uv run --env-file .env agents chat

uv run --env-file .env agents chat

The answer streams as the model writes it, and each tool call shows as it runs. The chat keeps every message, so the agent remembers the conversation. Ctrl+C interrupts a turn; Ctrl+D or /exit ends the chat. To send one message and exit, pass -m.

A tool is a Python function, sync or async, with the @agents.tool decorator. Add a forecast tool to main.py, above the agent, and add it to the agent's tools. Keep get_weather and main():

@agents.tool
async def get_forecast(city: str, days: int) -> list[str]:
    """Weather forecast for a city, one line per day."""
    return [f"day {day}: rain in {city}" for day in range(1, days + 1)]

agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Tell us the weather in a city.",
    tools=[get_weather, get_forecast],
)

@agents.tool
async def get_forecast(city: str, days: int) -> list[str]:
    """Weather forecast for a city, one line per day."""
    return [f"day {day}: rain in {city}" for day in range(1, days + 1)]

agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Tell us the weather in a city.",
    tools=[get_weather, get_forecast],
)

Ask a question that needs the new tool:

uv run --env-file .env agents chat -m "Will it rain in Paris in the next 3 days?"

uv run --env-file .env agents chat -m "Will it rain in Paris in the next 3 days?"

The model filled both parameters from the question, days as an integer. Edit main.py and chat again: this is the fastest loop while you write the agent.

In addition to Before you start, you need Python 3.12, 3.13 or 3.14, the standard build (not the free-threaded 3.14t). The package name is mistralai-agents.

Create a project, add the SDK, and set your key:

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

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

To check that it works, print the SDK's version:

uv run agents --version

uv run agents --version

The SDK's command line is agents, run uv run agents --help to list its commands.

To run shell commands and edit files, an agent needs an environment: see Environment. A project from agents init already installs the sandbox extras: bashkit, sessions-client and koyeb. With uv add, add the extra your sandbox needs, for example uv add "mistralai-agents[koyeb]==1.1.0" for the Mistral sandbox. Creating a Mistral sandbox also needs the cloud_user workspace role, shown as Mistral Cloud User in the console.

Deploy your agent runs the same project on Mistral with agents deploy, and calls it from your app by name.

The agent can also run elsewhere, with the same main.py:

• On your own servers, for example when its tools must run inside your network: Self-hosted (agents serve).
• Each mode side by side: Run modes.

To go further:

• Step through a turn: agent.run returns where the turn stopped: its answer, or the approval it waits for. When a tool call waits for an approval, Step through a session answers it and lets the turn continue.
• Watch and steer a turn: Build a session app shows the turn's events as they come while you send the agent messages.
• See what happened: agents chat prints each tool call and its result as the turn runs. Once the agent is deployed, each turn is also a trace in Mistral Studio, with one span per model call and tool call.
• See a finished project: the Telegram weather bot puts a chat interface in front of the same kind of agent.
• Give the agent more to work with: Tools, Environment and Connectors and MCP.
• Understand the agent: What an agent is.