Guide de démarrage

Un agent s'exécute dans votre propre processus Python : seuls ses appels au modèle sont envoyés à Mistral. Il répond donc avant tout déploiement. agents init crée un projet avec un agent fonctionnel. Un outil est une fonction Python que vous ajoutez à cet agent. Comptez environ cinq minutes.

• uv : l'étape 1 exécute agents init avec uvx, fourni par uv.
• Une clé API Mistral, disponible sur la page Clés API de Mistral Studio. agents init l'enregistre dans le fichier .env du projet sous le nom MISTRAL_API_KEY.

agents init crée un projet d'agent dans un nouveau dossier portant le nom de l'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

✓ Created hello-agent/
  pyproject.toml, .python-version, main.py, .gitignore, README.md, Dockerfile
✓ Locked the dependencies in uv.lock

✓ Created hello-agent/
  pyproject.toml, .python-version, main.py, .gitignore, README.md, Dockerfile
✓ Locked the dependencies in uv.lock

La commande vous demande ensuite votre clé API : elle ouvre la page des clés API de Mistral Studio pour vous permettre d'en créer une, ou accepte une clé que vous collez, puis l'enregistre dans .env. .gitignore exclut .env de git. Enfin, elle propose de créer un dépôt git et d'y enregistrer le projet dans un commit. Ajoutez --yes pour ignorer les questions : la commande installe uv s'il est absent, crée immédiatement un commit (sauf si le dossier se trouve dans un autre dépôt git) et laisse .env vide. Ajoutez donc votre clé dans ce fichier avant l'étape 2.

pyproject.toml fixe la version de mistralai-agents à celle qui a exécuté init, avec ses extras. L'agent se trouve dans main.py. Il dispose d'un outil, get_weather, qui renvoie un texte fixe :

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

Le modèle lit le nom de l'outil, sa docstring et ses paramètres typés pour décider quand l'appeler. La commande agents recherche agent dans main.py. Ajoutez les dépendances propres à l'agent avec uv add.

Remplacez main.py par cette version. Elle ajoute les lignes mises en évidence : import asyncio et une fonction main() qui envoie un message et affiche la réponse :

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())

Exécutez le programme. --env-file .env lit la clé enregistrée par agents init :

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

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

The weather in **Paris** is currently **sunny** ☀️ — a beautiful day to be out and about!

The weather in **Paris** is currently **sunny** ☀️ — a beautiful day to be out and about!

agent.run démarre une session, envoie le message et renvoie le résultat du tour une fois que l'agent a répondu. Le modèle a appelé get_weather, puis rédigé la réponse à partir du résultat. Pour envoyer plusieurs messages dans la même conversation, consultez Sessions.

agents chat charge le même fichier main.py et ouvre une conversation dans votre terminal. Pour lui fournir votre clé, exécutez la commande avec uv run --env-file .env, ou exportez MISTRAL_API_KEY dans votre shell.

uv run --env-file .env agents chat

uv run --env-file .env agents chat

Talking to the agent in this process (session 4236c157-70c1-4211-a914-cc43e49adb1f). Ctrl+D or /exit to quit.
> Tell me about the weather in Paris
→ get_weather {"city": "Paris"}
← get_weather done
Here's the current weather in **Paris**: **Sunny!**

It's a bright, sunny day in the City of Light. Perfect weather for a stroll along the Seine or relaxing at a café terrace! Is there anything else you'd like to know?

Talking to the agent in this process (session 4236c157-70c1-4211-a914-cc43e49adb1f). Ctrl+D or /exit to quit.
> Tell me about the weather in Paris
→ get_weather {"city": "Paris"}
← get_weather done
Here's the current weather in **Paris**: **Sunny!**

It's a bright, sunny day in the City of Light. Perfect weather for a stroll along the Seine or relaxing at a café terrace! Is there anything else you'd like to know?

La réponse s'affiche en streaming à mesure que le modèle la rédige, et chaque appel d'outil s'affiche pendant son exécution. La conversation conserve tous les messages : l'agent garde donc le contexte des échanges. Ctrl+C interrompt un tour ; Ctrl+D ou /exit met fin à la conversation. Pour envoyer un seul message puis quitter, ajoutez -m.

Un outil est une fonction Python, synchrone ou asynchrone, munie du décorateur @agents.tool. Ajoutez un outil de prévisions météo dans main.py, au-dessus de l'agent, puis ajoutez-le à la liste tools de l'agent. Conservez get_weather et 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],
)

Posez une question qui nécessite le nouvel outil :

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?"

→ get_forecast {"city": "Paris", "days": 3}
← get_forecast done
Yes — according to the forecast, **it will rain in Paris on all of the next 3 days**:

- **Day 1:** Rain
- **Day 2:** Rain
- **Day 3:** Rain

Looks like a wet stretch ahead — pack an umbrella!

→ get_forecast {"city": "Paris", "days": 3}
← get_forecast done
Yes — according to the forecast, **it will rain in Paris on all of the next 3 days**:

- **Day 1:** Rain
- **Day 2:** Rain
- **Day 3:** Rain

Looks like a wet stretch ahead — pack an umbrella!

Le modèle a renseigné les deux paramètres à partir de la question, en utilisant un entier pour days. Modifiez main.py, puis relancez la conversation : c'est la boucle la plus rapide pendant le développement de l'agent.

Déployer votre agent explique comment exécuter le même projet sur Mistral avec agents deploy, puis l'appeler par son nom depuis votre application.

L'agent peut aussi s'exécuter ailleurs, avec le même fichier main.py :

• Sur vos propres serveurs, par exemple lorsque ses outils doivent s'exécuter dans votre réseau : Auto-hébergés (agents serve).
• Comparer les modes : Modes d'exécution.

Pour aller plus loin :

• Exécuter un tour pas à pas : agent.run renvoie le résultat à l'endroit où le tour s'est arrêté : sa réponse, ou la demande d'approbation en attente. Lorsqu'un appel d'outil attend une approbation, Exécuter une session pas à pas explique comment y répondre pour permettre au tour de continuer.
• Suivre et orienter un tour : Construire une application de session affiche les événements du tour à mesure qu'ils se produisent, pendant que vous envoyez des messages à l'agent.
• Examiner le déroulement : agents chat affiche chaque appel d'outil et son résultat pendant l'exécution du tour. Une fois l'agent déployé, chaque tour apparaît aussi sous forme de trace dans Mistral Studio, avec un span par appel de modèle et par appel d'outil.
• Consulter un projet complet : le bot météo Telegram ajoute une interface de conversation à un agent du même type.
• Donner plus de ressources à l'agent : Outils, Environnement et Connecteurs et MCP.
• Comprendre l'agent : Qu'est-ce qu'un agent.