From 927346f36ef68efac32386191103310b0f02c8db Mon Sep 17 00:00:00 2001 From: Wen-Tien Chang Date: Tue, 4 Nov 2025 10:56:24 +0800 Subject: [PATCH] docs: clarify that on_tool_start and on_tool_end hooks apply only to local tools --- examples/basic/agent_lifecycle_example.py | 4 ++++ examples/basic/lifecycle_example.py | 4 ++++ src/agents/lifecycle.py | 8 ++++---- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/examples/basic/agent_lifecycle_example.py b/examples/basic/agent_lifecycle_example.py index 032851188..3c553381b 100644 --- a/examples/basic/agent_lifecycle_example.py +++ b/examples/basic/agent_lifecycle_example.py @@ -28,6 +28,10 @@ async def on_handoff(self, context: RunContextWrapper, agent: Agent, source: Age f"### ({self.display_name}) {self.event_counter}: Agent {source.name} handed off to {agent.name}" ) + # Note: The on_tool_start and on_tool_end hooks apply only to local tools. + # They do not include hosted tools that run on the OpenAI server side, + # such as WebSearchTool, FileSearchTool, CodeInterpreterTool, HostedMCPTool, + # or other built-in hosted tools. async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None: self.event_counter += 1 print( diff --git a/examples/basic/lifecycle_example.py b/examples/basic/lifecycle_example.py index 13a5be582..04ed8b4c7 100644 --- a/examples/basic/lifecycle_example.py +++ b/examples/basic/lifecycle_example.py @@ -70,6 +70,10 @@ async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: A f"### {self.event_counter}: Agent {agent.name} ended with output {output}. Usage: {self._usage_to_str(context.usage)}" ) + # Note: The on_tool_start and on_tool_end hooks apply only to local tools. + # They do not include hosted tools that run on the OpenAI server side, + # such as WebSearchTool, FileSearchTool, CodeInterpreterTool, HostedMCPTool, + # or other built-in hosted tools. async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None: self.event_counter += 1 # While this type cast is not ideal, diff --git a/src/agents/lifecycle.py b/src/agents/lifecycle.py index 438f25d7a..85ea26bc8 100644 --- a/src/agents/lifecycle.py +++ b/src/agents/lifecycle.py @@ -62,7 +62,7 @@ async def on_tool_start( agent: TAgent, tool: Tool, ) -> None: - """Called concurrently with tool invocation.""" + """Called immediately before a local tool is invoked.""" pass async def on_tool_end( @@ -72,7 +72,7 @@ async def on_tool_end( tool: Tool, result: str, ) -> None: - """Called after a tool is invoked.""" + """Called immediately after a local tool is invoked.""" pass @@ -113,7 +113,7 @@ async def on_tool_start( agent: TAgent, tool: Tool, ) -> None: - """Called concurrently with tool invocation.""" + """Called immediately before a local tool is invoked.""" pass async def on_tool_end( @@ -123,7 +123,7 @@ async def on_tool_end( tool: Tool, result: str, ) -> None: - """Called after a tool is invoked.""" + """Called immediately after a local tool is invoked.""" pass async def on_llm_start(