feat: allow set reasoningEffort in AIAgentArgs (#3241)

## Description

This PR adds an optional `reasoningEffort` setting to AI Agent arguments
so GPT-5 model calls can control reasoning effort per agent
configuration.

## Context

GPT-5 requests previously used a fixed reasoning effort. Exposing this
setting lets consumers tune inference behavior while keeping a default
value when no explicit effort is provided.

## Approach taken / Explain the design

- Added a shared `ReasoningEffort` enum to `@botonic/core` and exposed
it through `AiAgentBaseArgs`.
- Propagated `reasoningEffort` from the AI Agents plugin into
`LLMConfig` for both specialist and router agents.
- Updated GPT-5 model settings to use the provided effort, defaulting to
`medium`; non-GPT-5 fallback settings continue using `none`.
- Bumped `@botonic/plugin-core` to `0.51.1` and
`@botonic/plugin-ai-agents` to `0.51.1`.

## Testing

The pull request has unit test coverage for the default GPT-5 reasoning
effort in `LLMConfig`.

Author: Iru89

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@botonic/core",
-  "version": "0.51.0",
+  "version": "0.51.1",
   "license": "MIT",
   "description": "Build Chatbots using React",
   "main": "./lib/cjs/index.js",

packages/botonic-core/package.json

@@ -116,6 +116,13 @@ export enum VerbosityLevel {
   High = 'high',
 }
 
+export enum ReasoningEffort {
+  None = 'none',
+  Low = 'low',
+  Medium = 'medium',
+  High = 'high',
+}
+
 export interface HubtypeAssistantMessage {
   role: 'assistant'
   content: string
@@ -139,6 +146,7 @@ export type AiAgentBaseArgs = {
   instructions: string
   model: string
   verbosity: VerbosityLevel
+  reasoningEffort?: ReasoningEffort
   inputGuardrailRules?: GuardrailRule[]
   previousHubtypeMessages?: HubtypeAssistantMessage[]
   outputMessagesSchemas?: z.ZodObject<any>[]

packages/botonic-core/src/models/ai-agents.ts

@@ -1,6 +1,6 @@
 {
   "name": "@botonic/plugin-ai-agents",
-  "version": "0.51.0",
+  "version": "0.51.1",
   "main": "./lib/cjs/index.js",
   "module": "./lib/esm/index.js",
   "description": "Use AI Agents to generate your contents",
@@ -14,7 +14,7 @@
     "format": "biome format --write src/ tests/"
   },
   "dependencies": {
-    "@botonic/core": "^0.51.0",
+    "@botonic/core": "^0.51.1",
     "@openai/agents": "^0.10.1",
     "axios": "^1.15.2",
     "openai": "^6.36.0",

packages/botonic-plugin-ai-agents/package.json

@@ -6,6 +6,7 @@ import {
   type BotContext,
   type HubtypeAssistantMessage,
   type Plugin,
+  type ReasoningEffort,
   type ResolvedPlugins,
 } from '@botonic/core'
 import { handoff, setTracingDisabled, tool } from '@openai/agents'
@@ -86,6 +87,8 @@ export default class BotonicPluginAiAgents<
       throw new Error('Auth token is required')
     }
 
+    const reasoningEffort = aiAgentArgs.reasoningEffort
+
     const inferenceId = uuidv7()
 
     try {
@@ -94,7 +97,8 @@ export default class BotonicPluginAiAgents<
           botContext,
           aiAgentArgs,
           authToken,
-          inferenceId
+          inferenceId,
+          reasoningEffort
         )
       }
 
@@ -103,7 +107,8 @@ export default class BotonicPluginAiAgents<
           botContext,
           aiAgentArgs,
           authToken,
-          inferenceId
+          inferenceId,
+          reasoningEffort
         )
       }
 
@@ -130,14 +135,16 @@ export default class BotonicPluginAiAgents<
     botContext: BotContext<TPlugins, TExtraData>,
     aiAgentArgs: AiAgentSpecialistArgs,
     authToken: string,
-    inferenceId: string
+    inferenceId: string,
+    reasoningEffort?: ReasoningEffort
   ) {
     const llmConfig = new LLMConfig({
       maxRetries: this.maxRetries,
       timeout: this.timeout,
       modelName: aiAgentArgs.model,
       verbosity: aiAgentArgs.verbosity,
       botContext,
+      reasoningEffort,
     })
 
     // Get LLM config, tools and agent
@@ -190,7 +197,8 @@ export default class BotonicPluginAiAgents<
     botContext: BotContext<TPlugins, TExtraData>,
     aiAgentArgs: AIAgentRouterArgs,
     authToken: string,
-    inferenceId: string
+    inferenceId: string,
+    reasoningEffort?: ReasoningEffort
   ) {
     const { specialists, name, instructions } = aiAgentArgs
 
@@ -200,6 +208,7 @@ export default class BotonicPluginAiAgents<
       modelName: aiAgentArgs.model,
       verbosity: aiAgentArgs.verbosity,
       botContext,
+      reasoningEffort,
     })
 
     const specialistsAgents = await Promise.all(

packages/botonic-plugin-ai-agents/src/index.ts

@@ -1,4 +1,4 @@
-import type { BotContext, VerbosityLevel } from '@botonic/core'
+import { type BotContext, ReasoningEffort, VerbosityLevel } from '@botonic/core'
 import {
   type Model,
   type ModelProvider,
@@ -24,6 +24,7 @@ export interface LLMConfigParams {
   modelName: string
   verbosity: VerbosityLevel
   botContext: BotContext
+  reasoningEffort?: ReasoningEffort
 }
 
 export class LLMConfig {
@@ -33,13 +34,15 @@ export class LLMConfig {
   public readonly modelName: string
   public readonly modelSettings: ModelSettings
   public readonly modelProvider: ModelProvider
+  public readonly reasoningEffort?: ReasoningEffort
 
   constructor({
     maxRetries,
     timeout,
     modelName,
     verbosity,
     botContext,
+    reasoningEffort,
   }: LLMConfigParams) {
     this.maxRetries = maxRetries
     this.timeout = timeout
@@ -48,6 +51,7 @@ export class LLMConfig {
       LLM_PROVIDER === LLM_PROVIDERS.OPENAI ? LLM_OPENAI_MODEL : modelName
     this.modelProvider = this.getModelProvider()
     this.modelSettings = this.getModelSettings(modelName, verbosity)
+    this.reasoningEffort = reasoningEffort
   }
 
   async getModel(): Promise<Model> {
@@ -141,7 +145,7 @@ export class LLMConfig {
   ): ModelSettings {
     if (model.includes('gpt-5')) {
       return {
-        reasoning: { effort: 'none' },
+        reasoning: { effort: this.reasoningEffort ?? ReasoningEffort.Medium },
         temperature: 1,
         text: { verbosity },
       }
@@ -150,13 +154,13 @@ export class LLMConfig {
     if (model.includes('gpt-4')) {
       return {
         temperature: 0,
-        text: { verbosity: 'medium' },
+        text: { verbosity: VerbosityLevel.Medium },
       }
     }
 
     // LiteLLM can proxy any model — fall back to reasoning settings
     return {
-      reasoning: { effort: 'none' },
+      reasoning: { effort: ReasoningEffort.None },
       temperature: 1,
       text: { verbosity },
     }

packages/botonic-plugin-ai-agents/src/llm-config.ts

@@ -150,7 +150,7 @@ describe('LLMConfig', () => {
       })
 
       expect(config.modelSettings).toEqual({
-        reasoning: { effort: 'none' },
+        reasoning: { effort: 'medium' },
         temperature: 1,
         text: { verbosity: 'high' },
       })