Add typed reasoning / text options to ModelSettings (#513)

seratch · web-flow · commit 311517792d42 · 2025-09-26T10:29:50.000+09:00
diff --git a/.changeset/hungry-sheep-end.md b/.changeset/hungry-sheep-end.md
@@ -0,0 +1,6 @@
+---
+'@openai/agents-openai': patch
+'@openai/agents-core': patch
+---
+
+Add typed reasoning / text options to ModelSettings
diff --git a/examples/agent-patterns/agents-as-tools.ts b/examples/agent-patterns/agents-as-tools.ts
@@ -33,10 +33,8 @@ const orchestratorAgent = new Agent({
       runConfig: {
         model: 'gpt-5',
         modelSettings: {
-          providerData: {
-            reasoning: { effort: 'low' },
-            text: { verbosity: 'low' },
-          },
+          reasoning: { effort: 'low' },
+          text: { verbosity: 'low' },
         },
       },
       runOptions: {
diff --git a/examples/ai-sdk/gpt-5.ts b/examples/ai-sdk/gpt-5.ts
@@ -0,0 +1,38 @@
+import { Agent, run, tool } from '@openai/agents';
+import { aisdk } from '@openai/agents-extensions';
+import { z } from 'zod';
+import { openai } from '@ai-sdk/openai';
+
+export async function main() {
+  const getWeatherTool = tool({
+    name: 'get_weather',
+    description: 'Get the weather for a given city',
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => `The weather in ${city} is sunny`,
+  });
+  const agent = new Agent({
+    name: 'Helpful Assistant',
+    instructions:
+      'You are a helpful assistant. When you need to get the weather, you must use tools.',
+    tools: [getWeatherTool],
+    model: aisdk(openai('gpt-5-mini')),
+    modelSettings: {
+      providerData: {
+        providerOptions: {
+          openai: {
+            reasoningEffort: 'minimal',
+            textVerbosity: 'low',
+          },
+        },
+      },
+    },
+  });
+
+  const result = await run(
+    agent,
+    'Hello what is the weather in San Francisco?',
+  );
+  console.log(result.finalOutput);
+}
+
+main().catch(console.error);
diff --git a/examples/ai-sdk/package.json b/examples/ai-sdk/package.json
@@ -11,6 +11,7 @@
   "scripts": {
     "build-check": "tsc --noEmit",
     "start": "tsx index.ts",
+    "start:gpt-5": "tsx gpt-5.ts",
     "start:stream": "tsx stream.ts"
   }
 }
diff --git a/examples/basic/hello-world-gpt-5.ts b/examples/basic/hello-world-gpt-5.ts
@@ -8,38 +8,59 @@ const output = z.object({
 });
 
 async function main() {
+  const prompt =
+    'Tell me about recursion in programming. Quickly responding with a single answer is fine.';
+
   const agent = new Agent({
     name: 'GPT-5 Assistant',
     model: 'gpt-5',
     instructions: "You're a helpful assistant.",
     modelSettings: {
-      providerData: {
-        reasoning: { effort: 'minimal' },
-        text: { verbosity: 'low' },
-      },
+      reasoning: { effort: 'minimal' },
+      text: { verbosity: 'low' },
     },
     outputType: output,
   });
 
-  const prompt =
-    'Tell me about recursion in programming. Quickly responding with a single answer is fine.';
   const result = await run(agent, prompt);
   console.log(result.finalOutput);
 
+  // The following code works in the same way:
+  // const agent2 = agent.clone({
+  //   modelSettings: {
+  //     providerData: {
+  //       reasoning: { effort: 'minimal' },
+  //       text: { verbosity: 'low' },
+  //     }
+  //   },
+  // });
+  // const result2 = await run(agent2, prompt);
+  // console.log(result2.finalOutput);
+
   const completionsAgent = new Agent({
     name: 'GPT-5 Assistant',
     model: new OpenAIChatCompletionsModel(new OpenAI(), 'gpt-5'),
     instructions: "You're a helpful assistant.",
     modelSettings: {
-      providerData: {
-        reasoning_effort: 'minimal',
-        verbosity: 'low',
-      },
+      reasoning: { effort: 'minimal' },
+      text: { verbosity: 'low' },
     },
     outputType: output,
   });
   const completionsResult = await run(completionsAgent, prompt);
   console.log(completionsResult.finalOutput);
+
+  // The following code works in the same way:
+  // const completionsAgent2 = completionsAgent.clone({
+  //   modelSettings: {
+  //     providerData: {
+  //       reasoning_effort: 'minimal',
+  //       verbosity: 'low',
+  //     }
+  //   },
+  // });
+  // const completionsResult2 = await run(completionsAgent2, prompt);
+  // console.log(completionsResult2.finalOutput);
 }
 
 if (require.main === module) {
diff --git a/examples/basic/hello-world-gpt-oss.ts b/examples/basic/hello-world-gpt-oss.ts
@@ -25,9 +25,7 @@ async function main() {
       'gpt-oss:20b',
     ),
     instructions: 'You answer questions concisely and to the point.',
-    modelSettings: {
-      providerData: { reasoning: { effort: 'low' } },
-    },
+    modelSettings: { reasoning: { effort: 'low' } },
   });
 
   const question = 'Tell me about recursion in programming.';
diff --git a/examples/basic/reasoning.ts b/examples/basic/reasoning.ts
@@ -9,15 +9,8 @@ async function main() {
     name: 'Agent',
     model: 'gpt-5',
     modelSettings: {
-      providerData: {
-        reasoning: {
-          effort: 'high',
-          summary: 'auto',
-        },
-        text: {
-          verbosity: 'high',
-        },
-      },
+      reasoning: { effort: 'high', summary: 'auto' },
+      text: { verbosity: 'high' },
     },
   });
 
diff --git a/examples/tools/web-search-filters.ts b/examples/tools/web-search-filters.ts
@@ -21,9 +21,9 @@ async function main() {
       }),
     ],
     modelSettings: {
+      reasoning: { effort: 'low' },
+      text: { verbosity: 'low' },
       providerData: {
-        reasoning: { effort: 'low' },
-        text: { verbosity: 'low' },
         // https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#sources
         include: ['web_search_call.action.sources'],
       },
diff --git a/packages/agents-core/src/defaultModel.ts b/packages/agents-core/src/defaultModel.ts
@@ -43,13 +43,11 @@ export function getDefaultModelSettings(model?: string): ModelSettings {
   const _model = model ?? getDefaultModel();
   if (gpt5ReasoningSettingsRequired(_model)) {
     return {
-      providerData: {
-        // We chose "low" instead of "minimal" because some of the built-in tools
-        // (e.g., file search, image generation, etc.) do not support "minimal"
-        // If you want to use "minimal" reasoning effort, you can pass your own model settings
-        reasoning: { effort: 'low' },
-        text: { verbosity: 'low' },
-      },
+      // We chose "low" instead of "minimal" because some of the built-in tools
+      // (e.g., file search, image generation, etc.) do not support "minimal"
+      // If you want to use "minimal" reasoning effort, you can pass your own model settings
+      reasoning: { effort: 'low' },
+      text: { verbosity: 'low' },
     };
   }
   return {};
diff --git a/packages/agents-core/src/model.ts b/packages/agents-core/src/model.ts
@@ -18,6 +18,46 @@ export type ModelSettingsToolChoice =
   | 'none'
   | (string & {});
 
+/**
+ * Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+ * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+ * Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
+ */
+export type ModelSettingsReasoningEffort =
+  | 'minimal'
+  | 'low'
+  | 'medium'
+  | 'high'
+  | null;
+
+/**
+ * Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+ */
+export type ModelSettingsReasoning = {
+  /**
+   * Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+   * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+   * Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
+   */
+  effort?: ModelSettingsReasoningEffort | null;
+
+  /**
+   * A summary of the reasoning performed by the model.
+   * This can be useful for debugging and understanding the model's reasoning process.
+   * One of `auto`, `concise`, or `detailed`.
+   */
+  summary?: 'auto' | 'concise' | 'detailed' | null;
+};
+
+export interface ModelSettingsText {
+  /**
+   * Constrains the verbosity of the model's response.
+   * Lower values will result in more concise responses, while higher values will result in more verbose responses.
+   * Currently supported values are `low`, `medium`, and `high`.
+   */
+  verbosity?: 'low' | 'medium' | 'high' | null;
+}
+
 /**
  * Settings to use when calling an LLM.
  *
@@ -75,6 +115,16 @@ export type ModelSettings = {
    */
   store?: boolean;
 
+  /**
+   * The reasoning settings to use when calling the model.
+   */
+  reasoning?: ModelSettingsReasoning;
+
+  /**
+   * The text settings to use when calling the model.
+   */
+  text?: ModelSettingsText;
+
   /**
    * Additional provider specific settings to be passed directly to the model
    * request.
diff --git a/packages/agents-core/src/run.ts b/packages/agents-core/src/run.ts
@@ -1090,10 +1090,19 @@ function adjustModelSettingsForNonGPT5RunnerModel(
       agentModelSettings.providerData?.text?.verbosity ||
       (agentModelSettings.providerData as any)?.reasoning_effort)
   ) {
+    const copiedModelSettings = { ...modelSettings };
     // the incompatible parameters should be removed to avoid runtime errors
-    delete modelSettings.providerData?.reasoning;
-    delete (modelSettings.providerData as any)?.text?.verbosity;
-    delete (modelSettings.providerData as any)?.reasoning_effort;
+    delete copiedModelSettings.providerData?.reasoning;
+    delete (copiedModelSettings.providerData as any)?.text?.verbosity;
+    delete (copiedModelSettings.providerData as any)?.reasoning_effort;
+    if (copiedModelSettings.reasoning) {
+      delete copiedModelSettings.reasoning.effort;
+      delete copiedModelSettings.reasoning.summary;
+    }
+    if (copiedModelSettings.text) {
+      delete copiedModelSettings.text.verbosity;
+    }
+    return copiedModelSettings;
   }
   return modelSettings;
 }
diff --git a/packages/agents-core/test/agent.test.ts b/packages/agents-core/test/agent.test.ts
@@ -5,7 +5,7 @@ import { Handoff, handoff } from '../src/handoff';
 import { z } from 'zod';
 import { JsonSchemaDefinition, setDefaultModelProvider } from '../src';
 import { FakeModelProvider } from './stubs';
-import { Runner } from '../src/run';
+import { Runner, RunConfig } from '../src/run';
 
 describe('Agent', () => {
   afterEach(() => {
@@ -221,12 +221,10 @@ describe('Agent', () => {
       .spyOn(Runner.prototype, 'run')
       .mockImplementation(async () => mockResult);
 
-    const runConfig = {
+    const runConfig: Partial<RunConfig> = {
       model: 'gpt-5',
       modelSettings: {
-        providerData: {
-          reasoning: { effort: 'low' },
-        },
+        reasoning: { effort: 'low' },
       },
     };
     const runOptions = {
diff --git a/packages/agents-core/test/run.test.ts b/packages/agents-core/test/run.test.ts
diff --git a/packages/agents-openai/src/openaiChatCompletionsModel.ts b/packages/agents-openai/src/openaiChatCompletionsModel.ts
diff --git a/packages/agents-openai/src/openaiResponsesModel.ts b/packages/agents-openai/src/openaiResponsesModel.ts
diff --git a/packages/agents-openai/test/openaiChatCompletionsModel.test.ts b/packages/agents-openai/test/openaiChatCompletionsModel.test.ts
diff --git a/packages/agents-openai/test/openaiResponsesModel.test.ts b/packages/agents-openai/test/openaiResponsesModel.test.ts

Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,7 @@`
`11`	`11`	`"scripts": {`
`12`	`12`	`"build-check": "tsc --noEmit",`
`13`	`13`	`"start": "tsx index.ts",`
	`14`	`+ "start:gpt-5": "tsx gpt-5.ts",`
`14`	`15`	`"start:stream": "tsx stream.ts"`
`15`	`16`	`}`
`16`	`17`	`}`