Events and history entries

The events that iter_events and on_event give, and the entries of a session's history.

Guides: Events and History entries.

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

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

One event of a session.

id is its position in the session's log. turn_id is the turn it happened in, or None between turns or when the event does not name its turn.

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

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

A turn started.

Inherits id, session_id and turn_id from 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,
)

A turn's status changed: "blocked" when it waits on a callback, such as an approval, "running" when it runs again, "terminated" once it has ended, and an UnknownValue for a status added after your SDK version, with which the turn still runs. turn_id is always that turn's ID.

An open callback comes as CallbackOpened, and the turn's end as TurnEnded, which has its record.

Inherits id and session_id from 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,
)

A turn ended. Sent once, when the turn ends; state is the final turn record.

To read the events after it, pass after= its id, not state.cursor, which can be later.

Inherits id, session_id and turn_id from 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)

The turn waits on a callback, such as an approval.

Inherits id, session_id and turn_id from 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)

A callback was answered or closed.

turn_id is the turn that opened the callback, or None when the resolution does not name its turn.

Inherits id, session_id and turn_id from 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,
)

The session changed: its status, or its title, or it was archived.

status is "running" while a turn is active, "waiting" when no turn is, and "terminated" once the session has ended, and an UnknownValue for a status added after your SDK version. title is the session's title, or None when it has none yet. archived is whether the session is archived. turn_id is always None: a change of the session belongs to no turn, even one made while a turn runs.

Inherits id, session_id and turn_id from 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,
)

A notice for the developer, which the model does not get.

For example, a connector or an MCP server whose tools cannot be used now, or a guessed context window. level is "info", "warning" or "error", or an UnknownValue for a level added after your SDK version. source names what the notice is about, such as "mistral_connectors:notion" for one connector, or is None. details is its data, such as {"source_id": "mistral_connectors:notion", "connector": "notion", "status": "unavailable", "reason": "..."} for a connector; do not change it, copy it first. For an MCP server that cannot be used, source is the server's ID and details["reason"] says why: "credential_rejected" (HTTP 401 or 403), "credential_unavailable", "unreachable", "timeout", "invalid_catalog" or "request_failed". A failure of another kind has no reason. turn_id is the turn this notice belongs to, or None: the same in every read.

Inherits id, session_id and turn_id from 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,
)

An entry was added to the session's history: a message, a tool call, a tool's result, or another entry.

entry is the entry as it was first added: a MessageEntry (the user's input, the model's text, a ContextMessage the model got with the input), a ToolCallEntry, a ToolResultEntry (its tool_call_id is the call's, a client tool's too), or an UnknownEntry for an entry of a type added after your SDK version, or one this version reads only as raw data, such as a checkpoint. It can be incomplete: a message the model is writing has its first text, a tool's result added while the tool runs has no content yet. The whole entry comes as EntryCompleted, after it. turn_id is the entry's, the same in every read.

Inherits id, session_id and turn_id from 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,
)

An entry of the session's history is complete: entry is the whole entry, final.

Every entry comes as EntryAdded first, then once as EntryCompleted, also one added complete, such as the user's message or a tool call. entry and turn_id are as in EntryAdded. A reader that starts after an entry's EntryAdded gets only its EntryCompleted.

Inherits id, session_id and turn_id from 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)

Text the model just wrote, while it writes a message.

entry_id is the ID of the message's entry: the deltas come after its EntryAdded and before its EntryCompleted, which has all the text. The text the message was added with comes right after its EntryAdded, with the same entry_id. text is the new text: the deltas of one entry, joined, are its text so far, when none was missed. Keep the completed entry's text: when the model's call is retried, the message can be written again from its start, under the same ID. Deltas are live only: a reader that joins late or reads again after a cursor can miss some, or all, of a message's deltas, never its entry events. Once the turn ends, read the message's entry, not its deltas.

Inherits id, session_id and turn_id from 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] = {},
)

An event type added after your SDK version. type names it, and raw holds its data.

New event types are added in minor versions. Ignore the event types that you do not know. turn_id is always None; read raw for the event's data.

Inherits id, session_id and turn_id from 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, ...],
)

A message in a session's history: the user's, the model's, a system message or a context message.

id and turn_id are as in ToolCallEntry. role is "user" for a turn's input or a steer, "assistant" for the model's text, "system" for a system message given in a session's starting history, and "context" for a ContextMessage. content is the message's content blocks, the block classes of a turn's input; text is their text, joined. A message another agent sent this session's model is an UnknownEntry of type "message", with its sender in 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,
)

A context message in a session's history: text the model got with a turn's input, which is not the user's own message.

It is a MessageEntry whose role is "context"; id, turn_id, content and text are as there. kind says who added it: "input" for a context message sent with a message, "capability_source" for one the session added about a tool source, such as a connector whose tools cannot be used now, or are back. source names that tool source, such as "mistral_connectors:notion", as in Notice; it is None for a context message sent with a message. The model gets it just before the input of the turn start or the steer that carried it; the history has it after that input.

Inherits id, turn_id and content from 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,
)

A tool call in a session's history: the model called a tool.

id is the entry's ID in the history. turn_id is the turn the call was made in, or None when the entry is not part of a turn, for example in a history given at the session's start. tool_call_id names the call: the tool's result carries the same ID. name is the tool's full ID, such as client.get_weather, as in ToolCall. arguments is the call's arguments: the model's, or the ones a pre_tool_call hook set (a skipped call keeps the model's). Do not change it, copy it first.

This is a history entry. ToolCall stays the item of 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] = {},
)

A tool's result in a session's history: the pair of a ToolCallEntry.

id and turn_id are as in ToolCallEntry. tool_call_id is the ID of the call this result answers. name is the tool's full ID, such as client.get_weather, or None when it is not known. content is the content blocks the tool returned, the block classes of a turn's input; a tool that returned a string has one text block. structured_content is the tool's structured output, such as a dict, or None when it returned none. is_error is True when the call failed: content then holds the error's content blocks, or its message as one text block. structured_content then holds the failed call's output, if any, such as a failed command's stdout and stderr. meta is the result's metadata for the client, as MCP's _meta and as in ToolResult; it is empty when there is none. Do not change structured_content or meta, copy them first.

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

An entry of a type added after your SDK version, or one this version reads only as raw data, such as a checkpoint. type names it, and raw holds its data.

The entry keeps its place in the history instead of failing the read. id and turn_id are as in ToolCallEntry. A later SDK version can give a typed entry instead.