Lifecycle

RunHooks module-attribute

RunHooks = RunHooksBase[TContext, Agent]

Run hooks when using Agent.

AgentHooks module-attribute

AgentHooks = AgentHooksBase[TContext, Agent]

Agent hooks for Agents.

RunHooksBase

Bases: Generic[TContext, TAgent]

A class that receives callbacks on various lifecycle events in an agent run. Subclass and override the methods you need.

on_llm_start async

on_llm_start(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    system_prompt: str | None,
    input_items: list[TResponseInputItem],
) -> None

Called just before invoking the LLM for this agent.

on_llm_end async

on_llm_end(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    response: ModelResponse,
) -> None

Called immediately after the LLM call returns for this agent.

on_agent_start async

on_agent_start(
    context: AgentHookContext[TContext], agent: TAgent
) -> None

Called before the agent is invoked. Called each time the current agent changes.

Keep agent.tools unchanged when sharing an agent across concurrent runs. Tool-list replacement while concurrent runs use the same agent raises UserError before newly resolved tools reach the model. In-place mutations of a shared list are not isolated. Changes to shared tool objects, including FunctionTool.is_enabled and FunctionTool.needs_approval, are not isolated or detected. For per-run configuration changes, use an independent agent, tools list, and tool objects. Copying only the list still shares its tool objects. Alternatively, keep the tool configuration unchanged and use context-based enablement and approval callbacks.

When restoring a serialized RunState, rebuild any hook-created tools on the supplied agents before loading the state. Serialized state does not contain Python tool definitions, and start hooks are not replayed before pending approval calls are resolved.

Parameters:

Name	Type	Description	Default
context	AgentHookContext[TContext]	The agent hook context.	required
agent	TAgent	The agent that is about to be invoked.	required

on_agent_end async

on_agent_end(
    context: AgentHookContext[TContext],
    agent: TAgent,
    output: Any,
) -> None

Called when the agent produces a final output.

Parameters:

Name	Type	Description	Default
context	AgentHookContext[TContext]	The agent hook context.	required
agent	TAgent	The agent that produced the output.	required
output	Any	The final output produced by the agent.	required

on_handoff async

on_handoff(
    context: RunContextWrapper[TContext],
    from_agent: TAgent,
    to_agent: TAgent,
) -> None

Called when a handoff occurs.

on_tool_start async

on_tool_start(
    context: RunContextWrapper[TContext],
    agent: TAgent,
    tool: Tool,
) -> None

Called immediately before a local tool is invoked.

For function-tool invocations, context is typically a ToolContext instance, which exposes tool-call-specific metadata such as tool_call_id, tool_name, and tool_arguments. Other local tool families may provide a plain RunContextWrapper instead.

on_tool_end async

on_tool_end(
    context: RunContextWrapper[TContext],
    agent: TAgent,
    tool: Tool,
    result: object,
) -> None

Called immediately after a local tool is invoked.

For function-tool invocations, context is typically a ToolContext instance, which exposes tool-call-specific metadata such as tool_call_id, tool_name, and tool_arguments. Other local tool families may provide a plain RunContextWrapper instead.

Simple tool outputs are typically str values. Function tools may also return structured tool output objects or any value the SDK can stringify before sending it to the model.

AgentHooksBase

Bases: Generic[TContext, TAgent]

A class that receives callbacks on various lifecycle events for a specific agent. You can set this on agent.hooks to receive events for that specific agent.

Subclass and override the methods you need.

on_start async

on_start(
    context: AgentHookContext[TContext], agent: TAgent
) -> None

Called before the agent is invoked. Called each time the running agent is changed to this agent.

Keep agent.tools unchanged when sharing an agent across concurrent runs. Tool-list replacement while concurrent runs use the same agent raises UserError before newly resolved tools reach the model. In-place mutations of a shared list are not isolated. Changes to shared tool objects, including FunctionTool.is_enabled and FunctionTool.needs_approval, are not isolated or detected. For per-run configuration changes, use an independent agent, tools list, and tool objects. Copying only the list still shares its tool objects. Alternatively, keep the tool configuration unchanged and use context-based enablement and approval callbacks.

When restoring a serialized RunState, rebuild any hook-created tools on the supplied agents before loading the state. Serialized state does not contain Python tool definitions, and start hooks are not replayed before pending approval calls are resolved.

Parameters:

Name	Type	Description	Default
context	AgentHookContext[TContext]	The agent hook context.	required
agent	TAgent	This agent instance.	required

on_end async

on_end(
    context: AgentHookContext[TContext],
    agent: TAgent,
    output: Any,
) -> None

Called when the agent produces a final output.

Parameters:

Name	Type	Description	Default
context	AgentHookContext[TContext]	The agent hook context.	required
agent	TAgent	This agent instance.	required
output	Any	The final output produced by the agent.	required

on_handoff async

on_handoff(
    context: RunContextWrapper[TContext],
    agent: TAgent,
    source: TAgent,
) -> None

Called when the agent is being handed off to. The source is the agent that is handing off to this agent.

on_tool_start async

on_tool_start(
    context: RunContextWrapper[TContext],
    agent: TAgent,
    tool: Tool,
) -> None

Called immediately before a local tool is invoked.

For function-tool invocations, context is typically a ToolContext instance, which exposes tool-call-specific metadata such as tool_call_id, tool_name, and tool_arguments. Other local tool families may provide a plain RunContextWrapper instead.

on_tool_end async

on_tool_end(
    context: RunContextWrapper[TContext],
    agent: TAgent,
    tool: Tool,
    result: object,
) -> None

Called immediately after a local tool is invoked.

For function-tool invocations, context is typically a ToolContext instance, which exposes tool-call-specific metadata such as tool_call_id, tool_name, and tool_arguments. Other local tool families may provide a plain RunContextWrapper instead.

Simple tool outputs are typically str values. Function tools may also return structured tool output objects or any value the SDK can stringify before sending it to the model.

on_llm_start async

on_llm_start(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    system_prompt: str | None,
    input_items: list[TResponseInputItem],
) -> None

Called immediately before the agent issues an LLM call.

on_llm_end async

on_llm_end(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    response: ModelResponse,
) -> None

Called immediately after the agent receives the LLM response.