Add providerData to model responses (#104)

* feat(core): expose model response via details

* Create shaggy-teachers-worry.md

Author: dkundel-openai

.changeset/shaggy-teachers-worry.md

@@ -0,0 +1,8 @@
+---
+"@openai/agents-core": patch
+"@openai/agents-extensions": patch
+"@openai/agents-openai": patch
+"@openai/agents-realtime": patch
+---
+
+Add details to output guardrail execution

packages/agents-core/src/guardrail.ts

@@ -2,6 +2,7 @@ import type { ModelItem } from './types/protocol';
 import { Agent, AgentOutputType } from './agent';
 import { RunContext } from './runContext';
 import { ResolvedAgentOutput, TextOutput, UnknownContext } from './types';
+import type { ModelResponse } from './model';
 
 /**
  * Definition of input/output guardrails; SDK users usually do not need to create this.
@@ -149,6 +150,13 @@ export interface OutputGuardrailFunctionArgs<
   agent: Agent<any, any>;
   agentOutput: ResolvedAgentOutput<TOutput>;
   context: RunContext<TContext>;
+  /**
+   * Additional details about the agent output.
+   */
+  details?: {
+    /** Model response associated with the output if available. */
+    modelResponse?: ModelResponse;
+  };
 }
 /**
  * The result of an output guardrail execution.

packages/agents-core/src/model.ts

@@ -221,6 +221,11 @@ export type ModelResponse = {
    * model. Not supported by all model providers.
    */
   responseId?: string;
+
+  /**
+   * Raw response data from the underlying model provider.
+   */
+  providerData?: Record<string, any>;
 };
 
 /**

packages/agents-core/src/run.ts

@@ -543,6 +543,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
         agent: state._currentAgent,
         agentOutput,
         context: state._context,
+        details: { modelResponse: state._lastTurnResponse },
       };
       try {
         const results = await Promise.all(

packages/agents-core/src/runState.ts

@@ -82,6 +82,7 @@ const modelResponseSchema = z.object({
   usage: usageSchema,
   output: z.array(protocol.OutputModelItem),
   responseId: z.string().optional(),
+  providerData: z.record(z.string(), z.any()).optional(),
 });
 
 const itemSchema = z.discriminatedUnion('type', [
@@ -388,6 +389,7 @@ export class RunState<TContext, TAgent extends Agent<any, any>> {
           },
           output: response.output as any,
           responseId: response.responseId,
+          providerData: response.providerData,
         };
       }),
       context: this._context.toJSON(),
@@ -635,6 +637,7 @@ export function deserializeModelResponse(
       protocol.OutputModelItem.parse(item),
     ),
     responseId: serializedModelResponse.responseId,
+    providerData: serializedModelResponse.providerData,
   };
 }
 

packages/agents-extensions/src/aiSdk.ts

@@ -449,6 +449,7 @@ export class AiSdkModel implements Model {
               result.usage.promptTokens + result.usage.completionTokens,
           }),
           output,
+          providerData: result,
         };
       } catch (error) {
         if (error instanceof Error) {

packages/agents-openai/src/openaiChatCompletionsModel.ts

@@ -141,6 +141,7 @@ export class OpenAIChatCompletionsModel implements Model {
         : new Usage(),
       output,
       responseId: response.id,
+      providerData: response,
     };
 
     return modelResponse;

packages/agents-openai/src/openaiResponsesModel.ts

@@ -856,6 +856,7 @@ export class OpenAIResponsesModel implements Model {
       }),
       output: convertToOutputItem(response.output),
       responseId: response.id,
+      providerData: response,
     };
 
     return output;