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.

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: str,
) -> 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.

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.

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: str,
) -> 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.

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.