Hooks and contexts

Hooks that change the agent loop, the contexts your code gets, and the helpers that give the same values when a deployed agent runs the loop again.

Give a hook result's content as content blocks, such as agents.TextContentBlock(text="..."), or use agents.skip(reason), agents.retry(feedback) and agents.reject(reason) with a string.

Guide: Guardrails.

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

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

Code that runs at points of the agent loop: before and after each turn, model call and tool call.

Override the points you need; returning None continues unchanged. A hook is a Pydantic model. Its fields are its state: the session keeps their values and every call starts from the values the last successful call left. Anything else the hook holds, such as a client, is a PrivateAttr, which is never saved. __init__ runs only when you build the hook: each call starts from a copy.

A saved value records its class, and the SDK finds the class again among the modules already loaded. Loading a value never imports a module. Define every hook class, and the class of every hook kept in a field, at module level, in a module your agent's module imports. Otherwise, creating a session fails. Keep hooks held in a field in a list or a tuple. A set raises SdkError.

A field with an alias, such as max_calls: int = Field(0, alias="maxCalls"), takes its name when you build the hook, Budget(max_calls=5), and its alias in the saved value. To build the hook by alias too, set validate_by_alias=True in model_config. Pydantic's own model_validate reads a hook by field name, so it does not load the saved value of a hook with an aliased field.

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

Runs before each turn, with its user content in request.user_content.

Return hook.PreAgentTurnHookContinue to send other content, such as [*request.user_content, agents.TextContentBlock(text="...")], or agents.skip or hook.PreAgentTurnHookSkip to skip the turn.

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

Runs after each turn, with the model's final answer in result: result.text, result.content.

Return hook.PostAgentTurnHookAccept() to keep the answer, or replace its content with 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

Runs before each model call. Return agents.skip or hook.PreLlmCallHookSkip to end the turn without calling the model (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

Runs after each model call, with its response in invocation: invocation.text, invocation.tool_calls, invocation.content.

Return hook.PostLlmCallHookAccept to keep the response or replace its content, as hook.PostAgentTurnHookAccept does, agents.retry to call the model again with feedback, or agents.reject to end the turn.

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

Runs before each tool call, with the call in call.

Return hook.PreToolCallHookContinue to run the tool with other effective_arguments, or agents.skip or hook.PreToolCallHookSkip to skip the call: the model sees the reason instead. The history's tool call entry shows the arguments the hook set; a skipped call keeps the model's.

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

Runs after each tool call, with the call and its result, an agents.ToolResult, in result.

Return hook.PostToolCallHookContinue with another tool_result to change what the model gets, such as agents.ToolResult(content=[agents.TextContentBlock(text="...")]).

class HookDecision

class HookDecision

A hook's decision, turned into the result of the point that returns it.

Build it with agents.skip, agents.retry or agents.reject.

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

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

Stop the turn, model call or tool call.

From pre_tool_call, reason is what the model sees in place of the tool result. From pre_agent_turn or pre_llm_call, the turn ends with stop_reason="skipped" and reason as its text.

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

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

Discard the model's response and call the model again with feedback.

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

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

Reject the model's response and end the turn with reason.

What a hook gets at each point and returns: continue, or replace the input or output.

A hook that continues unchanged returns None; one that stops returns agents.skip, agents.retry or agents.reject.

Its classes are under Classes of agents.hook.

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

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

The saved form of a hook or sandbox: its type, and the JSON data it keeps across turns.

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

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

The turn a pre_agent_turn hook receives.

class PreLlmCall(*, turn_id: str)

class PreLlmCall(*, turn_id: str)

The model call a pre_llm_call hook receives.

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

The model reply a post_llm_call hook receives.

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

The final answer of the turn a post_agent_turn hook receives.

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

The tool call a pre_tool_call hook receives.

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

The tool call and result a post_tool_call hook receives.

Inherits turn_id, tool_name, tool_id and tool_call_id from hook.PreToolCall.

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

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

What pre_agent_turn returns to start the turn with other user content.

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

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

What pre_agent_turn returns to end the turn before the model runs, as agents.skip does.

class PreLlmCallHookContinue()

class PreLlmCallHookContinue()

What pre_llm_call returns to let the model call run, as None does.

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

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

What pre_llm_call returns to end the turn instead of calling the model, as agents.skip does.

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

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

What post_llm_call returns to keep the model's response, or to replace its content.

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

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

What post_llm_call returns to drop the response and call the model again, as agents.retry does.

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

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

What post_llm_call returns to reject the response and end the turn, as agents.reject does.

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

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

What pre_tool_call returns to run the tool with other arguments. Pass effective_arguments=; with none, the tool runs with no arguments.

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

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

What pre_tool_call returns to skip the call, as agents.skip does.

class PostToolCallHookContinue(*, tool_result: ToolResult)

class PostToolCallHookContinue(*, tool_result: ToolResult)

What post_tool_call returns to give the model another tool result.

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

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

What post_agent_turn returns to keep the final answer, or to replace its content.

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

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

Replace the model's reply with content, from post_llm_call or 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,
)

Validate the final answer of each turn with a Pydantic model, and ask the model to correct it.

Name the Pydantic model in brackets, as in StructuredOutputHook[City](max_retries=2), or subclass StructuredOutputHook[City] and set new defaults for its fields.

The hook asks for a correction only while max_retries allows it and the turn has an iteration left under the agent's max_iterations. At that limit it accepts the last answer, or, when on_limit is "reject", raises ValueError, which fails the turn. Set schema_in_prompt to False to leave the JSON Schema out of the user message, for example when output_type already gives it to the model; corrections still include it. Set enabled to False to let answers through unchecked.

The hook counts each model call before it is made, so a call that a guardrail or an earlier hook retries still counts toward max_iterations.

Based on Hook.

class CallbackContext

class CallbackContext

What a callback gets as ctx: the session it runs in and the session's sandbox.

The shared base: a hook method gets a HookCallbackContext, and a tool a ToolCallbackContext.

class CallbackSession

class CallbackSession

The session a callback runs in: its ID and the turn's.

class HookCallbackContext(CallbackContext)

class HookCallbackContext(CallbackContext)

What a hook method gets as ctx: the session it runs in and the session's sandbox.

class ToolCallbackContext(CallbackContext)

class ToolCallbackContext(CallbackContext)

What a tool gets as its first, positional-only parameter: the session, its sandbox and the call.

A tool takes it by type, under any name: def search(ctx: agents.ToolCallbackContext, /, query: str). The model never sees it. A direct call can pass ToolCallbackContext.local(), or leave it out to get that local context. A client tool's answer gets it too, with no sandbox, so the methods of ctx.sandbox raise RuntimeError.

@classmethod
def local() -> ToolCallbackContext

@classmethod
def local() -> ToolCallbackContext

A context for a call outside any session: every ID is "local" and the sandbox is unbound.

class ApprovalCallbackContext(CallbackContext)

class ApprovalCallbackContext(CallbackContext)

What an approval handler gets as ctx: the session that asked, and the approval's ID.

ctx.session.id and ctx.session.turn_id name the session and turn that asked: a subagent's approval has the subagent's session and its own turn there. ctx.callback_id is the approval's ID, the one turn.answer takes. The handler runs in your program, so the methods of ctx.sandbox raise RuntimeError.

class SandboxCallbackContext

class SandboxCallbackContext

Context a sandbox hook receives in on_create and on_destroy.

def agents.now() -> datetime

def agents.now() -> datetime

The current time in UTC, as a timezone-aware datetime.

Use it instead of datetime.now(). In the agent loop of a deployed agent, such as in a custom sandbox's methods or a SandboxHook, it gets the same time when the agent runs the loop again to resume a session, so a deadline holds. In a tool, a Hook or a local run, it is the clock's time: tools and Hook methods run as recorded steps, outside the part of the loop a deployed agent replays.

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

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

Wait for duration, in the agent loop, a tool, a Hook or a local run.

Use it instead of asyncio.sleep(). In the agent loop of a deployed agent, such as in a custom sandbox's methods or a SandboxHook, the wait is a timer on the server: it survives a restart of the agent, and nothing of the agent runs while it waits. Tools and Hook methods run as recorded steps, outside the part of the loop a deployed agent replays: there the wait must end within the step's time limit. In a local run, it is asyncio.sleep().

def agents.uuid4() -> UUID

def agents.uuid4() -> UUID

A random UUID that stays the same when a deployed agent runs the agent loop again.

Use it instead of uuid.uuid4(). In a tool, a Hook or a local run, it is uuid.uuid4().

def agents.random() -> Random

def agents.random() -> Random

A random number generator that gives the same numbers when a deployed agent runs the loop again.

Use it instead of the random module. It has methods such as random, uniform, choice and shuffle. In a tool, a Hook or a local run, it is a new random.Random.