fix(realtime): use item id for guardrail details

Author: dkundel-openai

docs/src/content/docs/guides/voice-agents/build.mdx

@@ -98,7 +98,7 @@ Guardrails offer a way to monitor whether what the agent has said violated a set
 
 The guardrails that you provide will run asynchronously as a model response is returned, allowing you to cut off the response based a predefined classification trigger, for example "mentions a specific banned word".
 
-When a guardrail trips the session emits a `guardrail_tripped` event.
+When a guardrail trips the session emits a `guardrail_tripped` event. The event also provides a `details` object containing the `itemId` that triggered the guardrail.
 
 <Code lang="typescript" code={guardrailsExample} />
 

docs/src/content/docs/ja/guides/voice-agents/build.mdx

@@ -92,7 +92,7 @@ Realtime Agent で使用できるのは関数ツールのみで、これらの
 
 提供したガードレールは、モデルの応答が返されると同時に非同期で実行され、たとえば「特定の禁止ワードを含む」などの分類トリガーに基づいて応答を打ち切れます。
 
-ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。
+ガードレールが作動すると、セッションは `guardrail_tripped` イベントを発行します。イベントには違反したアイテムの `itemId` を含む `details` オブジェクトが追加で渡されます。
 
 <Code lang="typescript" code={guardrailsExample} />
 

packages/agents-realtime/src/realtimeSession.ts

@@ -447,7 +447,11 @@ export class RealtimeSession<
     }
   }
 
-  async #runOutputGuardrails(output: string, responseId: string) {
+  async #runOutputGuardrails(
+    output: string,
+    responseId: string,
+    itemId: string,
+  ) {
     if (this.#outputGuardrails.length === 0) {
       return;
     }
@@ -475,7 +479,9 @@ export class RealtimeSession<
         `Output guardrail triggered: ${JSON.stringify(firstTripwireTriggered.output.outputInfo)}`,
         firstTripwireTriggered,
       );
-      this.emit('guardrail_tripped', this.#context, this.#currentAgent, error);
+      this.emit('guardrail_tripped', this.#context, this.#currentAgent, error, {
+        itemId,
+      });
       this.interrupt();
 
       const feedbackText = getRealtimeGuardrailFeedbackMessage(
@@ -500,10 +506,11 @@ export class RealtimeSession<
     this.#transport.on('turn_done', (event) => {
       const item = event.response.output[event.response.output.length - 1];
       const textOutput = getLastTextFromAudioOutputMessage(item) ?? '';
+      const itemId = item.id ?? '';
       this.emit('agent_end', this.#context, this.#currentAgent, textOutput);
       this.#currentAgent.emit('agent_end', this.#context, textOutput);
 
-      this.#runOutputGuardrails(textOutput, event.response.id);
+      this.#runOutputGuardrails(textOutput, event.response.id, itemId);
     });
 
     this.#transport.on('audio_done', () => {
@@ -537,7 +544,7 @@ export class RealtimeSession<
           // We don't cancel existing runs because we want the first one to fail to fail
           // The transport layer should upon failure handle the interruption and stop the model
           // from generating further
-          this.#runOutputGuardrails(newText, responseId);
+          this.#runOutputGuardrails(newText, responseId, itemId);
         }
       } catch (err) {
         this.emit('error', {

packages/agents-realtime/src/realtimeSessionEvents.ts

@@ -113,6 +113,7 @@ export type RealtimeSessionEventTypes<TContext = unknown> = {
     context: RunContext<RealtimeContextData<TContext>>,
     agent: AgentWithOrWithoutHistory<TContext>,
     error: OutputGuardrailTripwireTriggered<RealtimeGuardrailMetadata>,
+    details: { itemId: string },
   ];
 
   /**

packages/agents-realtime/test/realtimeSession.test.ts

@@ -155,6 +155,7 @@ describe('RealtimeSession', () => {
     await vi.waitFor(() => expect(guardrailEvents.length).toBe(1));
     expect(transport.interruptCalls).toBe(1);
     expect(transport.sendMessageCalls.at(-1)?.[0]).toContain('blocked');
+    expect(guardrailEvents[0][3]).toEqual({ itemId: '123' });
     vi.restoreAllMocks();
   });