`on_llm_end` hook not being called for agents with handoffs

[muneebarshadd]

Title

on_llm_end hook not being called for agents with handoffs

Description

The on_llm_end hook in RunHooks is not being triggered when an agent uses handoffs to transfer to another agent, even though the hook is properly defined and other hooks (on_agent_start, on_handoff) are being called successfully.

Environment

• openai-agents version: 0.2.11
• Python version: 3.11

Expected Behavior

When an agent completes an LLM call, the on_llm_end hook should be triggered with the ModelResponse object, allowing access to the LLM's output before any handoff occurs.

Actual Behavior

The on_llm_end hook is never called. Only on_agent_start and on_handoff hooks are triggered.

Code Example

from agents import Agent, RunHooks, RunContextWrapper, ModelResponse

class MyAgentHooks(RunHooks):
    async def on_agent_start(self, context, agent):
        print("✅ on_agent_start called")  # This IS called
    
    async def on_llm_start(self, context, agent):
        print("❌ on_llm_start called")  # This is NEVER called
    
    async def on_llm_end(self, context, agent, response: ModelResponse):
        print("❌ on_llm_end called")  # This is NEVER called
        print(f"Response: {response}")
    
    async def on_handoff(self, context, agent, source):
        print("✅ on_handoff called")  # This IS called

# Agent with handoff
next_agent = Agent(name="next_agent", instructions="...")

my_agent = Agent(
    name="my_agent",
    instructions="Output text then call handoff tool",
    hooks=MyAgentHooks(),
    handoffs=[next_agent],
)

# Run the agent
result = Runner.run_streamed(my_agent, input="test query", context=my_context)

Observed Hook Execution Order

1. ✅ on_agent_start - Called
2. ❌ on_llm_start - Not verified
3. ❌ on_llm_end - NOT CALLED (this is the issue)
4. ✅ on_handoff - Called

[ihower]

@muneebarshadd There’s no bug here, and you’re just confusing two different kinds of hooks.

There are two kinds of hooks:

• AgentHooks: attached to the agent (Agent(hooks=...))
• RunHooks: attached to the runner (Runner.run(..., hooks=...))

You can check these examples to see how it works:

• https://github.com/openai/openai-agents-python/blob/main/examples/basic/lifecycle_example.py
• https://github.com/openai/openai-agents-python/blob/main/examples/basic/agent_lifecycle_example.py

Here’s your example fixed and working correctly 👇

from agents import Agent, RunHooks, Runner, RunContextWrapper, ModelResponse
from typing import Optional
from agents.items import TResponseInputItem

class MyAgentHooks(RunHooks):
    def __init__(self):
        self.event_counter = 0

    async def on_agent_start(self, context: RunContextWrapper, agent: Agent) -> None:
        print("✅ on_agent_start called")  # This IS called
    
    async def on_llm_start(
        self,
        context: RunContextWrapper,
        agent: Agent,
        system_prompt: Optional[str],
        input_items: list[TResponseInputItem],
    ) -> None:
        print("✅ on_llm_start called") # This IS called
    
    async def on_llm_end(
        self, context: RunContextWrapper, agent: Agent, response: ModelResponse
    ) -> None:
        print("✅ on_llm_end called")  #This IS called
        print(f"Response: {response}")
    
    async def on_handoff(self, context: RunContextWrapper, from_agent: Agent, to_agent: Agent) -> None:
        print("✅ on_handoff called")  # This IS called

next_agent = Agent(name="next_agent", instructions="...")

my_agent = Agent(
    name="my_agent",
    instructions="Output text then call handoff tool",
    handoffs=[next_agent],
)

# Run the agent
result = Runner.run_sync(my_agent, input="test query", hooks=MyAgentHooks() )

print(result.final_output)

✅ Output:

✅ on_agent_start called
✅ on_llm_start called
✅ on_llm_end called
Response: ModelResponse(output=[...])
✅ on_handoff called
✅ on_agent_start called
✅ on_llm_start called
✅ on_llm_end called
Response: ModelResponse(output=[...])

[muneebarshadd]

@ihower Thank you for the clarification! However, I believe there may still be an issue with AgentHooks when using run_streamed.

My Setup

I'm using AgentHooks (not RunHooks) attached directly to my agent:

from agents import Agent, AgentHooks, ModelResponse, RunContextWrapper

class MyAgentHooks(AgentHooks):
    async def on_start(self, context: RunContextWrapper, agent: Agent) -> None:
        print("✅ on_start called")  # This IS called
    
    async def on_end(self, context: RunContextWrapper, agent: Agent, output: str) -> None:
        print("❌ on_end called")  # This is NEVER called
        context.context.converted_query = output
    
    async def on_llm_end(self, context: RunContextWrapper, agent: Agent, response: ModelResponse) -> None:
        print("❌ on_llm_end called")  # This is NEVER called

# Create agent with AgentHooks
my_agent = Agent(
    name="my_rewrite_agent",
    instructions="Rewrite the user's query...",
    hooks=MyAgentHooks(),  # AgentHooks attached to agent
    handoffs=[next_agent],
)

# Run using run_streamed
result = Runner.run_streamed(
    my_agent,
    input=user_query,
    context=my_context
)

The Issue

When using run_streamed with AgentHooks:

• ✅ on_start is called
• ❌ on_end is NOT called
• ❌ on_llm_end is NOT called

Questions

1. Is this expected behavior for AgentHooks with run_streamed?
2. Should on_end and on_llm_end be called for AgentHooks, or are they only available in RunHooks?
3. If I need access to the agent's output before handoff, should I use RunHooks instead of AgentHooks?

[ihower]

@muneebarshadd Because you attached the hooks only to my_agent, when the handoff happens, control is transferred to next_agent, which doesn’t have any hooks attached, so your on_end and on_llm_end methods will no longer run.

Try this instead 👇

next_agent = Agent( name="next_agent", instructions="...",  hooks=MyAgentHooks() )  # 👈 add this

That way, both agents have their own AgentHooks, and you’ll see the hooks being printed.

To clarify a bit more:

1. AgentHooks only apply to the specific agent they’re attached to. Once a handoff occurs, the next agent needs its own hooks if you want to observe its lifecycle.
2. RunHooks apply to the entire run, even if handoffs happen internally.
3. If your goal is to observe the full run, it’s usually better to use RunHooks.

[github-actions]

This issue is stale because it has been open for 7 days with no activity.