Enregistrements de tour

Ce que renvoie la lecture ou l'attente d'un tour : un TurnState, l'un des six enregistrements, et les valeurs renvoyées par les appels qui démarrent, orientent ou interrompent un tour.

Guides : Tours et Statuts de session.

type TurnState[T] = Running | Blocked | Completed[T] | Interrupted | Failed | UnknownOutcome

type TurnState[T] = Running | Blocked | Completed[T] | Interrupted | Failed | UnknownOutcome

L'état d'un tour à la position cursor : l'un des six enregistrements Running, Blocked, Completed, Interrupted, Failed et UnknownOutcome.

class Running(*, session_id: str, turn_id: str, cursor: str, text: str | None)

class Running(*, session_id: str, turn_id: str, cursor: str, text: str | None)

Le tour est en cours d'exécution. Aucune action n'est attendue de votre part.

class Blocked(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    callbacks: tuple[OpenCallback, ...],
)

class Blocked(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    callbacks: tuple[OpenCallback, ...],
)

Le tour attend une réponse à un ou plusieurs callbacks.

class Completed[T](
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    output: T | InvalidOutput | None,
    stop_reason: str | None = None,
    tool_calls: tuple[ToolCall, ...] = (),
)

class Completed[T](
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    output: T | InvalidOutput | None,
    stop_reason: str | None = None,
    tool_calls: tuple[ToolCall, ...] = (),
)

Le tour est terminé, éventuellement de manière anticipée : voir stop_reason.

Avec output_type, output vaut None lorsque le tour s'est terminé de manière anticipée : il n'y a donc aucune réponse à analyser. Sans output_type, il contient le texte du tour, même si le tour s'est terminé de manière anticipée (le texte d'un tour ignoré est le motif fourni par le hook, celui d'un tour tronqué est la réponse tronquée), ou "" en l'absence de texte.

class Interrupted(*, session_id: str, turn_id: str, cursor: str, text: str | None, cause: str)

class Interrupted(*, session_id: str, turn_id: str, cursor: str, text: str | None, cause: str)

Le tour s'est arrêté avant de se terminer.

Lorsqu'aucune cause n'est fournie, le SDK lit "cancelled" si le tour s'est terminé avec l'annulation de sa session, sinon "interrupted". text contient le texte produit par le tour avant son arrêt.

class Failed(*, session_id: str, turn_id: str, cursor: str, text: str | None, error: ProtocolError)

class Failed(*, session_id: str, turn_id: str, cursor: str, text: str | None, error: ProtocolError)

Le tour s'est terminé avec une erreur, par exemple un refus du fournisseur du modèle.

class UnknownOutcome(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    outcome: str,
    raw: dict[str, JsonValue] = {},
)

class UnknownOutcome(
    *,
    session_id: str,
    turn_id: str,
    cursor: str,
    text: str | None,
    outcome: str,
    raw: dict[str, JsonValue] = {},
)

Le tour s'est terminé avec une issue ajoutée après votre version du SDK, telle que "future_outcome".

Prévoyez un case pour cet enregistrement, pour que votre code continue de fonctionner lorsque de nouvelles issues sont ajoutées.

class ProtocolError(
    *,
    message: str,
    code: str | None = None,
    retryable: bool = False,
    details: dict[str, JsonValue] | None = None,
)

class ProtocolError(
    *,
    message: str,
    code: str | None = None,
    retryable: bool = False,
    details: dict[str, JsonValue] | None = None,
)

Une erreur provenant de l'environnement d'exécution de la session, comme celle qui a fait échouer un tour.

Le code de l'erreur d'un tour ayant échoué indique ce qui a échoué. Vous pouvez donc l'utiliser pour distinguer les cas :

• "completion_rejected" : le fournisseur du modèle a refusé la requête avec un statut HTTP 4xx autre que 401, 403, 408, 409 et 429, par exemple pour un modèle inconnu ou un paramètre invalide : corrigez la requête.
• "completion_unauthorized" : le fournisseur du modèle a refusé les identifiants (HTTP 401 ou 403). Aucune nouvelle tentative possible.
• "completion_rate_limited" : le nombre de requêtes dépasse votre limite de débit (HTTP 429 avec le motif rate_limited). Une nouvelle tentative est possible.
• "completion_unavailable" : le fournisseur du modèle n'a pas pu traiter la requête : aucune capacité disponible pour le modèle (HTTP 409, ou tout autre 429), une panne ou une erreur serveur. Une nouvelle tentative est possible si la cause est temporaire, par exemple HTTP 502, 503 ou 504.
• "completion_timed_out" : le fournisseur a répondu HTTP 408, le modèle a cessé de produire une sortie, ou l'appel a dépassé sa limite de durée. Une nouvelle tentative est possible, sauf si l'appel a dépassé sa limite de durée.
• "completion_context_too_large" : la requête dépasse la fenêtre de contexte du modèle. Aucune nouvelle tentative possible, sauf si le fournisseur la refuse à nouveau juste après une compaction du contexte, ou refuse même la plus petite requête de compaction (details.reason vaut "after_compaction" ou "minimal_summary_request").
• "completion_billing_denied" : la facturation a refusé la requête, par exemple parce que le budget est épuisé. Aucune nouvelle tentative possible.
• "completion_failed" : l'appel au modèle a échoué sans statut HTTP, par exemple à cause d'une perte de connexion ou d'un flux terminé prématurément. Une nouvelle tentative est possible.
• "completion_failed_permanently" : l'appel au modèle a échoué sans statut HTTP et une nouvelle tentative ne résoudra pas le problème, par exemple si une réponse ne rapporte aucune utilisation de tokens : un serveur compatible avec OpenAI doit prendre en charge stream_options.include_usage. Aucune nouvelle tentative possible.
• "remote_session_failed" : une session accessible via une API ou déployée a échoué ou atteint sa limite de durée. La session est terminée : démarrez-en une nouvelle.
• "capability_execution_failed" : un hook autre que pre_tool_call ou post_tool_call a levé une exception, ou son état sauvegardé était trop volumineux. Le message se termine par le texte de l'exception. Aucune nouvelle tentative possible.
• "tool_raised" : un outil a levé une exception autre que agents.ToolError sur un agent avec tool_errors="raise". Le message indique le nom de l'outil et le type de l'exception. Aucune nouvelle tentative possible.
• "tool_output_schema_mismatch" : le résultat d'un outil n'était pas conforme à son output_schema= sur un agent avec tool_errors="raise". Aucune nouvelle tentative possible.
• "invalid_compaction_summary" : une compaction du contexte a échoué : le résumé du modèle était vide, comportait des délimiteurs <summary> mal formés, appelait des outils ou atteignait la limite de tokens de sortie. Aucune nouvelle tentative possible.
• "compaction_request_too_large" : une compaction du contexte n'a pas pu démarrer, car le contexte à envoyer dépasse le seuil de compaction. Aucune nouvelle tentative possible.
• "compaction_replacement_too_large" : le résumé et le contexte nécessaires au tour dépassent le seuil de compaction. Aucune nouvelle tentative possible.
• "turn_failed" : une erreur sans code dédié provenant d'un agent accessible via une API.

class InvalidOutput(*, raw: JsonValue, error: str)

class InvalidOutput(*, raw: JsonValue, error: str)

Le tour s'est terminé, mais sa sortie n'est pas conforme au type demandé.

class ToolCall(name: str, arguments: JsonValue)

class ToolCall(name: str, arguments: JsonValue)

Un appel d'outil effectué par le modèle pendant le tour.

name est l'identifiant complet de l'outil, par exemple client.get_weather, et non le nom utilisé par le modèle pour l'appeler. Un appel à un outil inexistant conserve le nom utilisé par le modèle. Dans les tool_calls d'un hook post_llm_call ou post_agent_turn, l'appel n'est pas encore résolu : name correspond donc au nom utilisé par le modèle, par exemple get_weather. Un appel qui n'a pas été exécuté figure aussi dans la liste : une règle d'autorisation l'a refusé, un utilisateur l'a rejeté lors de l'approbation, le délai d'approbation a expiré, un hook l'a ignoré ou a échoué en le traitant, l'agent l'a refusé (invalid_tool_call : arguments qui ne sont pas du JSON valide ou que le schéma rejette, outil inconnu, wait aux côtés d'autres appels) ou, dans run_typescript, ses arguments ne correspondaient pas au schéma d'entrée de l'outil ou la limite de temps du programme l'a arrêté avant son démarrage. arguments contient les arguments de l'appel : dans Completed.tool_calls, ceux définis par un hook pre_tool_call si présent, sinon ceux du modèle ; dans les tool_calls d'un hook, ceux du modèle. Les arguments qui ne sont pas du JSON valide sont représentés par la chaîne brute, et une session d'un agent déployé peut renvoyer n'importe quelle valeur JSON.

class TokenUsage(
    *,
    input_tokens: int,
    output_tokens: int,
    total_tokens: int,
    cached_input_tokens: int = 0,
    cache_write_tokens: int = 0,
    reasoning_tokens: int = 0,
)

class TokenUsage(
    *,
    input_tokens: int,
    output_tokens: int,
    total_tokens: int,
    cached_input_tokens: int = 0,
    cache_write_tokens: int = 0,
    reasoning_tokens: int = 0,
)

Les tokens utilisés par un appel au modèle, tels que rapportés par le fournisseur.

total_tokens est la somme de input_tokens et output_tokens. cached_input_tokens compte les tokens d'entrée lus dans le cache du fournisseur et fait partie de input_tokens.

class OpenCallback(*, id: str, session_id: str, turn_id: str, kind: str, title: str | None)

class OpenCallback(*, id: str, session_id: str, turn_id: str, kind: str, title: str | None)

Un callback dont le tour, ou l'un de ses sous-agents, attend la réponse : un OpenApproval, un OpenSignIn, un OpenClientToolCall ou un UnknownOpenCallback.

turn.answer accepte son id sur n'importe quel tour de sa session ou d'une session située au-dessus dans l'arborescence. Le callback d'un sous-agent porte les identifiants du sous-agent, y compris celui de son propre tour.

class OpenApproval(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    request: ApprovalRequest,
)

class OpenApproval(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    request: ApprovalRequest,
)

Une approbation que le tour attend.

Hérite de id, session_id, turn_id, kind et title de OpenCallback.

class OpenClientToolCall[P, R](
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    call: ClientToolCall,
)

class OpenClientToolCall[P, R](
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    call: ClientToolCall,
)

Un appel d'outil côté client dont le tour attend la réponse.

Vérifiez l'outil appelé avec <stub>.called(callback), puis répondez avec turn.answer(callback.id, await callback.run(fn)).

Hérite de id, session_id, turn_id, kind et title de OpenCallback.

async def run(
    fn: Callable[P, R | ToolResult[Any] | Awaitable[R | ToolResult[Any]]],
    /,
) -> R | ToolResult[Any]

async def run(
    fn: Callable[P, R | ToolResult[Any] | Awaitable[R | ToolResult[Any]]],
    /,
) -> R | ToolResult[Any]

Appelle fn avec les arguments de l'appel, validés par le stub de l'outil, et renvoie son résultat : la valeur qu'accepte turn.answer(callback.id, ...) pour cet appel.

fn accepte les paramètres du stub, sans contexte, et renvoie le type de retour du stub ou un agents.ToolResult, de manière synchrone ou asynchrone. Une fonction fn synchrone s'exécute dans un thread d'outil. Toute exception levée par fn se propage : tool_errors ne s'applique pas.

Lorsque les arguments du modèle ne correspondent pas au stub, fn n'est pas appelée : le résultat est un agents.ToolResult d'erreur qui en indique la raison. Répondre avec ce résultat permet au modèle de corriger l'appel.

class OpenSignIn(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    requests: tuple[SignInRequest, ...],
)

class OpenSignIn(
    *,
    id: str,
    session_id: str,
    turn_id: str,
    kind: str,
    title: str | None,
    requests: tuple[SignInRequest, ...],
)

Une connexion que le tour attend : l'agent demande à l'utilisateur de connecter une ou plusieurs sources, par exemple des connecteurs, avant d'utiliser leurs outils.

Répondez avec turn.answer(callback.id, agents.SignInAnswer(connected=..., denied=...)), en désignant chaque source par son id, ou avec un gestionnaire on_sign_in=, qui reçoit cet enregistrement. kind vaut "sign_in". on_client_tool ne reçoit jamais de demande de connexion.

Hérite de id, session_id, turn_id, kind et title de OpenCallback.

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

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

Un callback dont la catégorie n'a pas de type propre dans votre version du SDK.

Une version ultérieure du SDK peut attribuer un type propre à une catégorie. Faites la correspondance sur kind et laissez ouverts les callbacks des catégories que vous ne connaissez pas.

Hérite de id, session_id, turn_id, kind et title de OpenCallback.

class Busy(*, session_id: str, active_turn_id: str, turn: Turn)

class Busy(*, session_id: str, active_turn_id: str, turn: Turn)

Un nouveau tour n'a pas été démarré, car un autre tour de la session est actif.

Ce n'est pas un état de tour : aucun tour n'a été démarré.

class TurnConflict(*, session_id: str, expected_turn_id: str, active_turn_id: str | None)

class TurnConflict(*, session_id: str, expected_turn_id: str, active_turn_id: str | None)

Une requête désignait un tour qui n'est plus le tour actif de la session. Rien n'a été appliqué : la session a refusé la requête.