How to run a first Mistral agents project

A first Mistral agents project runs in your own Python process. It calls Mistral only for the model, so you can try a tool-using agent before any deploy. The agents init command creates a project with a working agent. A tool is a Python function you add to that agent.

What you need

You need uv, because the first step runs agents init with uv's uvx. You also need permission to create a Mistral API key in your workspace. agents init opens the API keys page of Mistral Studio so you can create a key, or takes a key you paste, and writes it to the project's .env as MISTRAL_API_KEY.

Create the project

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

The quickstart shows this output:

✓ Created hello-agent/

pyproject.toml, .python-version, main.py, .gitignore, README.md, Dockerfile

✓ Locked the dependencies in uv.lock

The command then asks for your API key and writes .env. .gitignore keeps .env out of git. Last, it offers to create a git repository and commit the project.

Pass --yes to skip those questions. That mode installs uv if it is missing, commits at once unless the folder is already inside another git repository, and leaves .env empty. Put your key in .env before the next step.

pyproject.toml pins mistralai-agents to the version that ran init, with its extras. That pin is whatever version ran the command; the quickstart does not print a fixed version number for the init path. In Python you import the package as from mistralai import agents. The agents command line looks for agent in main.py. Add the agent's own dependencies with uv add.

What lands in main.py

The generated agent 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],
)

The model reads the tool's name, its docstring, and its typed parameters to decide when to call it.

Run one prompt from Python

Replace main.py with the quickstart's runnable version. The added lines are 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())

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

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

The quickstart's sample output says the weather in Paris is currently sunny. That answer comes from the fixed tool text, not from a live weather service. agent.run starts a session, sends the message, and returns the turn's result when the agent has answered. In that run the model called get_weather, then wrote the answer from the tool result.

Chat from the terminal

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

uv run --env-file .env agents chat

The sample session says it is talking to the agent in this process, and tells you to use Ctrl+D or /exit to quit. Ask about the weather in Paris: the tool call shows as it runs, then the answer streams as the model writes it. The chat keeps every message, so the agent remembers the conversation. Ctrl+C interrupts a turn. To send one message and exit, pass -m.

Add a forecast tool

A tool is a Python function, sync or async, with the @agents.tool decorator. Add get_forecast above the agent, add it to tools, and keep get_weather and main(). The quickstart shows this change:

@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],
)

The new function also returns fixed text: one rain line per requested day. Ask a question that needs it:

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

The quickstart's sample shows the forecast tool running for Paris over three days, then an answer that it will rain in Paris on all of the next 3 days. The model filled both parameters from the question, days as an integer. Edit main.py and chat again: the quickstart calls that the fastest loop while you write the agent.

Install into a project you already have

Manual installation still needs uv and a Mistral API key. It also needs Python 3.12, 3.13, or 3.14, the standard build, not the free-threaded 3.14t build. The package name is mistralai-agents. The documented example pins 1.1.0:

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

Check it:

uv run agents --version

The sample output is mistralai-agents 1.1.0. The command line is agents. Run uv run agents --help to list its commands. This path adds the SDK. It does not create the hello-agent main.py that agents init writes, so use the agent patterns above in that project. The command line still looks for agent in main.py.

A project from agents init already installs the sandbox extras bashkit, sessions-client, and koyeb. The weather tools here do not need a sandbox. If you later add one, the documented Mistral sandbox extra is:

uv add "mistralai-agents[koyeb]==1.1.0"

Creating a Mistral sandbox also needs the cloud_user workspace role, shown as Mistral Cloud User in the console.

If the run cannot see the key

If you see KeyError: 'Required environment variable is not set: MISTRAL_CLIENT_API_KEY', set MISTRAL_API_KEY in .env and pass --env-file .env to uv run, or export MISTRAL_API_KEY. A key exported in your shell takes precedence over .env.

Try this, then read deploy

From hello-agent, run the one-message script, then open terminal chat and ask about the weather in Paris so you can watch the tool call print before the streamed answer. Add get_forecast and repeat the three-day question with -m.

Leave deploy until that local loop works. The quickstart's next page runs the same project on Mistral with agents deploy and calls it from your app by name. The same main.py can also run on your own servers with agents serve when tools must run inside your network. Read that deploy section before you move the process off your machine.

Sources

• Mistral Studio agents quickstart