fix: #563 enable explicit model override for prompt (#589)

Author: seratch

.changeset/blue-symbols-kiss.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents-openai': patch
+'@openai/agents-core': patch
+---
+
+fix: #563 enable explicit model override for prompt

packages/agents-core/src/model.ts

@@ -269,6 +269,13 @@ export type ModelRequest = {
    * The prompt template to use for the model, if any.
    */
   prompt?: Prompt;
+
+  /**
+   * When true, the resolved model should override the model configured in the prompt template.
+   * Providers that support prompt templates should include the explicit model name in the request
+   * even when a prompt is supplied.
+   */
+  overridePromptModel?: boolean;
 };
 
 export type ModelResponse = {

packages/agents-core/src/run.ts

@@ -558,6 +558,8 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
                 state._context,
               ),
               prompt: await state._currentAgent.getPrompt(state._context),
+              // Explicit agent/run config models should take precedence over prompt defaults.
+              ...(explictlyModelSet ? { overridePromptModel: true } : {}),
               input: turnInput,
               previousResponseId,
               conversationId,
@@ -957,6 +959,8 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
               result.state._context,
             ),
             prompt: await currentAgent.getPrompt(result.state._context),
+            // Streaming requests should also honor explicitly chosen models.
+            ...(explictlyModelSet ? { overridePromptModel: true } : {}),
             input: turnInput,
             previousResponseId,
             conversationId,

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

@@ -157,6 +157,39 @@ describe('Runner.run', () => {
       await expect(run(agent, 'fail')).rejects.toThrow('No response found');
     });
 
+    it('sets overridePromptModel when agent supplies a prompt and explicit model', async () => {
+      class CapturingModel implements Model {
+        lastRequest?: ModelRequest;
+        async getResponse(request: ModelRequest): Promise<ModelResponse> {
+          this.lastRequest = request;
+          return {
+            output: [fakeModelMessage('override')],
+            usage: new Usage(),
+          };
+        }
+        async *getStreamedResponse(
+          _request: ModelRequest,
+        ): AsyncIterable<protocol.StreamEvent> {
+          yield* [];
+          throw new Error('Not implemented');
+        }
+      }
+
+      const capturingModel = new CapturingModel();
+
+      const agent = new Agent({
+        name: 'Prompted',
+        instructions: 'Use the prompt.',
+        model: capturingModel,
+        prompt: { promptId: 'prompt_123' },
+      });
+
+      await run(agent, 'hello');
+
+      expect(capturingModel.lastRequest?.prompt).toBeDefined();
+      expect(capturingModel.lastRequest?.overridePromptModel).toBe(true);
+    });
+
     it('emits agent_end lifecycle event for non-streaming agents', async () => {
       const agent = new Agent({
         name: 'TestAgent',

packages/agents-openai/src/openaiResponsesModel.ts

@@ -877,8 +877,13 @@ export class OpenAIResponsesModel implements Model {
       parallelToolCalls = request.modelSettings.parallelToolCalls;
     }
 
+    // When a prompt template already declares a model, skip sending the agent's default model.
+    // If the caller explicitly requests an override, include the resolved model name in the request.
+    const shouldSendModel =
+      !request.prompt || request.overridePromptModel === true;
+
     const requestData = {
-      ...(!request.prompt ? { model: this.#model } : {}),
+      ...(shouldSendModel ? { model: this.#model } : {}),
       instructions: normalizeInstructions(request.systemInstructions),
       input,
       include,

packages/agents-openai/test/openaiResponsesModel.test.ts

@@ -104,6 +104,37 @@ describe('OpenAIResponsesModel', () => {
     });
   });
 
+  it('includes model when overridePromptModel is true', async () => {
+    await withTrace('test', async () => {
+      const fakeResponse = { id: 'res-prompt-override', usage: {}, output: [] };
+      const createMock = vi.fn().mockResolvedValue(fakeResponse);
+      const fakeClient = {
+        responses: { create: createMock },
+      } as unknown as OpenAI;
+      const model = new OpenAIResponsesModel(fakeClient, 'gpt-override');
+
+      const request = {
+        systemInstructions: undefined,
+        prompt: { promptId: 'pmpt_456' },
+        input: 'hello',
+        modelSettings: {},
+        tools: [],
+        outputType: 'text',
+        handoffs: [],
+        tracing: false,
+        signal: undefined,
+        overridePromptModel: true,
+      };
+
+      await model.getResponse(request as any);
+
+      expect(createMock).toHaveBeenCalledTimes(1);
+      const [args] = createMock.mock.calls[0];
+      expect(args.model).toBe('gpt-override');
+      expect(args.prompt).toMatchObject({ id: 'pmpt_456' });
+    });
+  });
+
   it('normalizes systemInstructions so empty strings are omitted', async () => {
     await withTrace('test', async () => {
       const fakeResponse = {