Expose Tool Call ID to Lifecycle Hooks

[ElliotAtKlaviyo]

Please read this first

• Have you read the docs? Agents SDK docs
• Have you searched for related issues? Others may have had similar requests

Describe the feature

Problem Statement

I'm leveraging lifecycle events to record timing metrics for my AI agent. I have a class that inherits RunHooksBase. When on_agent_start and on_tool_start are called, I begin timers. When on_agent_end or on_tool_end are called, I stop timers and record the metric. Unfortunately, I'm unable to differentiate between tool calls. Thus, metrics may be slightly imprecise if the agent has parallel tool calls enabled. Knowing with *_start corresponds with which *_end would allow this type of observability.

Feature Details

If possible, all hook methods should have access to a unique ID that identifies the tool call. I notice that elsewhere, ToolContext provides a tool_call_id. This type of value would be ideal for lifecycle events and satisfy the problem statement above.

[ihower]

@ElliotAtKlaviyo You can refer to https://github.com/openai/openai-agents-python/blob/main/examples/basic/lifecycle_example.py example.

In both on_tool_start and on_tool_end hooks, you already have access to context.tool_call_id, which lets you distinguish between different tool calls. That should meet your requirement.

[ElliotAtKlaviyo]

Thank you for your response, @ihower. I notice that this attribute, tool_call_id, isn't available on the object type given to these hooks: RunContextWrapper. I'm seeing it on ToolContext, instead. Given your example, I suspect that on_tool_start and on_tool_end are really receiving this subtype. Thus, I think a better described feature request would be:

Change the RunContextWrapper type annotation to ToolContext on on_tool_start and on_tool_end.

Does that match your thinking, too?

[ihower]

@ElliotAtKlaviyo Unfortunately, I don’t think we can simply change the type annotation of on_tool_start and on_tool_end from RunContextWrapper to ToolContext.

The reason is that two special built-in tools: LocalShellTool and ComputerTool also rely on these hooks. Their structure doesn’t align with ToolContext, and for now they pass a RunContextWrapper into the hook methods.