Home
Studio

Points forts des fonctionnalités

Chaque exemple montre une fonctionnalité en quelques lignes de Python, avec la sortie d'une exécution réelle.

Pour exécuter les exemples, installez le SDK et collez chacun d'eux dans main() du fichier ci-dessous. Ses outils renvoient un texte fixe.

main.py, utilisé par tous les exemples
import asyncio

from pydantic import BaseModel

from mistralai import agents


@agents.tool(annotations=agents.ToolAnnotations(read_only_hint=True))
async def get_order(order_id: str) -> str:
    """Get the status of an order."""
    return f"Order {order_id}: delivered, 49 EUR"


@agents.tool(annotations=agents.ToolAnnotations(read_only_hint=True))
async def list_orders(country: str) -> list[str]:
    """List this week's orders for a country, or for every country with 'any'."""
    return [f"order {number} ({country})" for number in range(1040, 1045)]


@agents.tool
async def refund_order(order_id: str) -> str:
    """Refund an order."""
    return f"Order {order_id}: refunded"


agent = agents.Agent(
    model="mistral-large-4",
    name="support-agent",
    instructions="Answer questions about orders in one plain sentence.",
    tools=[get_order, list_orders, refund_order],
)


async def main() -> None:
    ...  # paste an example's code here


if __name__ == "__main__":
    asyncio.run(main())
Approuver les appels d'outils

Approuver les appels d'outils

Avec permission_mode="ask", chaque appel d'outil nécessite une approbation. Votre code peut la donner, ou laisser une personne approuver l'appel.

def policy(
    ctx: agents.ApprovalCallbackContext, request: agents.ApprovalRequest
) -> agents.AllowApproval | agents.KeepCallbackOpen:
    if request.tool.annotations.read_only_hint:
        return agents.AllowApproval()
    return agents.KeepCallbackOpen()  # anything else waits for a person


careful = agents.Agent(
    model="mistral-large-4",
    tools=[get_order, refund_order],
    permission_mode="ask",
)
session = await careful.start_session(on_approval=policy)
state = await session.run("Check the status of order 1042, then refund it.")
while isinstance(state, agents.Blocked):  # refund_order waits
    turn = session.turn(state.turn_id)
    for callback in state.callbacks:
        await turn.answer(callback.id, agents.AllowApproval())  # a person allows
    state = await turn.result(after=state)
if isinstance(state, agents.Completed):
    print(state.text)
await session.cancel()
Done! Here's a summary:
- **Status check:** Order **1042** was **delivered**, amount **49 EUR**.
- **Refund:** Order **1042** has been **refunded** ✅

La boucle s'exécute jusqu'à la fin du tour : turn.result(after=state) attend de nouveau le tour, là où il s'était arrêté. Voir Approbations et Parcourir une session pas à pas.

Piloter un tour pendant son exécution

Piloter un tour pendant son exécution

Envoyez un message à l'agent pendant qu'il travaille, pour modifier ce qu'il fait. on_event= affiche les événements du tour au fur et à mesure.

def show(event: agents.Event) -> None:
    match event:
        case agents.EntryCompleted(entry=agents.MessageEntry(role="user") as message):
            print("user:", message.text)
        case agents.EntryCompleted(entry=agents.ToolCallEntry(name, arguments)):
            print("calling", name, arguments)
        case agents.TextDelta(text=text):
            print(text, end="", flush=True)  # the reply, while the model writes it


session = await agent.start_session()
turn = await session.send_message("List this week's orders, then count them.")
await turn.steer("Only the orders from France.")
state = await turn.result(on_event=show)
print()
await session.cancel()
user: List this week's orders, then count them.
user: Only the orders from France.
calling client.list_orders {'country': 'France'}
This week's orders from France:

1. order 1040 (France)
2. order 1041 (France)
3. order 1042 (France)
4. order 1043 (France)
5. order 1044 (France)

**Total: 5 orders**

Le message de pilotage rejoint le tour en cours. Ici, il arrive avant le premier appel d'outil, si bien que l'agent ne liste que les commandes provenant de France. Voir Construire une application avec des sessions et Suivre un tour pendant l'attente.

Obtenir un résultat typé en un seul appel

Obtenir un résultat typé en un seul appel

run envoie un message et attend la réponse. Passez un modèle Pydantic en tant que output_type pour obtenir la réponse sous forme d'objet de ce modèle.

class Order(BaseModel):
    order_id: str
    delivered: bool
    price_eur: int


typed = agents.Agent(model="mistral-medium-latest", tools=[get_order])
state = await typed.run("What is the status of order 1042?", output_type=Order)
if isinstance(state, agents.Completed):
    print(state.output)
order_id='1042' delivered=True price_eur=49

Voir Un seul appel et Sortie structurée.

Interagir avec un agent

Interagir avec un agent

Une session conserve tout ce que l'agent a fait, si bien que chaque message s'appuie sur le travail précédent. Elle peut contenir un échange rapide ou un travail qui dure des heures.

session = await agent.start_session()
await session.run("My order is 1042.")
state = await session.run("Which order is mine?")
if isinstance(state, agents.Completed):
    print(state.text)
await session.cancel()  # ends the session
Your order is 1042.

Voir Sessions.

Déployer sur Mistral

Déployer sur Mistral

Dans un projet créé par agents init, avec le main.py ci-dessus (son agent est support-agent) : discutez avec l'agent dans votre terminal, puis poussez-le et déployez-le. Le déploiement construit le commit que vous avez poussé vers GitHub, dans le dépôt que Déployer votre agent met en place :

uv run --env-file .env agents chat
git add --all && git commit -m "Support agent"
git push
uv run --env-file .env agents deploy

Votre application charge l'agent déployé par son nom, puis l'exécute comme un agent local :

agent = agents.Agent.load_from(agent_name="support-agent")
state = await agent.run("Has order 1042 shipped?")
if isinstance(state, agents.Completed):
    print(state.text)
Yes, order 1042 was delivered.

Voir Déployer votre agent et Déployer.

Exécuter en arrière-plan

Exécuter en arrière-plan

Une fois que vous avez déployé avec Studio, auto-hébergé ou géré par Mistral, l'exécution est durable et s'effectue en arrière-plan. Votre application peut s'arrêter et récupérer le résultat plus tard. Cet exemple utilise l'agent de Déployer sur Mistral.

agent = agents.Agent.load_from(agent_name="support-agent")
session = await agent.start_session()
turn = await session.send_message("List this week's orders, then count them.")
session_id, turn_id = session.id, turn.id  # store them, then exit

# Later, after your app restarts:
agent = agents.Agent.load_from(agent_name="support-agent")
session = agent.session(session_id)
state = await session.turn(turn_id).result()
if isinstance(state, agents.Completed):
    print(state.text)
await session.cancel()
There are 5 orders this week.

Voir Retrouver une session et Ouvrir une session à partir de son id.

Aller plus loin

Aller plus loin