Session et tour

Les références à une session et à ses tours, et les données qu'un tour accepte en entrée.

Guides : Sessions et Tours.

class Session

class Session

Une session, identifiée par son ID. Créer une référence avec agent.session(session_id) n'envoie aucune requête.

Obtenez une référence avec await agent.start_session(), ou utilisez un ID enregistré avec agent.session(session_id). Les deux méthodes conservent le output_type de l'agent pour run, ainsi que pour get et result des tours de la session.

on_approval répond aux demandes d'approbation de la session et de ses sous-agents pendant l'attente de session.run ou turn.result, avec AllowApproval, DenyApproval ou agents.KeepCallbackOpen(). on_sign_in répond à leurs demandes de connexion avec un SignInAnswer. on_client_tool répond à leurs appels d'outils côté client, pour que l'attente ne renvoie pas Blocked pour ces appels. Un gestionnaire d'approbation ou de connexion qui lève une exception ou renvoie une autre valeur laisse son callback ouvert, et l'appel en attente lève une exception tandis que le tour continue de s'exécuter. Une réponse d'outil côté client ou un gestionnaire on_client_tool qui lève une exception suit le paramètre tool_errors de l'agent, comme pour agent.run : par défaut, le modèle est informé de l'échec de l'appel et l'attente continue. Deux attentes simultanées dans une même boucle d'événements partagent les réponses : la fonction de réponse s'exécute une fois par appel d'outil côté client.

Deux références sont égales lorsqu'elles désignent la même session au même endroit : la même API Mistral pour un agent déployé, quelle que soit la manière dont vous l'avez chargé, ou le même environnement d'exécution local. Vous pouvez les conserver dans un ensemble ou les utiliser comme clés de dictionnaire.

def turn(turn_id: str) -> Turn

def turn(turn_id: str) -> Turn

Renvoie la référence à un tour de cette session. N'envoie aucune requête.

async def send_message(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    idempotency_key: str | None = None,
) -> Turn

async def send_message(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    idempotency_key: str | None = None,
) -> Turn

Envoie un message : la session démarre un tour ou ajoute le message au tour en cours.

turn.started indique le cas : True pour un nouveau tour, False pour le tour en cours.

Lève agents.SessionBusyError si la session ne peut toujours pas accepter le message après plusieurs tentatives ; aucune modification n'a été appliquée.

async def start_turn(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    idempotency_key: str | None = None,
) -> Turn | Busy

async def start_turn(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    idempotency_key: str | None = None,
) -> Turn | Busy

Démarre un nouveau tour. Renvoie Busy, avec le tour en cours dans busy.turn, si un tour est actif.

La même idempotency_key renvoie le tour démarré par cette clé ; sa réutilisation pour un autre message lève agents.SessionIdempotencyConflictError pendant l'exécution de la session. Une nouvelle tentative avec une clé refusée par Busy démarre un tour une fois le tour en cours terminé. Un démarrage ne rejoint jamais un tour en cours, donc turn.started vaut True.

Lève SessionBusyError si la session ne peut pas accepter un démarrage pour une autre raison, comme une limite du nombre de sous-agents en cours d'exécution ; aucune modification n'a été appliquée.

async def run(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    output_type: type[BaseModel] | None = None,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    on_event: Callable[[Event], Awaitable[None] | None] | None = None,
) -> TurnState[Any] | Busy

async def run(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
    *,
    output_type: type[BaseModel] | None = None,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    on_event: Callable[[Event], Awaitable[None] | None] | None = None,
) -> TurnState[Any] | Busy

Démarre un tour et attend qu'il se termine ou qu'il attende un callback ; renvoie son enregistrement.

Renvoie Busy si un autre tour est actif. Équivaut à start_turn, puis turn.result(timeout=, on_event=) : quitter l'attente n'arrête pas le tour. Avec le on_client_tool de la référence, lève les mêmes exceptions que Turn.result pour une réponse d'outil côté client.

def iter_events(*, after: TurnState[object] | str | None = None) -> AsyncIterator[Event]

def iter_events(*, after: TurnState[object] | str | None = None) -> AsyncIterator[Event]

Produit les événements de la session après after, un enregistrement ou un curseur, ou depuis son début.

Suit la session jusqu'à sa fin, sans jamais rien modifier. Lit chaque tour terminé, de sorte que chaque TurnEnded contient son enregistrement.

async def cancel() -> None

async def cancel() -> None

Termine la session et ses sous-agents. Une session déjà terminée reste inchangée.

Les tours en cours sont interrompus et la session n'accepte plus de nouvelle commande : un envoi ultérieur lève SessionTerminatedError. Son historique reste accessible en lecture. Pour une session déployée, l'annulation revient dès que le déploiement l'accepte ; pour une session locale, elle revient une fois la session terminée et sa sandbox libérée. Un sous-agent ne peut pas être annulé seul. Annulez plutôt sa session racine.

async def subagents() -> list[Session]

async def subagents() -> list[Session]

Renvoie les références aux sous-agents directs de cette session, du plus récent au plus ancien.

La référence à un sous-agent permet la lecture, et ses tours acceptent interrupt : send_message, start_turn, run et cancel sur la référence, ainsi que steer sur ses tours, lèvent UnsupportedSessionProcedureError. Pour réorienter un sous-agent, envoyez un message à son parent ou utilisez steer sur celui-ci ; pour l'arrêter, annulez sa session racine. Il utilise les mêmes on_approval, on_sign_in et on_client_tool que cette référence.

class Turn

class Turn

Un tour d'une session, identifié par son ID. Créer une référence avec session.turn(turn_id) n'envoie aucune requête.

Obtenez une référence avec session.turn(turn_id) ou à partir d'un envoi. Deux références au même tour de la même session sont égales.

async def get() -> TurnState[Any]

async def get() -> TurnState[Any]

Lit l'état actuel de ce tour. N'attend jamais et ne modifie jamais le tour.

Renvoie Running, Blocked (le tour attend un callback), ou l'enregistrement de la façon dont le tour s'est terminé : Completed, Interrupted, Failed ou UnknownOutcome. Completed.output contient le texte du tour ou, si l'agent associé à la référence possède un output_type, ce texte analysé comme avec result(output_type=...). Le cursor de l'enregistrement est l'ID du dernier événement de la session au moment de la lecture. Le tour actif de la session est également Blocked lorsqu'un de ses sous-agents, à n'importe quelle profondeur, attend un callback, comme une approbation : Blocked.callbacks le liste avec les ID du sous-agent. Un tour d'une session terminée n'est jamais Running. Si la session n'a pas indiqué comment le tour s'est terminé, son état reflète la fin de la session : pour une session annulée, Interrupted avec cause="cancelled". Un tour renvoyé par un envoi est Running jusqu'à ce que la session le répertorie : un agent déployé répond à l'envoi avant de le faire.

async def result(
    *,
    output_type: type[BaseModel] | None = None,
    after: TurnState[object] | str | None = None,
    timeout: float | None = None,
    on_event: Callable[[Event], Awaitable[None] | None] | None = None,
) -> TurnState[Any]

async def result(
    *,
    output_type: type[BaseModel] | None = None,
    after: TurnState[object] | str | None = None,
    timeout: float | None = None,
    on_event: Callable[[Event], Awaitable[None] | None] | None = None,
) -> TurnState[Any]

Attend que le tour se termine ou qu'il attende un callback, puis renvoie son enregistrement.

Renvoie Completed, Interrupted, Failed ou UnknownOutcome quand le tour se termine, et Blocked s'il attend un callback ouvert après after et toujours ouvert. À l'expiration du délai, renvoie l'enregistrement du tour à cet instant, Running ou Blocked, sans lever d'exception.

Quitter l'attente n'envoie rien, et le tour continue de s'exécuter. Une annulation, comme asyncio.wait_for ou Ctrl-C, reçoit une note indiquant les ID et la marche à suivre pour arrêter le tour.

Sans after, un tour qui attend un callback renvoie immédiatement son état. Passez le dernier enregistrement de ce tour comme after pour attendre au-delà des callbacks déjà traités.

def iter_events(*, after: TurnState[object] | str | None = None) -> AsyncIterator[Event]

def iter_events(*, after: TurnState[object] | str | None = None) -> AsyncIterator[Event]

Produit les événements de ce tour après after, ou depuis son début, jusqu'à son TurnEnded.

Produit les événements déjà disponibles dans la session, puis ceux qui arrivent en direct, sans limite de temps : un tour qui attend une approbation peut n'envoyer aucun événement pendant des heures. Une fois le tour terminé, le dernier événement est TurnEnded, avec son enregistrement, et une position située à sa fin ou après ne produit rien, immédiatement. Ne modifie rien.

async def steer(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
) -> Turn | TurnConflict

async def steer(
    content: str | Sequence[TextContentBlock | ImageContentBlock | Mapping[str, Any]],
) -> Turn | TurnConflict

Ajoute un message à ce tour pendant son exécution.

Renvoie TurnConflict si ce tour n'est plus le tour actif : le message n'est pas ajouté.

async def answer(callback_id: str, answer: object) -> Answered | AlreadySettled | NotFound

async def answer(callback_id: str, answer: object) -> Answered | AlreadySettled | NotFound

Répond à tout callback ouvert de la session de ce tour ou de ses sous-agents, quel que soit le tour, à partir de son ID de callback. L'ID du tour n'est pas utilisé : l'ID d'un callback l'identifie dans sa session.

Une approbation (OpenApproval) accepte AllowApproval ou DenyApproval. Une demande de connexion (OpenSignIn) accepte un SignInAnswer qui désigne chaque source demandée, et uniquement celles-ci. Un appel d'outil côté client (OpenClientToolCall) accepte le résultat de l'outil : ce qu'une fonction de réponse renverrait, comme un modèle, un dictionnaire ou un ToolResult. Si le stub figure dans le tools= de l'agent ou de ses sous-agents, le résultat est vérifié par rapport au type de retour du stub et envoyé de la même manière que sa réponse. Sinon, il est envoyé en JSON, sans vérification : pour un outil créé avec output_schema=, un outil de hook, un ID d'outil partagé par deux stubs différents, ou une référence obtenue avec Agent.load_from().

Lit la session une fois, puis répond. Renvoie Answered si le callback était ouvert, AlreadySettled s'il ne l'est plus (un autre client a répondu en premier, ou le callback s'est fermé), et NotFound si la session ne l'a jamais ouvert. Un callback ouvert d'un sous-agent, répertorié dans le Blocked.callbacks de la racine, reçoit une réponse dans la session du sous-agent, et l'enregistrement désigne cette session ; une fois le callback fermé, la racine renvoie NotFound et la session du sous-agent lui-même, agent.session(callback.session_id), renvoie AlreadySettled.

Pour une approbation, Answered.answer est la réponse prise en compte : deux clients qui répondent simultanément reçoivent tous deux Answered, avec la réponse du premier arrivé. Vous devez donc la comparer à la vôtre. Elle vaut None si la réponse prise en compte n'a pas pu être lue à temps ; lisez le tour pour connaître le résultat. Pour un appel d'outil côté client et une demande de connexion, elle vaut None : le premier résultat envoyé est pris en compte. Les sessions locales et déployées fonctionnent de la même manière.

La valeur answer d'une approbation est AllowApproval ou DenyApproval, jamais un booléen, un dictionnaire ou None. KeepCallbackOpen() est une valeur de retour de gestionnaire, jamais une réponse : pour laisser un callback ouvert, n'y répondez pas.

async def interrupt() -> Turn | TurnConflict

async def interrupt() -> Turn | TurnConflict

Arrête ce tour ; la session reste ouverte pour de nouveaux tours.

Renvoie TurnConflict lorsque ce tour n'est plus le tour actif.

class SessionInput(pydantic.BaseModel)

class SessionInput(pydantic.BaseModel)

Une valeur que vous transmettez au démarrage d'une session et que les outils et les hooks peuvent lire.

Créez une sous-classe avec les champs nécessaires, par exemple un dépôt ou une organisation, et définissez input_id. Un outil, un hook ou un hook de sandbox la lit au moyen d'un paramètre annoté Annotated[YourInput, agents.Depends()] ; le modèle ne la voit jamais. N'y placez jamais d'identifiant d'authentification : la session la conserve pendant toute sa durée de vie.

Une règle exprimée uniquement par un validateur est vérifiée à l'endroit où la valeur est utilisée, et le rejet d'une valeur fait échouer cette utilisation. N'incluez jamais la valeur dans le message d'un validateur, car ce message est transmis aux résultats des tours et au modèle.

Une session conserve ses entrées pendant toute sa durée de vie, y compris lors de nouveaux déploiements de l'agent. Toute modification d'une classe doit donc continuer d'accepter les valeurs acceptées par sa version précédente.

class Depends()

class Depends()

Marque un paramètre Annotated comme entrée de session : Annotated[T, agents.Depends()].

Le type annoté T est la classe d'entrée, déclarée une seule fois.

type HistoryImportEntry = (
    HistoryImportMessage
    | HistoryImportReasoning
    | HistoryImportToolCall
    | HistoryImportToolResult
    | HistoryImportSnapshot
)

type HistoryImportEntry = (
    HistoryImportMessage
    | HistoryImportReasoning
    | HistoryImportToolCall
    | HistoryImportToolResult
    | HistoryImportSnapshot
)

Une entrée d'historique qui initialise une nouvelle session, telle qu'acceptée par history= : un message, le raisonnement du modèle, un appel d'outil, un résultat d'outil ou un instantané. Fournissez chaque entrée sous la forme d'une des classes ci-dessous, ou d'un dictionnaire contenant les mêmes champs, en snake case ou en camelCase, avec son type : "message", "reasoning", "tool_call", "tool_result" ou "snapshot".

class HistoryImportMessage(
    *,
    role: Literal['system', 'user', 'assistant'],
    content: list[ContentBlock] = [],
)

class HistoryImportMessage(
    *,
    role: Literal['system', 'user', 'assistant'],
    content: list[ContentBlock] = [],
)

Un message de l'historique : ce qu'a dit l'utilisateur, le modèle ou le système.

class HistoryImportReasoning(*, text: str)

class HistoryImportReasoning(*, text: str)

Le raisonnement du modèle, sous forme d'entrée d'historique.

class HistoryImportToolCall(
    *,
    tool_call_id: str,
    tool_kind: Literal['builtin', 'local', 'mcp', 'client', 'plugin', 'connector'] = 'local',
    name: str,
    arguments: JsonValue = None,
)

class HistoryImportToolCall(
    *,
    tool_call_id: str,
    tool_kind: Literal['builtin', 'local', 'mcp', 'client', 'plugin', 'connector'] = 'local',
    name: str,
    arguments: JsonValue = None,
)

Un appel d'outil effectué par le modèle, sous forme d'entrée d'historique.

class HistoryImportToolResult(
    *,
    tool_call_id: str,
    name: str | None = None,
    result: JsonValue = None,
    error: ProtocolError | None = None,
    annotations: dict[str, JsonValue] = {},
)

class HistoryImportToolResult(
    *,
    tool_call_id: str,
    name: str | None = None,
    result: JsonValue = None,
    error: ProtocolError | None = None,
    annotations: dict[str, JsonValue] = {},
)

Le résultat d'un appel d'outil, sous forme d'entrée d'historique : result ou error, mais pas les deux.

class HistoryImportSnapshot(*, task_name: str, snapshot_type: str, value: JsonValue = None)

class HistoryImportSnapshot(*, task_name: str, snapshot_type: str, value: JsonValue = None)

Des données enregistrées dans l'historique que le modèle ne voit pas. L'historique de la session les présente comme une entrée agents.UnknownEntry de type "checkpoint" : raw["message"] vaut task_name:snapshot_type, et raw["details"] vaut value.

class TextContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    text: str = '',
)

class TextContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    text: str = '',
)

Un bloc de texte.

class ImageContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    media_type: str | None = None,
    alt_text: str | None = None,
)

class ImageContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    media_type: str | None = None,
    alt_text: str | None = None,
)

Une image, référencée par une URI.

@classmethod
def from_bytes(
    data: bytes,
    media_type: str | None = None,
    *,
    alt_text: str | None = None,
    annotations: ContentAnnotations | None = None,
) -> ImageContentBlock

@classmethod
def from_bytes(
    data: bytes,
    media_type: str | None = None,
    *,
    alt_text: str | None = None,
    annotations: ContentAnnotations | None = None,
) -> ImageContentBlock

Une image intégrée ; le type de média est déterminé à partir des octets PNG, JPEG, GIF ou WebP.

@classmethod
def from_path(
    path: str | PathLike[str],
    media_type: str | None = None,
    *,
    alt_text: str | None = None,
    annotations: ContentAnnotations | None = None,
) -> ImageContentBlock

@classmethod
def from_path(
    path: str | PathLike[str],
    media_type: str | None = None,
    *,
    alt_text: str | None = None,
    annotations: ContentAnnotations | None = None,
) -> ImageContentBlock

Une image intégrée, lue depuis un fichier local. Sa représentation en base64 est limitée à 10 000 000 caractères, soit un fichier d'environ 7,5 Mo ; un fichier plus volumineux lève ValueError.

class AudioContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    media_type: str | None = None,
)

class AudioContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    media_type: str | None = None,
)

Un extrait audio, référencé par une URI.

class ResourceLinkContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    name: str | None = None,
    title: str | None = None,
    description: str | None = None,
    media_type: str | None = None,
    size: int | None = None,
)

class ResourceLinkContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    name: str | None = None,
    title: str | None = None,
    description: str | None = None,
    media_type: str | None = None,
    size: int | None = None,
)

Un lien vers une ressource, par exemple un fichier, dont le contenu n'est pas inclus dans le bloc.

class EmbeddedResourceContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    media_type: str | None = None,
    text: str | None = None,
    blob: str | None = None,
)

class EmbeddedResourceContentBlock(
    *,
    annotations: ContentAnnotations | None = None,
    meta: dict[str, JsonValue] | None = None,
    uri: str,
    media_type: str | None = None,
    text: str | None = None,
    blob: str | None = None,
)

Une ressource, par exemple un fichier, dont le contenu est inclus dans le bloc sous forme de texte ou de données encodées en base64.

class UnknownContentBlock(*, original_type: str)

class UnknownContentBlock(*, original_type: str)

Un bloc de contenu dont le type a été ajouté après votre version du SDK. Son champ type vaut unknown, ce qui permet à un match sur type de continuer à fonctionner pour les blocs connus ; original_type indique son type d'origine, et ses autres champs sont conservés tels qu'ils ont été reçus. L'entrée d'un tour ne peut pas contenir ce type de bloc.

class ContentAnnotations(
    *,
    audience: list[Literal['user', 'assistant'] | str] | None = None,
    priority: float | None = None,
    last_modified: str | None = None,
)

class ContentAnnotations(
    *,
    audience: list[Literal['user', 'assistant'] | str] | None = None,
    priority: float | None = None,
    last_modified: str | None = None,
)

Annotations MCP d'un bloc : le public auquel il est destiné et son importance.

Un bloc de résultat d'outil dont le public exclut "assistant" n'est jamais envoyé au modèle ; un client peut masquer un bloc dont le public exclut "user". priority doit être compris entre 0 et 1.