feat(core): add tool call details to tool events (#102)

Author: dkundel-openai

packages/agents-core/src/lifecycle.ts

@@ -7,6 +7,7 @@ import {
   EventEmitterEvents,
 } from '@openai/agents-core/_shims';
 import { TextOutput, UnknownContext } from './types';
+import * as protocol from './types/protocol';
 
 export abstract class EventEmitterDelegate<
   EventTypes extends EventEmitterEvents = Record<string, any[]>,
@@ -64,7 +65,11 @@ export type AgentHookEvents<
    * @param agent - The agent that is starting a tool
    * @param tool - The tool that is starting
    */
-  agent_tool_start: [context: RunContext<TContext>, tool: Tool<any>];
+  agent_tool_start: [
+    context: RunContext<TContext>,
+    tool: Tool<any>,
+    details: { toolCall: protocol.ToolCallItem },
+  ];
   /**
    * @param context - The context of the run
    * @param agent - The agent that is ending a tool
@@ -75,6 +80,7 @@ export type AgentHookEvents<
     context: RunContext<TContext>,
     tool: Tool<any>,
     result: string,
+    details: { toolCall: protocol.ToolCallItem },
   ];
 };
 
@@ -129,6 +135,7 @@ export type RunHookEvents<
     context: RunContext<TContext>,
     agent: Agent<TContext, TOutput>,
     tool: Tool,
+    details: { toolCall: protocol.ToolCallItem },
   ];
   /**
    * @param context - The context of the run
@@ -141,6 +148,7 @@ export type RunHookEvents<
     agent: Agent<TContext, TOutput>,
     tool: Tool,
     result: string,
+    details: { toolCall: protocol.ToolCallItem },
   ];
 };
 

packages/agents-core/src/runImplementation.ts

@@ -732,8 +732,12 @@ export async function executeFunctionToolCalls<TContext = UnknownContext>(
         }
 
         try {
-          runner.emit('agent_tool_start', state._context, agent, toolRun.tool);
-          agent.emit('agent_tool_start', state._context, toolRun.tool);
+          runner.emit('agent_tool_start', state._context, agent, toolRun.tool, {
+            toolCall: toolRun.toolCall,
+          });
+          agent.emit('agent_tool_start', state._context, toolRun.tool, {
+            toolCall: toolRun.toolCall,
+          });
           const result = await toolRun.tool.invoke(
             state._context,
             toolRun.toolCall.arguments,
@@ -747,12 +751,14 @@ export async function executeFunctionToolCalls<TContext = UnknownContext>(
             agent,
             toolRun.tool,
             stringResult,
+            { toolCall: toolRun.toolCall },
           );
           agent.emit(
             'agent_tool_end',
             state._context,
             toolRun.tool,
             stringResult,
+            { toolCall: toolRun.toolCall },
           );
 
           if (runner.config.traceIncludeSensitiveData) {
@@ -879,9 +885,11 @@ export async function executeComputerActions(
     const toolCall = action.toolCall;
 
     // Hooks: on_tool_start (global + agent)
-    runner.emit('agent_tool_start', runContext, agent, action.computer);
+    runner.emit('agent_tool_start', runContext, agent, action.computer, {
+      toolCall,
+    });
     if (typeof agent.emit === 'function') {
-      agent.emit('agent_tool_start', runContext, action.computer);
+      agent.emit('agent_tool_start', runContext, action.computer, { toolCall });
     }
 
     // Run the action and get screenshot
@@ -894,9 +902,13 @@ export async function executeComputerActions(
     }
 
     // Hooks: on_tool_end (global + agent)
-    runner.emit('agent_tool_end', runContext, agent, action.computer, output);
+    runner.emit('agent_tool_end', runContext, agent, action.computer, output, {
+      toolCall,
+    });
     if (typeof agent.emit === 'function') {
-      agent.emit('agent_tool_end', runContext, action.computer, output);
+      agent.emit('agent_tool_end', runContext, action.computer, output, {
+        toolCall,
+      });
     }
 
     // Always return a screenshot as a base64 data URL

packages/agents-core/test/runImplementation.test.ts

@@ -537,8 +537,16 @@ describe('executeFunctionToolCalls', () => {
     );
 
     expect(res[0].type).toBe('function_output');
-    expect(start).toHaveBeenCalled();
-    expect(end).toHaveBeenCalled();
+    expect(start).toHaveBeenCalledWith(state._context, state._currentAgent, t, {
+      toolCall,
+    });
+    expect(end).toHaveBeenCalledWith(
+      state._context,
+      state._currentAgent,
+      t,
+      'ok',
+      { toolCall },
+    );
     expect(res[0].runItem).toBeInstanceOf(ToolCallOutputItem);
     expect(invokeSpy).toHaveBeenCalled();
   });

packages/agents-realtime/src/realtimeSession.ts

@@ -372,8 +372,12 @@ export class RealtimeSession<
         callId: toolCall.callId,
       });
       if (approval === false) {
-        this.emit('agent_tool_start', this.#context, this.#currentAgent, tool);
-        this.#currentAgent.emit('agent_tool_start', this.#context, tool);
+        this.emit('agent_tool_start', this.#context, this.#currentAgent, tool, {
+          toolCall,
+        });
+        this.#currentAgent.emit('agent_tool_start', this.#context, tool, {
+          toolCall,
+        });
 
         const result = 'Tool execution was not approved.';
         this.#transport.sendFunctionCallOutput(toolCall, result, true);
@@ -383,8 +387,11 @@ export class RealtimeSession<
           this.#currentAgent,
           tool,
           result,
+          { toolCall },
         );
-        this.#currentAgent.emit('agent_tool_end', this.#context, tool, result);
+        this.#currentAgent.emit('agent_tool_end', this.#context, tool, result, {
+          toolCall,
+        });
         return;
       } else if (typeof approval === 'undefined') {
         this.emit(
@@ -401,8 +408,12 @@ export class RealtimeSession<
       }
     }
 
-    this.emit('agent_tool_start', this.#context, this.#currentAgent, tool);
-    this.#currentAgent.emit('agent_tool_start', this.#context, tool);
+    this.emit('agent_tool_start', this.#context, this.#currentAgent, tool, {
+      toolCall,
+    });
+    this.#currentAgent.emit('agent_tool_start', this.#context, tool, {
+      toolCall,
+    });
 
     this.#context.context.history = JSON.parse(JSON.stringify(this.#history)); // deep copy of the history
     const result = await tool.invoke(this.#context, toolCall.arguments);
@@ -414,12 +425,14 @@ export class RealtimeSession<
       this.#currentAgent,
       tool,
       stringResult,
+      { toolCall },
     );
     this.#currentAgent.emit(
       'agent_tool_end',
       this.#context,
       tool,
       stringResult,
+      { toolCall },
     );
   }
 

packages/agents-realtime/src/realtimeSessionEvents.ts

@@ -9,6 +9,7 @@ import { RealtimeItem } from './items';
 import { RealtimeAgent } from './realtimeAgent';
 import { TransportEvent, TransportLayerAudio } from './transportLayerEvents';
 import { RealtimeContextData } from './realtimeSession';
+import { protocol } from '@openai/agents-core';
 
 type AgentWithOrWithoutHistory<TContext> =
   | RealtimeAgent<TContext>
@@ -59,6 +60,7 @@ export type RealtimeSessionEventTypes<TContext = unknown> = {
     context: RunContext<RealtimeContextData<TContext>>,
     agent: AgentWithOrWithoutHistory<TContext>,
     tool: FunctionTool<RealtimeContextData<TContext>>,
+    details: { toolCall: protocol.ToolCallItem },
   ];
 
   /**
@@ -68,7 +70,8 @@ export type RealtimeSessionEventTypes<TContext = unknown> = {
     context: RunContext<RealtimeContextData<TContext>>,
     agent: AgentWithOrWithoutHistory<TContext>,
     tool: FunctionTool<RealtimeContextData<TContext>>,
-    result?: string,
+    result: string,
+    details: { toolCall: protocol.ToolCallItem },
   ];
 
   /**