feat: #460 Enable to customize the internal runner for an agent as too (#481)

Author: seratch

.changeset/warm-ties-sort.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-core': patch
+---
+
+feat: #460 Enable to customize the internal runner for an agent as tool

examples/agent-patterns/agents-as-tools.ts

@@ -29,6 +29,19 @@ const orchestratorAgent = new Agent({
     spanishAgent.asTool({
       toolName: 'translate_to_spanish',
       toolDescription: "Translate the user's message to Spanish",
+      // You can customize both runner init options and additional options for its execution
+      runConfig: {
+        model: 'gpt-5',
+        modelSettings: {
+          providerData: {
+            reasoning: { effort: 'low' },
+            text: { verbosity: 'low' },
+          },
+        },
+      },
+      runOptions: {
+        maxTurns: 3,
+      },
     }),
     frenchAgent.asTool({
       toolName: 'translate_to_french',

packages/agents-core/src/agent.ts

@@ -26,7 +26,7 @@ import type {
 } from './types';
 import type { RunResult } from './result';
 import type { Handoff } from './handoff';
-import { Runner } from './run';
+import { NonStreamRunOptions, RunConfig, Runner } from './run';
 import { toFunctionToolName } from './utils/tools';
 import { getOutputText } from './utils/messages';
 import { isAgentToolInput } from './utils/typeGuards';
@@ -511,9 +511,23 @@ export class Agent<
     needsApproval?:
       | boolean
       | ToolApprovalFunction<typeof AgentAsToolNeedApprovalSchame>;
+    /**
+     * Run configuration for initializing the internal agent runner.
+     */
+    runConfig?: Partial<RunConfig>;
+    /**
+     * Additional run options for the agent (as tool) execution.
+     */
+    runOptions?: NonStreamRunOptions<TContext>;
   }): FunctionTool<TContext, typeof AgentAsToolNeedApprovalSchame> {
-    const { toolName, toolDescription, customOutputExtractor, needsApproval } =
-      options;
+    const {
+      toolName,
+      toolDescription,
+      customOutputExtractor,
+      needsApproval,
+      runConfig,
+      runOptions,
+    } = options;
     return tool({
       name: toolName ?? toFunctionToolName(this.name),
       description: toolDescription ?? '',
@@ -524,9 +538,11 @@ export class Agent<
         if (!isAgentToolInput(data)) {
           throw new ModelBehaviorError('Agent tool called with invalid input');
         }
-
-        const runner = new Runner();
-        const result = await runner.run(this, data.input, { context });
+        const runner = new Runner(runConfig ?? {});
+        const result = await runner.run(this, data.input, {
+          context,
+          ...(runOptions ?? {}),
+        });
         const outputText =
           typeof customOutputExtractor === 'function'
             ? await customOutputExtractor(result as any)

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

@@ -1,12 +1,17 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 import { Agent } from '../src/agent';
 import { RunContext } from '../src/runContext';
 import { Handoff, handoff } from '../src/handoff';
 import { z } from 'zod';
 import { JsonSchemaDefinition, setDefaultModelProvider } from '../src';
 import { FakeModelProvider } from './stubs';
+import { Runner } from '../src/run';
 
 describe('Agent', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it('should create an agent with default values', () => {
     const agent = new Agent({ name: 'TestAgent' });
 
@@ -206,6 +211,61 @@ describe('Agent', () => {
     expect(decision).toBe(true);
   });
 
+  it('passes runConfig and runOptions to the runner when used as a tool', async () => {
+    const agent = new Agent({
+      name: 'Configurable Agent',
+      instructions: 'You do tests.',
+    });
+    const mockResult = {} as any;
+    const runSpy = vi
+      .spyOn(Runner.prototype, 'run')
+      .mockImplementation(async () => mockResult);
+
+    const runConfig = {
+      model: 'gpt-5',
+      modelSettings: {
+        providerData: {
+          reasoning: { effort: 'low' },
+        },
+      },
+    };
+    const runOptions = {
+      maxTurns: 3,
+      previousResponseId: 'prev-response',
+    };
+    const customOutputExtractor = vi.fn().mockReturnValue('custom output');
+
+    const tool = agent.asTool({
+      toolDescription: 'You act as a tool.',
+      runConfig,
+      runOptions,
+      customOutputExtractor,
+    });
+
+    const runContext = new RunContext({ locale: 'en-US' });
+    const inputPayload = { input: 'translate this' };
+    const result = await tool.invoke(runContext, JSON.stringify(inputPayload));
+
+    expect(result).toBe('custom output');
+    expect(customOutputExtractor).toHaveBeenCalledWith(mockResult);
+    expect(runSpy).toHaveBeenCalledTimes(1);
+
+    const [calledAgent, calledInput, calledOptions] = runSpy.mock.calls[0];
+    expect(calledAgent).toBe(agent);
+    expect(calledInput).toBe(inputPayload.input);
+    expect(calledOptions).toMatchObject({
+      context: runContext,
+      maxTurns: runOptions.maxTurns,
+      previousResponseId: runOptions.previousResponseId,
+    });
+
+    const runnerInstance = runSpy.mock.instances[0] as unknown as Runner;
+    expect(runnerInstance.config.model).toBe(runConfig.model);
+    expect(runnerInstance.config.modelSettings).toEqual(
+      runConfig.modelSettings,
+    );
+  });
+
   it('should process final output (text)', async () => {
     const agent = new Agent({
       name: 'Test Agent',