Hooks et contextes

Hooks qui modifient la boucle de l'agent, contextes reçus par votre code et fonctions utilitaires qui renvoient les mêmes valeurs lorsqu'un agent déployé exécute à nouveau la boucle.

Fournissez le contenu du résultat d'un hook sous forme de blocs de contenu, comme agents.TextContentBlock(text="..."), ou utilisez agents.skip(reason), agents.retry(feedback) et agents.reject(reason) avec une chaîne de caractères.

Guide : Les mécanismes de contrôle.

class Hook(*, tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any]] = (), **data: Any)

class Hook(*, tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any]] = (), **data: Any)

Code exécuté à différents points de la boucle de l'agent : avant et après chaque tour, appel au modèle et appel d'outil.

Redéfinissez les points d'exécution dont vous avez besoin ; renvoyer None poursuit l'exécution sans modification. Un hook est un modèle Pydantic. Ses champs constituent son état : la session conserve leurs valeurs et chaque appel démarre avec les valeurs laissées par le dernier appel réussi. Tout autre élément contenu dans le hook, comme un client, est un PrivateAttr, qui n'est jamais sauvegardé. __init__ ne s'exécute qu'à la création du hook : chaque appel démarre à partir d'une copie.

Une valeur sauvegardée enregistre sa classe, que le SDK retrouve parmi les modules déjà chargés. Le chargement d'une valeur n'importe jamais de module. Définissez chaque classe de hook, ainsi que la classe de chaque hook conservé dans un champ, au niveau du module, dans un module importé par celui de votre agent. Sinon, la création d'une session échoue. Conservez les hooks contenus dans un champ dans une liste ou un tuple. Un ensemble lève SdkError.

Un champ avec un alias, comme max_calls: int = Field(0, alias="maxCalls"), utilise son nom à la création du hook, Budget(max_calls=5), et son alias dans la valeur sauvegardée. Pour créer le hook également à partir de l'alias, définissez validate_by_alias=True dans model_config. La méthode model_validate de Pydantic lit un hook par nom de champ ; elle ne charge donc pas la valeur sauvegardée d'un hook dont un champ possède un alias.

async def pre_agent_turn(
    ctx: HookCallbackContext,
    request: hook.PreAgentTurn,
) -> hook.PreAgentTurnHookContinue | hook.PreAgentTurnHookSkip | HookDecision | None

async def pre_agent_turn(
    ctx: HookCallbackContext,
    request: hook.PreAgentTurn,
) -> hook.PreAgentTurnHookContinue | hook.PreAgentTurnHookSkip | HookDecision | None

S'exécute avant chaque tour, avec le contenu utilisateur du tour dans request.user_content.

Renvoyez hook.PreAgentTurnHookContinue pour envoyer un autre contenu, comme [*request.user_content, agents.TextContentBlock(text="...")], ou agents.skip ou hook.PreAgentTurnHookSkip pour ignorer le tour.

async def post_agent_turn(
    ctx: HookCallbackContext,
    result: hook.PostAgentTurn,
) -> hook.PostAgentTurnHookAccept | None

async def post_agent_turn(
    ctx: HookCallbackContext,
    result: hook.PostAgentTurn,
) -> hook.PostAgentTurnHookAccept | None

S'exécute après chaque tour, avec la réponse finale du modèle dans result : result.text, result.content.

Renvoyez hook.PostAgentTurnHookAccept() pour conserver la réponse, ou remplacez son contenu avec acceptance=hook.ReplaceAssistantContent(content=[agents.TextContentBlock(text="...")]).

async def pre_llm_call(
    ctx: HookCallbackContext,
    invocation: hook.PreLlmCall,
) -> hook.PreLlmCallHookContinue | hook.PreLlmCallHookSkip | HookDecision | None

async def pre_llm_call(
    ctx: HookCallbackContext,
    invocation: hook.PreLlmCall,
) -> hook.PreLlmCallHookContinue | hook.PreLlmCallHookSkip | HookDecision | None

S'exécute avant chaque appel au modèle. Renvoyez agents.skip ou hook.PreLlmCallHookSkip pour terminer le tour sans appeler le modèle (stop_reason="skipped").

async def post_llm_call(
    ctx: HookCallbackContext,
    invocation: hook.PostLlmCall,
) -> hook.PostLlmCallHookAccept | hook.PostLlmCallHookRetry | hook.PostLlmCallHookReject | HookDecision | None

async def post_llm_call(
    ctx: HookCallbackContext,
    invocation: hook.PostLlmCall,
) -> hook.PostLlmCallHookAccept | hook.PostLlmCallHookRetry | hook.PostLlmCallHookReject | HookDecision | None

S'exécute après chaque appel au modèle, avec sa réponse dans invocation : invocation.text, invocation.tool_calls, invocation.content.

Renvoyez hook.PostLlmCallHookAccept pour conserver la réponse ou remplacer son contenu, comme le fait hook.PostAgentTurnHookAccept, agents.retry pour appeler à nouveau le modèle avec des indications de correction, ou agents.reject pour terminer le tour.

async def pre_tool_call(
    ctx: HookCallbackContext,
    call: hook.PreToolCall,
) -> hook.PreToolCallHookContinue | hook.PreToolCallHookSkip | HookDecision | None

async def pre_tool_call(
    ctx: HookCallbackContext,
    call: hook.PreToolCall,
) -> hook.PreToolCallHookContinue | hook.PreToolCallHookSkip | HookDecision | None

S'exécute avant chaque appel d'outil, avec l'appel dans call.

Renvoyez hook.PreToolCallHookContinue pour exécuter l'outil avec d'autres effective_arguments, ou agents.skip ou hook.PreToolCallHookSkip pour ignorer l'appel : le modèle reçoit alors la raison à la place du résultat. L'entrée de l'appel d'outil dans l'historique affiche les arguments définis par le hook ; un appel ignoré conserve ceux du modèle.

async def post_tool_call(
    ctx: HookCallbackContext,
    result: hook.PostToolCall,
) -> hook.PostToolCallHookContinue | None

async def post_tool_call(
    ctx: HookCallbackContext,
    result: hook.PostToolCall,
) -> hook.PostToolCallHookContinue | None

S'exécute après chaque appel d'outil, avec l'appel et son résultat, un agents.ToolResult, dans result.

Renvoyez hook.PostToolCallHookContinue avec un autre tool_result pour modifier ce que le modèle reçoit, comme agents.ToolResult(content=[agents.TextContentBlock(text="...")]).

class HookDecision

class HookDecision

Décision d'un hook, convertie en résultat du point d'exécution qui la renvoie.

Créez-la avec agents.skip, agents.retry ou agents.reject.

def agents.skip(reason: str) -> HookDecision

def agents.skip(reason: str) -> HookDecision

Arrêter le tour, l'appel au modèle ou l'appel d'outil.

Depuis pre_tool_call, reason est ce que le modèle reçoit à la place du résultat de l'outil. Depuis pre_agent_turn ou pre_llm_call, le tour se termine avec stop_reason="skipped" et reason comme texte.

def agents.retry(feedback: str) -> HookDecision

def agents.retry(feedback: str) -> HookDecision

Ignorer la réponse du modèle et appeler à nouveau le modèle avec feedback.

def agents.reject(reason: str) -> HookDecision

def agents.reject(reason: str) -> HookDecision

Rejeter la réponse du modèle et terminer le tour avec reason.

Ce qu'un hook reçoit et renvoie à chaque point d'exécution : poursuivre ou remplacer l'entrée ou la sortie.

Un hook qui poursuit l'exécution sans modification renvoie None ; un hook qui l'arrête renvoie agents.skip, agents.retry ou agents.reject.

Ses classes sont présentées dans Classes de agents.hook.

class State(*, type: str, state: dict[str, JsonValue])

class State(*, type: str, state: dict[str, JsonValue])

Forme sauvegardée d'un hook ou d'une sandbox : son type et les données JSON conservées d'un tour à l'autre.

class PreAgentTurn(*, turn_id: str, user_content: list[ContentBlock])

class PreAgentTurn(*, turn_id: str, user_content: list[ContentBlock])

Le tour que reçoit un hook pre_agent_turn.

class PreLlmCall(*, turn_id: str)

class PreLlmCall(*, turn_id: str)

L'appel au modèle que reçoit un hook pre_llm_call.

class PostLlmCall(
    *,
    turn_id: str,
    content: list[ContentBlock],
    text: str,
    tool_calls: tuple[ToolCall, ...],
    reasoning: str,
    finish_reason: Literal['stop', 'tool_call', 'length', 'content_filter', 'other'],
    usage: TokenUsage | None,
)

class PostLlmCall(
    *,
    turn_id: str,
    content: list[ContentBlock],
    text: str,
    tool_calls: tuple[ToolCall, ...],
    reasoning: str,
    finish_reason: Literal['stop', 'tool_call', 'length', 'content_filter', 'other'],
    usage: TokenUsage | None,
)

La réponse du modèle que reçoit un hook post_llm_call.

class PostAgentTurn(
    *,
    turn_id: str,
    content: list[ContentBlock],
    text: str,
    tool_calls: tuple[ToolCall, ...],
    reasoning: str,
    finish_reason: Literal['stop', 'tool_call', 'length', 'content_filter', 'other'],
    usage: TokenUsage | None,
)

class PostAgentTurn(
    *,
    turn_id: str,
    content: list[ContentBlock],
    text: str,
    tool_calls: tuple[ToolCall, ...],
    reasoning: str,
    finish_reason: Literal['stop', 'tool_call', 'length', 'content_filter', 'other'],
    usage: TokenUsage | None,
)

La réponse finale du tour que reçoit un hook post_agent_turn.

class PreToolCall(
    *,
    turn_id: str,
    tool_name: str,
    tool_id: str,
    tool_call_id: str,
    arguments: dict[str, JsonValue],
)

class PreToolCall(
    *,
    turn_id: str,
    tool_name: str,
    tool_id: str,
    tool_call_id: str,
    arguments: dict[str, JsonValue],
)

L'appel d'outil que reçoit un hook pre_tool_call.

class PostToolCall(
    *,
    turn_id: str,
    tool_name: str,
    tool_id: str,
    tool_call_id: str,
    arguments: dict[str, JsonValue],
    tool_result: ToolResult,
)

class PostToolCall(
    *,
    turn_id: str,
    tool_name: str,
    tool_id: str,
    tool_call_id: str,
    arguments: dict[str, JsonValue],
    tool_result: ToolResult,
)

L'appel d'outil et son résultat que reçoit un hook post_tool_call.

Hérite de turn_id, tool_name, tool_id et tool_call_id de hook.PreToolCall.

class PreAgentTurnHookContinue(*, user_content: Sequence[ContentBlock])

class PreAgentTurnHookContinue(*, user_content: Sequence[ContentBlock])

Ce que renvoie pre_agent_turn pour démarrer le tour avec un autre contenu utilisateur.

class PreAgentTurnHookSkip(*, reason: Sequence[ContentBlock] = [])

class PreAgentTurnHookSkip(*, reason: Sequence[ContentBlock] = [])

Ce que renvoie pre_agent_turn pour terminer le tour avant l'exécution du modèle, comme le fait agents.skip.

class PreLlmCallHookContinue()

class PreLlmCallHookContinue()

Ce que renvoie pre_llm_call pour autoriser l'exécution de l'appel au modèle, comme le fait None.

class PreLlmCallHookSkip(*, reason: Sequence[ContentBlock] = [])

class PreLlmCallHookSkip(*, reason: Sequence[ContentBlock] = [])

Ce que renvoie pre_llm_call pour terminer le tour au lieu d'appeler le modèle, comme le fait agents.skip.

class PostLlmCallHookAccept(*, acceptance: ReplaceAssistantContent = ...)

class PostLlmCallHookAccept(*, acceptance: ReplaceAssistantContent = ...)

Ce que renvoie post_llm_call pour conserver la réponse du modèle ou remplacer son contenu.

class PostLlmCallHookRetry(*, feedback: Sequence[ContentBlock])

class PostLlmCallHookRetry(*, feedback: Sequence[ContentBlock])

Ce que renvoie post_llm_call pour supprimer la réponse et appeler à nouveau le modèle, comme le fait agents.retry.

class PostLlmCallHookReject(*, reason: Sequence[ContentBlock])

class PostLlmCallHookReject(*, reason: Sequence[ContentBlock])

Ce que renvoie post_llm_call pour rejeter la réponse et terminer le tour, comme le fait agents.reject.

class PreToolCallHookContinue(*, effective_arguments: dict[str, JsonValue] = {})

class PreToolCallHookContinue(*, effective_arguments: dict[str, JsonValue] = {})

Ce que renvoie pre_tool_call pour exécuter l'outil avec d'autres arguments. Passez effective_arguments= ; sans arguments fournis, l'outil s'exécute sans arguments.

class PreToolCallHookSkip(*, reason: Sequence[ContentBlock] = [])

class PreToolCallHookSkip(*, reason: Sequence[ContentBlock] = [])

Ce que renvoie pre_tool_call pour ignorer l'appel, comme le fait agents.skip.

class PostToolCallHookContinue(*, tool_result: ToolResult)

class PostToolCallHookContinue(*, tool_result: ToolResult)

Ce que renvoie post_tool_call pour fournir au modèle un autre résultat d'outil.

class PostAgentTurnHookAccept(*, acceptance: ReplaceAssistantContent = ...)

class PostAgentTurnHookAccept(*, acceptance: ReplaceAssistantContent = ...)

Ce que renvoie post_agent_turn pour conserver la réponse finale ou remplacer son contenu.

class ReplaceAssistantContent(*, content: Sequence[ContentBlock])

class ReplaceAssistantContent(*, content: Sequence[ContentBlock])

Remplacez la réponse du modèle par content, depuis post_llm_call ou post_agent_turn.

class StructuredOutputHook[T](
    *,
    tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any]] = (),
    **data: Any,
)

class StructuredOutputHook[T](
    *,
    tools: Sequence[PythonTool[..., Any] | ClientTool[..., Any]] = (),
    **data: Any,
)

Validez la réponse finale de chaque tour avec un modèle Pydantic, et demandez au modèle de la corriger.

Indiquez le modèle Pydantic entre crochets, comme dans StructuredOutputHook[City](max_retries=2), ou créez une sous-classe de StructuredOutputHook[City] et définissez de nouvelles valeurs par défaut pour ses champs.

Le hook ne demande une correction que si max_retries le permet et s'il reste au tour une itération dans la limite max_iterations de l'agent. Une fois cette limite atteinte, il accepte la dernière réponse ou, si on_limit vaut "reject", lève ValueError, ce qui fait échouer le tour. Définissez schema_in_prompt sur False pour exclure le schéma JSON du message utilisateur, par exemple si output_type le fournit déjà au modèle ; les corrections l'incluent toujours. Définissez enabled sur False pour accepter les réponses sans vérification.

Le hook compte chaque appel au modèle avant son exécution. Un appel relancé par un mécanisme de contrôle ou un hook précédent compte donc aussi dans la limite max_iterations.

Basé sur Hook.

class CallbackContext

class CallbackContext

Ce qu'un callback reçoit dans ctx : la session dans laquelle il s'exécute et la sandbox de cette session.

La base commune : une méthode de hook reçoit un HookCallbackContext, et un outil un ToolCallbackContext.

class CallbackSession

class CallbackSession

La session dans laquelle un callback s'exécute : son identifiant et celui du tour.

class HookCallbackContext(CallbackContext)

class HookCallbackContext(CallbackContext)

Ce qu'une méthode de hook reçoit dans ctx : la session dans laquelle elle s'exécute et la sandbox de cette session.

class ToolCallbackContext(CallbackContext)

class ToolCallbackContext(CallbackContext)

Ce qu'un outil reçoit comme premier paramètre, exclusivement positionnel : la session, sa sandbox et l'appel.

Un outil le reçoit selon son type, quel que soit son nom : def search(ctx: agents.ToolCallbackContext, /, query: str). Le modèle ne le voit jamais. Un appel direct peut passer ToolCallbackContext.local(), ou l'omettre pour obtenir ce contexte local. La réponse d'un outil client le reçoit aussi, sans sandbox ; les méthodes de ctx.sandbox lèvent donc RuntimeError.

@classmethod
def local() -> ToolCallbackContext

@classmethod
def local() -> ToolCallbackContext

Un contexte pour un appel en dehors de toute session : chaque identifiant vaut "local" et la sandbox n'est pas liée.

class ApprovalCallbackContext(CallbackContext)

class ApprovalCallbackContext(CallbackContext)

Ce qu'un gestionnaire d'approbation reçoit dans ctx : la session à l'origine de la demande et l'identifiant de l'approbation.

ctx.session.id et ctx.session.turn_id identifient la session et le tour à l'origine de la demande : une approbation de sous-agent contient la session du sous-agent et son propre tour. ctx.callback_id est l'identifiant de l'approbation, celui qu'accepte turn.answer. Le gestionnaire s'exécute dans votre programme ; les méthodes de ctx.sandbox lèvent donc RuntimeError.

class SandboxCallbackContext

class SandboxCallbackContext

Le contexte qu'un hook de sandbox reçoit dans on_create et on_destroy.

def agents.now() -> datetime

def agents.now() -> datetime

L'heure actuelle en UTC, sous forme de datetime avec fuseau horaire.

Utilisez cette fonction à la place de datetime.now(). Dans la boucle d'un agent déployé, par exemple dans les méthodes d'une sandbox personnalisée ou dans un SandboxHook, elle renvoie la même heure lorsque l'agent réexécute la boucle pour reprendre une session, ce qui préserve l'échéance. Dans un outil, un Hook ou une exécution locale, elle renvoie l'heure de l'horloge : les outils et les méthodes de Hook s'exécutent sous forme d'étapes enregistrées, en dehors de la partie de la boucle qu'un agent déployé rejoue.

async def agents.sleep(duration: timedelta | float, *, summary: str | None = None) -> None

async def agents.sleep(duration: timedelta | float, *, summary: str | None = None) -> None

Attendez pendant duration, dans la boucle de l'agent, un outil, un Hook ou une exécution locale.

Utilisez cette fonction à la place de asyncio.sleep(). Dans la boucle d'un agent déployé, par exemple dans les méthodes d'une sandbox personnalisée ou dans un SandboxHook, l'attente repose sur un minuteur côté serveur : elle persiste après un redémarrage de l'agent, et aucune partie de l'agent ne s'exécute pendant l'attente. Les outils et les méthodes de Hook s'exécutent sous forme d'étapes enregistrées, en dehors de la partie de la boucle qu'un agent déployé rejoue : dans ce cas, l'attente doit se terminer avant la limite de temps de l'étape. Dans une exécution locale, il s'agit de asyncio.sleep().

def agents.uuid4() -> UUID

def agents.uuid4() -> UUID

Un UUID aléatoire qui reste identique lorsqu'un agent déployé réexécute la boucle de l'agent.

Utilisez cette fonction à la place de uuid.uuid4(). Dans un outil, un Hook ou une exécution locale, il s'agit de uuid.uuid4().

def agents.random() -> Random

def agents.random() -> Random

Un générateur de nombres aléatoires qui produit les mêmes nombres lorsqu'un agent déployé réexécute la boucle.

Utilisez-le à la place du module random. Il propose des méthodes comme random, uniform, choice et shuffle. Dans un outil, un Hook ou une exécution locale, il s'agit d'une nouvelle instance de random.Random.