Événements et entrées de l'historique

Les événements fournis par iter_events et on_event, et les entrées de l'historique d'une session.

Guides : Événements et Entrées de l'historique.

class Event(*, id: str, session_id: str, turn_id: str | None)

class Event(*, id: str, session_id: str, turn_id: str | None)

Un événement d'une session.

id est sa position dans le log de la session. turn_id est le tour pendant lequel il s'est produit, ou None entre les tours ou lorsque l'événement n'indique pas son tour.

class TurnStarted(*, id: str, session_id: str, turn_id: str | None)

class TurnStarted(*, id: str, session_id: str, turn_id: str | None)

Un tour a commencé.

Hérite de id, session_id et turn_id de Event.

class TurnUpdated(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    status: Literal['running', 'blocked', 'terminated'] | UnknownValue,
)

class TurnUpdated(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    status: Literal['running', 'blocked', 'terminated'] | UnknownValue,
)

Le statut d'un tour a changé : "blocked" lorsqu'il attend un callback, comme une approbation, "running" lorsqu'il reprend son exécution, "terminated" lorsqu'il est terminé, et un UnknownValue pour un statut ajouté après votre version du SDK, avec lequel le tour poursuit son exécution. turn_id est toujours l'ID de ce tour.

L'ouverture d'un callback est signalée par CallbackOpened, et la fin du tour par TurnEnded, qui contient son enregistrement.

Hérite de id et session_id de Event.

class TurnEnded(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    state: Completed[str] | Interrupted | Failed | UnknownOutcome,
)

class TurnEnded(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    state: Completed[str] | Interrupted | Failed | UnknownOutcome,
)

Un tour s'est terminé. Émis une seule fois, à la fin du tour ; state est l'enregistrement final du tour.

Pour lire les événements qui le suivent, passez son id à after=, et non state.cursor, qui peut désigner une position ultérieure.

Hérite de id, session_id et turn_id de Event.

class CallbackOpened(*, id: str, session_id: str, turn_id: str | None, callback: OpenCallback)

class CallbackOpened(*, id: str, session_id: str, turn_id: str | None, callback: OpenCallback)

Le tour attend un callback, comme une approbation.

Hérite de id, session_id et turn_id de Event.

class CallbackResolved(*, id: str, session_id: str, turn_id: str | None, callback_id: str)

class CallbackResolved(*, id: str, session_id: str, turn_id: str | None, callback_id: str)

Un callback a reçu une réponse ou a été fermé.

turn_id est le tour qui a ouvert le callback, ou None lorsque la résolution n'indique pas son tour.

Hérite de id, session_id et turn_id de Event.

class SessionUpdated(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    status: Literal['running', 'waiting', 'terminated'] | UnknownValue,
    title: str | None,
    archived: bool,
)

class SessionUpdated(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    status: Literal['running', 'waiting', 'terminated'] | UnknownValue,
    title: str | None,
    archived: bool,
)

La session a changé : son statut ou son titre a été modifié, ou elle a été archivée.

status vaut "running" lorsqu'un tour est actif, "waiting" lorsqu'aucun tour ne l'est, et "terminated" lorsque la session est terminée, ou un UnknownValue pour un statut ajouté après votre version du SDK. title est le titre de la session, ou None si elle n'en a pas encore. archived indique si la session est archivée. turn_id vaut toujours None : une modification de la session n'appartient à aucun tour, même si elle intervient pendant l'exécution d'un tour.

Hérite de id, session_id et turn_id de Event.

class Notice(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    message: str,
    level: Literal['info', 'warning', 'error'] | UnknownValue,
    source: str | None,
    details: JsonValue = None,
)

class Notice(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    message: str,
    level: Literal['info', 'warning', 'error'] | UnknownValue,
    source: str | None,
    details: JsonValue = None,
)

Une notification destinée au développeur, que le modèle ne reçoit pas.

Par exemple, un connecteur ou un serveur MCP dont les outils sont actuellement indisponibles, ou une estimation de la fenêtre de contexte. level vaut "info", "warning" ou "error", ou un UnknownValue pour un niveau ajouté après votre version du SDK. source indique l'objet de la notification, comme "mistral_connectors:notion" pour un connecteur, ou vaut None. details contient ses données, comme {"source_id": "mistral_connectors:notion", "connector": "notion", "status": "unavailable", "reason": "..."} pour un connecteur ; ne les modifiez pas, copiez-les d'abord. Pour un serveur MCP indisponible, source est l'ID du serveur et details["reason"] en indique la raison : "credential_rejected" (HTTP 401 ou 403), "credential_unavailable", "unreachable", "timeout", "invalid_catalog" ou "request_failed". Un échec d'un autre type n'a pas de reason. turn_id est le tour auquel cette notification appartient, ou None : sa valeur reste la même à chaque lecture.

Hérite de id, session_id et turn_id de Event.

class EntryAdded(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    entry: MessageEntry | ToolCallEntry | ToolResultEntry | UnknownEntry,
)

class EntryAdded(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    entry: MessageEntry | ToolCallEntry | ToolResultEntry | UnknownEntry,
)

Une entrée a été ajoutée à l'historique de la session : un message, un appel d'outil, le résultat d'un outil ou une autre entrée.

entry est l'entrée telle qu'elle a été ajoutée initialement : un MessageEntry (l'entrée de l'utilisateur, le texte du modèle, un ContextMessage reçu par le modèle avec l'entrée), un ToolCallEntry, un ToolResultEntry (son tool_call_id est celui de l'appel, y compris pour un outil côté client), ou un UnknownEntry pour une entrée d'un type ajouté après votre version du SDK, ou que cette version ne lit que sous forme de données brutes, comme un point de contrôle. Elle peut être incomplète : un message que le modèle est en train de rédiger contient son texte initial, un résultat d'outil ajouté pendant l'exécution de l'outil n'a pas encore de contenu. L'entrée entière est ensuite fournie par EntryCompleted. turn_id est celui de l'entrée, identique à chaque lecture.

Hérite de id, session_id et turn_id de Event.

class EntryCompleted(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    entry: MessageEntry | ToolCallEntry | ToolResultEntry | UnknownEntry,
)

class EntryCompleted(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    entry: MessageEntry | ToolCallEntry | ToolResultEntry | UnknownEntry,
)

Une entrée de l'historique de la session est complète : entry contient l'entrée entière et définitive.

Chaque entrée est d'abord fournie par EntryAdded, puis une seule fois par EntryCompleted, même si elle est complète dès son ajout, comme le message de l'utilisateur ou un appel d'outil. entry et turn_id sont les mêmes que dans EntryAdded. Un lecteur qui commence après le EntryAdded d'une entrée ne reçoit que son EntryCompleted.

Hérite de id, session_id et turn_id de Event.

class TextDelta(*, id: str, session_id: str, turn_id: str | None, entry_id: str, text: str)

class TextDelta(*, id: str, session_id: str, turn_id: str | None, entry_id: str, text: str)

Le texte que le modèle vient d'écrire pendant la rédaction d'un message.

entry_id est l'ID de l'entrée du message : les deltas arrivent après son EntryAdded et avant son EntryCompleted, qui contient tout le texte. Le texte présent lors de l'ajout du message arrive juste après son EntryAdded, avec le même entry_id. text est le nouveau texte : les deltas d'une entrée, concaténés, constituent son texte jusqu'à cet instant, si aucun n'a été manqué. Conservez le texte de l'entrée complète : lorsque l'appel au modèle est relancé, le message peut être réécrit depuis le début, sous le même ID. Les deltas ne sont disponibles qu'en direct : un lecteur qui commence tard ou reprend la lecture après un curseur peut manquer une partie ou la totalité des deltas d'un message, mais jamais les événements de son entrée. Lorsque le tour se termine, lisez l'entrée du message, et non ses deltas.

Hérite de id, session_id et turn_id de Event.

class UnknownEvent(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    type: str,
    raw: dict[str, JsonValue] = {},
)

class UnknownEvent(
    *,
    id: str,
    session_id: str,
    turn_id: str | None,
    type: str,
    raw: dict[str, JsonValue] = {},
)

Un type d'événement ajouté après votre version du SDK. type indique son nom, et raw contient ses données.

De nouveaux types d'événements sont ajoutés dans les versions mineures. Ignorez les types d'événements que vous ne connaissez pas. turn_id vaut toujours None ; lisez raw pour obtenir les données de l'événement.

Hérite de id, session_id et turn_id de Event.

class MessageEntry(
    *,
    id: str,
    turn_id: str | None,
    role: Literal['user', 'assistant', 'system', 'context'],
    content: tuple[ContentBlock, ...],
)

class MessageEntry(
    *,
    id: str,
    turn_id: str | None,
    role: Literal['user', 'assistant', 'system', 'context'],
    content: tuple[ContentBlock, ...],
)

Un message dans l'historique d'une session : celui de l'utilisateur, celui du modèle, un message système ou un message de contexte.

id et turn_id sont les mêmes que dans ToolCallEntry. role vaut "user" pour l'entrée d'un tour ou une instruction de réorientation, "assistant" pour le texte du modèle, "system" pour un message système fourni dans l'historique initial d'une session, et "context" pour un ContextMessage. content contient les blocs de contenu du message, dont les classes sont celles des blocs de l'entrée d'un tour ; text est leur texte concaténé. Un message envoyé par un autre agent au modèle de cette session est un UnknownEntry de type "message", dont l'expéditeur figure dans raw.

class ContextMessage(
    *,
    id: str,
    turn_id: str | None,
    content: tuple[ContentBlock, ...],
    kind: Literal['input', 'capability_source'],
    source: str | None,
)

class ContextMessage(
    *,
    id: str,
    turn_id: str | None,
    content: tuple[ContentBlock, ...],
    kind: Literal['input', 'capability_source'],
    source: str | None,
)

Un message de contexte dans l'historique d'une session : du texte reçu par le modèle avec l'entrée d'un tour, qui n'est pas le message de l'utilisateur lui-même.

Il s'agit d'un MessageEntry dont le role vaut "context" ; id, turn_id, content et text sont les mêmes que dans cette classe. kind indique qui l'a ajouté : "input" pour un message de contexte envoyé avec un message, "capability_source" pour un message ajouté par la session au sujet d'une source d'outils, comme un connecteur dont les outils sont actuellement indisponibles ou le sont à nouveau. source indique cette source d'outils, comme "mistral_connectors:notion", de la même manière que dans Notice ; sa valeur est None pour un message de contexte envoyé avec un message. Le modèle le reçoit juste avant l'entrée de début de tour ou l'instruction de réorientation qui l'accompagnait ; dans l'historique, il figure après cette entrée.

Hérite de id, turn_id et content de MessageEntry.

class ToolCallEntry(
    *,
    id: str,
    turn_id: str | None,
    tool_call_id: str,
    name: str,
    arguments: JsonValue,
)

class ToolCallEntry(
    *,
    id: str,
    turn_id: str | None,
    tool_call_id: str,
    name: str,
    arguments: JsonValue,
)

Un appel d'outil dans l'historique d'une session : le modèle a appelé un outil.

id est l'identifiant de l'entrée dans l'historique. turn_id est le tour dans lequel l'appel a été effectué, ou None lorsque l'entrée ne fait pas partie d'un tour, par exemple dans un historique fourni au début de la session. tool_call_id désigne l'appel : le résultat de l'outil porte le même identifiant. name est l'identifiant complet de l'outil, comme client.get_weather, comme dans ToolCall. arguments correspond aux arguments de l'appel : ceux du modèle, ou ceux définis par un hook pre_tool_call (un appel ignoré conserve ceux du modèle). Ne les modifiez pas, copiez-les d'abord.

Il s'agit d'une entrée d'historique. ToolCall reste l'élément de Completed.tool_calls.

class ToolResultEntry(
    *,
    id: str,
    turn_id: str | None,
    tool_call_id: str,
    name: str | None,
    content: tuple[ContentBlock, ...],
    structured_content: JsonValue,
    is_error: bool,
    meta: dict[str, JsonValue] = {},
)

class ToolResultEntry(
    *,
    id: str,
    turn_id: str | None,
    tool_call_id: str,
    name: str | None,
    content: tuple[ContentBlock, ...],
    structured_content: JsonValue,
    is_error: bool,
    meta: dict[str, JsonValue] = {},
)

Le résultat d'un outil dans l'historique d'une session : la paire d'un ToolCallEntry.

id et turn_id sont comme dans ToolCallEntry. tool_call_id est l'identifiant de l'appel auquel ce résultat répond. name est l'identifiant complet de l'outil, comme client.get_weather, ou None lorsqu'il n'est pas connu. content correspond aux blocs de contenu renvoyés par l'outil, les classes de blocs de l'entrée d'un tour ; un outil qui a renvoyé une chaîne de caractères a un seul bloc de texte. structured_content est la sortie structurée de l'outil, comme un dict, ou None lorsqu'il n'en a pas renvoyé. is_error vaut True lorsque l'appel a échoué : content contient alors les blocs de contenu de l'erreur, ou son message sous forme d'un seul bloc de texte. structured_content contient alors la sortie de l'appel qui a échoué, s'il y en a une, comme les stdout et stderr d'une commande en échec. meta correspond aux métadonnées du résultat pour le client, comme le _meta de MCP et comme dans ToolResult ; elles sont vides lorsqu'il n'y en a pas. Ne modifiez pas structured_content ni meta, copiez-les d'abord.

class UnknownEntry(*, id: str, turn_id: str | None, type: str, raw: dict[str, JsonValue])

class UnknownEntry(*, id: str, turn_id: str | None, type: str, raw: dict[str, JsonValue])

Une entrée d'un type ajouté après votre version du SDK, ou une entrée que cette version lit uniquement sous forme de données brutes, comme un checkpoint. type la désigne, et raw contient ses données.

L'entrée conserve sa place dans l'historique au lieu de faire échouer la lecture. id et turn_id sont comme dans ToolCallEntry. Une version ultérieure du SDK peut fournir une entrée typée à la place.