Les tours et leur enregistrement

Un tour correspond au travail effectué par l'agent pour répondre à un message. Le SDK l'exécute et vous renvoie son enregistrement : une valeur qui indique comment le tour s'est terminé ou ce qu'il attend. Vous démarrez un tour, attendez son résultat et consultez son enregistrement. Trois appels permettent de démarrer un tour :

reviewer.py est l'agent de vérification des paiements présenté dans Qu'est-ce qu'un agent. report affiche le contenu de chaque enregistrement :

import asyncio

from mistralai import agents

from reviewer import payment_reviewer


def report(state: agents.TurnState) -> None:
    match state:
        case agents.Completed(tool_calls=calls):
            print("completed:", [call.name for call in calls])
        case agents.Blocked(callbacks=callbacks):
            print("waits for:", [callback.title for callback in callbacks])
        case agents.Interrupted(cause=cause):
            print("stopped:", cause)
        case agents.Failed(error=error):
            print("failed:", error.message)
        case agents.Running():
            print("still running")
        case _:  # agents.UnknownOutcome: an outcome added after your SDK version
            print("ended:", type(state).__name__)


async def main() -> None:
    session = await payment_reviewer.start_session()
    turn = await session.start_turn(
        "Review transaction monitoring alert 4711.",
        idempotency_key="alert:4711:review",
    )
    if isinstance(turn, agents.Busy):
        turn = turn.turn  # another turn runs: follow it
    state = await turn.result()
    report(state)

    state = await session.run("Which case did you open? Reply with the case id only.")
    if isinstance(state, agents.Completed):
        print(state.text)
    report(state)
    await session.cancel()


asyncio.run(main())

import asyncio

from mistralai import agents

from reviewer import payment_reviewer


def report(state: agents.TurnState) -> None:
    match state:
        case agents.Completed(tool_calls=calls):
            print("completed:", [call.name for call in calls])
        case agents.Blocked(callbacks=callbacks):
            print("waits for:", [callback.title for callback in callbacks])
        case agents.Interrupted(cause=cause):
            print("stopped:", cause)
        case agents.Failed(error=error):
            print("failed:", error.message)
        case agents.Running():
            print("still running")
        case _:  # agents.UnknownOutcome: an outcome added after your SDK version
            print("ended:", type(state).__name__)


async def main() -> None:
    session = await payment_reviewer.start_session()
    turn = await session.start_turn(
        "Review transaction monitoring alert 4711.",
        idempotency_key="alert:4711:review",
    )
    if isinstance(turn, agents.Busy):
        turn = turn.turn  # another turn runs: follow it
    state = await turn.result()
    report(state)

    state = await session.run("Which case did you open? Reply with the case id only.")
    if isinstance(state, agents.Completed):
        print(state.text)
    report(state)
    await session.cancel()


asyncio.run(main())

completed: ['client.get_alert', 'client.open_case']
CASE-4711
completed: []

completed: ['client.get_alert', 'client.open_case']
CASE-4711
completed: []

Le deuxième tour n'a appelé aucun outil. Un outil que vous avez écrit apparaît sous la forme client.<name> : consultez Espaces de noms des outils.

Une session exécute un seul tour à la fois. Lorsqu'un tour est en cours, start_turn() et session.run() ne démarrent rien et renvoient agents.Busy, dont le champ turn contient le handle du tour en cours, comme dans main() ci-dessus. send_message() ajoute plutôt le message au tour en cours.

Tous les appels qui consultent un tour ou attendent son résultat renvoient le même enregistrement : turn.result(), turn.get(), session.run(), agent.run() et le champ state d'un événement TurnEnded. Utilisez le filtrage par motif selon son type :

Conservez un case _: pour gérer agents.UnknownOutcome, qui représente un résultat ajouté après la publication de votre version du SDK. Chaque enregistrement contient aussi session_id, turn_id, cursor et text, le texte de la dernière réponse du tour. Enregistrements des tours répertorie les champs de chaque type et les motifs d'arrêt d'un tour Completed.

timeout= limite votre attente, pas la durée du tour. À l'expiration du délai, l'appel renvoie l'enregistrement dans son état actuel, souvent Running, et le tour continue de s'exécuter. Attendez à nouveau avec turn.result(after=state) : consultez Turn.result.

Pour arrêter un tour, appelez await turn.interrupt(). Pour terminer la session, appelez await session.cancel().

• Événements : suivez un tour étape par étape pendant son exécution.
• Entrées de l'historique : consultez les entrées d'un tour ou démarrez une session à partir d'un historique existant.
• Approbations : répondez aux demandes d'approbation d'un tour Blocked.