feat: #762 Add turnInput (optional) to agent_start event hooks (#765)

Author: seratch

.changeset/frank-maps-grab.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents-realtime': patch
+'@openai/agents-core': patch
+---
+
+feat: #762 Add turnInput (optional) to agent_start event hooks

packages/agents-core/src/lifecycle.ts

@@ -6,13 +6,12 @@ import {
   EventEmitter,
   EventEmitterEvents,
 } from '@openai/agents-core/_shims';
-import { TextOutput, UnknownContext } from './types';
+import { AgentInputItem, TextOutput, UnknownContext } from './types';
 import * as protocol from './types/protocol';
 
 export abstract class EventEmitterDelegate<
   EventTypes extends EventEmitterEvents = Record<string, any[]>,
-> implements EventEmitter<EventTypes>
-{
+> implements EventEmitter<EventTypes> {
   protected abstract eventEmitter: EventEmitter<EventTypes>;
 
   on<K extends keyof EventTypes>(
@@ -47,9 +46,20 @@ export type AgentHookEvents<
 > = {
   /**
    * @param context - The context of the run
+   * @param agent - The agent that is starting
+   * @param turnInput - The input items for the current turn
    */
-  agent_start: [context: RunContext<TContext>, agent: Agent<TContext, TOutput>];
+  agent_start: [
+    context: RunContext<TContext>,
+    agent: Agent<TContext, TOutput>,
+    turnInput?: AgentInputItem[],
+  ];
   /**
+   * Note that the second argument is not consistent with the run hooks here.
+   * Changing the list is a breaking change, so we don't make changes for it in the short term
+   * If we revisit the argument data structure (e.g., migrating to a single object instead),
+   * more properties could be easily added later on.
+   *
    * @param context - The context of the run
    * @param output - The output of the agent
    */
@@ -105,7 +115,11 @@ export type RunHookEvents<
    * @param context - The context of the run
    * @param agent - The agent that is starting
    */
-  agent_start: [context: RunContext<TContext>, agent: Agent<TContext, TOutput>];
+  agent_start: [
+    context: RunContext<TContext>,
+    agent: Agent<TContext, TOutput>,
+    turnInput?: AgentInputItem[],
+  ];
   /**
    * @param context - The context of the run
    * @param agent - The agent that is ending

packages/agents-core/src/run.ts

@@ -816,8 +816,14 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
                 'agent_start',
                 state._context,
                 state._currentAgent,
+                turnInput,
+              );
+              this.emit(
+                'agent_start',
+                state._context,
+                state._currentAgent,
+                turnInput,
               );
-              this.emit('agent_start', state._context, state._currentAgent);
             }
 
             const preparedCall = await this.#prepareModelCall(
@@ -1128,8 +1134,14 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
               'agent_start',
               result.state._context,
               currentAgent,
+              turnInput,
+            );
+            this.emit(
+              'agent_start',
+              result.state._context,
+              currentAgent,
+              turnInput,
             );
-            this.emit('agent_start', result.state._context, currentAgent);
           }
 
           let finalResponse: ModelResponse | undefined = undefined;

packages/agents-core/test/run.stream.test.ts

@@ -210,6 +210,68 @@ describe('Runner.run (streaming)', () => {
     expect(runnerEndEvents[0].output).toBe('Final output');
   });
 
+  it('emits turn input on agent_start during streaming runs', async () => {
+    class LifecycleStreamingModel implements Model {
+      async getResponse(_req: ModelRequest): Promise<ModelResponse> {
+        return {
+          output: [fakeModelMessage('Final output')],
+          usage: new Usage(),
+        };
+      }
+
+      async *getStreamedResponse(): AsyncIterable<StreamEvent> {
+        yield {
+          type: 'response_done',
+          response: {
+            id: 'r_lifecycle',
+            usage: {
+              requests: 1,
+              inputTokens: 0,
+              outputTokens: 0,
+              totalTokens: 0,
+            },
+            output: [fakeModelMessage('Final output')],
+          },
+        } as any;
+      }
+    }
+
+    const agent = new Agent({
+      name: 'StreamLifecycleAgent',
+      model: new LifecycleStreamingModel(),
+    });
+    const runner = new Runner();
+
+    const agentInputs: AgentInputItem[][] = [];
+    const runnerInputs: AgentInputItem[][] = [];
+
+    agent.on('agent_start', (_context, _agent, turnInput) => {
+      agentInputs.push(turnInput ?? []);
+    });
+    runner.on('agent_start', (_context, _agent, turnInput) => {
+      runnerInputs.push(turnInput ?? []);
+    });
+
+    const result = await runner.run(agent, 'stream this input', {
+      stream: true,
+    });
+
+    // Drain the stream to ensure the run completes.
+    for await (const _event of result.toStream()) {
+      // no-op
+    }
+    await result.completed;
+
+    expect(agentInputs).toHaveLength(1);
+    expect(runnerInputs).toHaveLength(1);
+    expect(agentInputs[0].map(getFirstTextContent)).toEqual([
+      'stream this input',
+    ]);
+    expect(runnerInputs[0].map(getFirstTextContent)).toEqual([
+      'stream this input',
+    ]);
+  });
+
   it('updates cumulative usage during streaming responses', async () => {
     const testTool = tool({
       name: 'calculator',

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

@@ -123,6 +123,41 @@ describe('Runner.run', () => {
       ]);
     });
 
+    it('emits turn input on agent_start lifecycle hooks', async () => {
+      const model = new FakeModel([
+        {
+          output: [fakeModelMessage('Acknowledged')],
+          usage: new Usage(),
+        },
+      ]);
+      const agent = new Agent({
+        name: 'LifecycleInputAgent',
+        model,
+      });
+      const runner = new Runner();
+
+      const agentInputs: AgentInputItem[][] = [];
+      const runnerInputs: AgentInputItem[][] = [];
+
+      agent.on('agent_start', (_context, _agent, turnInput) => {
+        agentInputs.push(turnInput ?? []);
+      });
+      runner.on('agent_start', (_context, _agent, turnInput) => {
+        runnerInputs.push(turnInput ?? []);
+      });
+
+      await runner.run(agent, 'capture this input for tracing');
+
+      expect(agentInputs).toHaveLength(1);
+      expect(runnerInputs).toHaveLength(1);
+      expect(agentInputs[0].map(getFirstTextContent)).toEqual([
+        'capture this input for tracing',
+      ]);
+      expect(runnerInputs[0].map(getFirstTextContent)).toEqual([
+        'capture this input for tracing',
+      ]);
+    });
+
     it('sholuld handle structured output', async () => {
       const fakeModel = new FakeModel([
         {

packages/agents-realtime/src/realtimeSessionEvents.ts

@@ -3,6 +3,7 @@ import {
   OutputGuardrailTripwireTriggered,
   RunContext,
   RunToolApprovalItem,
+  AgentInputItem,
 } from '@openai/agents-core';
 import { RealtimeGuardrailMetadata } from './guardrail';
 import { RealtimeItem, RealtimeMcpCallItem } from './items';
@@ -39,6 +40,7 @@ export type RealtimeSessionEventTypes<TContext = unknown> = {
   agent_start: [
     context: RunContext<RealtimeContextData<TContext>>,
     agent: AgentWithOrWithoutHistory<TContext>,
+    turnInput?: AgentInputItem[],
   ];
 
   /**