Un appel : agent.run()

agent.run() exécute une tâche complète en un seul appel. Il démarre une session, y exécute un tour, attend que le tour se termine ou nécessite votre intervention, puis renvoie l'enregistrement du tour : une valeur qui indique son état. Vous rédigez le message, puis utilisez un match sur l'enregistrement.

Utilisez agent.run() pour une tâche sans suivi, et une session pour aller plus loin : consultez Choisir entre agent.run() et une session.

Posez une question :

import asyncio

from mistralai import agents

agent = agents.Agent(model="mistral-large-4")


async def hello() -> None:
    result = await agent.run("Say hello in one short sentence, without emoji.")
    print(result.text)


asyncio.run(hello())

import asyncio

from mistralai import agents

agent = agents.Agent(model="mistral-large-4")


async def hello() -> None:
    result = await agent.run("Say hello in one short sentence, without emoji.")
    print(result.text)


asyncio.run(hello())

Hello, how can I help you today?

Hello, how can I help you today?

run() a démarré une session, exécuté un tour et renvoyé son enregistrement. Chaque enregistrement contient le text du tour, ses identifiants session_id et turn_id, ainsi qu'un cursor.

Un tour peut se terminer de plusieurs façons, et run() renvoie un enregistrement différent pour chacune. Aucun de ces résultats ne lève d'exception : lisez donc l'enregistrement avec match. Ajoutez ce qui suit au fichier de la section Exécuter une tâche :

reviewer = agents.Agent(
    model="mistral-large-4",
    instructions="You review payment alerts. Say how suspicious each one looks, in one sentence of at most 20 words.",
)


async def review() -> None:
    state = await reviewer.run("Review alert 4711: 9,800 EUR to a new payee at 03:12.")
    match state:
        case agents.Completed(text=text):
            print(text)
        case agents.Failed(error=error):
            print(f"failed: {error.code}: {error.message}")
        case _:
            print(f"the turn is {type(state).__name__}")


asyncio.run(review())

reviewer = agents.Agent(
    model="mistral-large-4",
    instructions="You review payment alerts. Say how suspicious each one looks, in one sentence of at most 20 words.",
)


async def review() -> None:
    state = await reviewer.run("Review alert 4711: 9,800 EUR to a new payee at 03:12.")
    match state:
        case agents.Completed(text=text):
            print(text)
        case agents.Failed(error=error):
            print(f"failed: {error.code}: {error.message}")
        case _:
            print(f"the turn is {type(state).__name__}")


asyncio.run(review())

Highly suspicious: a large 9,800 EUR transfer to a brand-new payee at 3 AM is a classic fraud pattern.

Highly suspicious: a large 9,800 EUR transfer to a brand-new payee at 3 AM is a classic fraud pattern.

run() renvoie les mêmes enregistrements que session.run() : consultez Les tours et leur enregistrement. Avec run(), Blocked indique que le tour attend une approbation, une connexion à un connecteur ou un appel d'outil côté client auquel aucun gestionnaire n'a répondu. Running indique que le délai timeout= est écoulé, mais que le tour continue de s'exécuter.

Passez un modèle Pydantic via output_type= : le champ output d'un enregistrement Completed contient alors la réponse convertie en une instance de ce modèle. Dans le même fichier :

from pydantic import BaseModel


class RiskScore(BaseModel):
    score: int
    reason: str


scorer = agents.Agent(
    model="mistral-medium-latest",
    instructions="You score payment alerts for fraud risk. Give the reason in one sentence of at most 20 words.",
)


async def score_alert() -> None:
    state = await scorer.run(
        "Score alert 4711 from 0 to 100: 9,800 EUR to a new payee at 03:12.",
        output_type=RiskScore,
    )
    match state:
        case agents.Completed(output=agents.InvalidOutput(error=error)):
            print(f"the reply is not a RiskScore: {error}")
        case agents.Completed(output=RiskScore() as score):
            print(score.score, score.reason)
        case _:
            print(f"no score: {state!r}")


asyncio.run(score_alert())

from pydantic import BaseModel


class RiskScore(BaseModel):
    score: int
    reason: str


scorer = agents.Agent(
    model="mistral-medium-latest",
    instructions="You score payment alerts for fraud risk. Give the reason in one sentence of at most 20 words.",
)


async def score_alert() -> None:
    state = await scorer.run(
        "Score alert 4711 from 0 to 100: 9,800 EUR to a new payee at 03:12.",
        output_type=RiskScore,
    )
    match state:
        case agents.Completed(output=agents.InvalidOutput(error=error)):
            print(f"the reply is not a RiskScore: {error}")
        case agents.Completed(output=RiskScore() as score):
            print(score.score, score.reason)
        case _:
            print(f"no score: {state!r}")


asyncio.run(score_alert())

95 High amount to new payee at unusual hour.

95 High amount to new payee at unusual hour.

Si la réponse échoue à la validation, output contient un objet agents.InvalidOutput avec la réponse brute et l'erreur de validation. Le tour reste Completed : vérifiez d'abord ce cas avec match. Consultez Sortie structurée.

Un tour qui échoue renvoie agents.Failed, quel que soit l'endroit où l'agent s'exécute. Son champ error contient code, message, retryable et details. Si le fournisseur du modèle a refusé la requête, le message se termine par le motif donné par ce fournisseur. Dans le même fichier :

async def failed() -> None:
    agent = agents.Agent(model="mistral-nope-9")
    match await agent.run("Say hello"):
        case agents.Failed(error=error):
            print(error.code, error.retryable)
            print(error.message)


asyncio.run(failed())

async def failed() -> None:
    agent = agents.Agent(model="mistral-nope-9")
    match await agent.run("Say hello"):
        case agents.Failed(error=error):
            print(error.code, error.retryable)
            print(error.message)


asyncio.run(failed())

completion_rejected False
The model provider request for model 'mistral-nope-9' failed with HTTP status 400: Invalid model: mistral-nope-9

completion_rejected False
The model provider request for model 'mistral-nope-9' failed with HTTP status 400: Invalid model: mistral-nope-9

Quand error.retryable vaut True, par exemple en cas de limite de débit (completion_rate_limited) ou d'indisponibilité du fournisseur (completion_unavailable), la même requête peut réussir si vous l'envoyez à nouveau. Une requête rejetée (completion_rejected) ou une clé API refusée (completion_unauthorized) ne permet pas de nouvelle tentative : corrigez d'abord le problème. ProtocolError répertorie toutes les valeurs de code.

Les erreurs qui ne concernent pas le tour, comme un message vide ou un argument incorrect, lèvent des exceptions avant le démarrage du tour : consultez Erreurs.

Utilisez agent.run() pour une tâche sans suivi. Démarrez une session si vous envoyez plusieurs messages, ou si un autre processus surveille le tour ou y répond : consultez Avancer dans une session étape par étape. Agent.run précise à quel moment la session démarrée par run() se ferme.

Pour répondre aux demandes d'approbation ou suivre le tour pendant son exécution, passez on_approval= ou on_event=.

• state.output vaut None avec output_type=. Le tour s'est terminé sans réponse finale : state.stop_reason en indique la raison. Par exemple, "iteration_limit" correspond à la limite max_iterations, et "output_limit" signifie que la dernière réponse du modèle s'est arrêtée à la limite de tokens de sortie. Consultez state.text pour lire la dernière réponse du modèle.
• run() renvoie Blocked. Le tour attend une approbation, une connexion ou un appel d'outil côté client, et aucun gestionnaire on_approval=, on_sign_in= ou on_client_tool= n'y a répondu. Passez un gestionnaire ou répondez depuis une session : consultez Avancer dans une session étape par étape.
• run() renvoie Running. Le délai timeout= est écoulé, mais le tour continue de s'exécuter : accédez-y avec agent.session(state.session_id).turn(state.turn_id).

• Avancer dans une session étape par étape : envoyez plusieurs messages dans une même session et faites avancer un tour en répondant à ses demandes d'approbation.
• Construire une application avec des sessions : surveillez une session et envoyez-lui des commandes.