enhancement(agent): add returnRunResult option to agent.asTool() to expose RunResult and interruptions

.changeset/cuddly-poets-refuse.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-core': patch
+---
+
+Add `returnRunResult` option to `agent.asTool()` to expose full RunResult, including interruptions such as approvals.

docs/src/content/docs/guides/tools.mdx

@@ -85,6 +85,7 @@ Under the hood the SDK:
 - Creates a function tool with a single `input` parameter.
 - Runs the sub‑agent with that input when the tool is called.
 - Returns either the last message or the output extracted by `customOutputExtractor`.
+- If `returnRunResult` is set, returns the full `RunResult` so nested interruptions can be inspected.
 
 ---
 

examples/basic/tool-use-behavior.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Agent, run, tool } from '@openai/agents';
+import { Agent, run, tool, RunContext, RunResult } from '@openai/agents';
 
 const Weather = z.object({
   city: z.string(),
@@ -46,6 +46,19 @@ const agent3 = new Agent({
   tools: [getWeatherTool, saySomethingTool],
 });
 
+const agentWithRunResult = new Agent({
+  name: 'Tool agent with RunResult',
+  instructions,
+  toolUseBehavior: { stopAtToolNames: ['get_weather'] },
+  outputType: Weather,
+  tools: [getWeatherTool, saySomethingTool],
+});
+
+const weatherToolWithRunResult = agentWithRunResult.asTool({
+  toolName: 'weather_summary',
+  returnRunResult: true,
+});
+
 async function main() {
   const input = 'What is the weather in San Francisco?';
   const result = await run(agent, input);
@@ -65,6 +78,12 @@ async function main() {
   const finalOutput3 = result3.finalOutput;
   // The weather in San Francisco is sunny. Thanks for asking!
   console.log(finalOutput3);
+
+  const result4 = (await weatherToolWithRunResult.invoke(
+    new RunContext(),
+    JSON.stringify({ input }),
+  )) as RunResult<any, Agent<any, any>>;
+  console.log('agentWithRunResult.newItems:', result4.newItems);
 }
 
 main();

examples/docs/tools/agentsAsTools.ts

@@ -10,7 +10,17 @@ const summarizerTool = summarizer.asTool({
   toolDescription: 'Generate a concise summary of the supplied text.',
 });
 
+const echoAgent = new Agent({
+  name: 'Echo',
+  instructions: 'Repeat whatever the user says.',
+});
+
+const echoTool = echoAgent.asTool({
+  toolName: 'echo_text',
+  returnRunResult: true,
+});
+
 const mainAgent = new Agent({
   name: 'Research assistant',
-  tools: [summarizerTool],
+  tools: [summarizerTool, echoTool],
 });

packages/agents-core/src/agent.ts

@@ -444,8 +444,22 @@ export class Agent<
     customOutputExtractor?: (
       output: RunResult<TContext, Agent<TContext, any>>,
     ) => string | Promise<string>;
-  }): FunctionTool {
-    const { toolName, toolDescription, customOutputExtractor } = options;
+    /**
+     * If true, the invoked tool will return the {@link RunResult} of the agent
+     * run instead of just the extracted output text.
+     */
+    returnRunResult?: boolean;
+  }): FunctionTool<
+    TContext,
+    any,
+    string | RunResult<TContext, Agent<TContext, any>>
+  > {
+    const {
+      toolName,
+      toolDescription,
+      customOutputExtractor,
+      returnRunResult,
+    } = options;
     return tool({
       name: toolName ?? toFunctionToolName(this.name),
       description: toolDescription ?? '',
@@ -469,6 +483,9 @@ export class Agent<
         const result = await runner.run(this, data.input, {
           context: context?.context,
         });
+        if (returnRunResult) {
+          return result as RunResult<TContext, Agent<TContext, any>>;
+        }
         if (typeof customOutputExtractor === 'function') {
           return customOutputExtractor(result as any);
         }

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

@@ -3,7 +3,11 @@ import { Agent } from '../src/agent';
 import { RunContext } from '../src/runContext';
 import { Handoff, handoff } from '../src/handoff';
 import { z } from 'zod/v3';
-import { JsonSchemaDefinition, setDefaultModelProvider } from '../src';
+import {
+  JsonSchemaDefinition,
+  setDefaultModelProvider,
+  RunResult,
+} from '../src';
 import { FakeModelProvider } from './stubs';
 
 describe('Agent', () => {
@@ -198,6 +202,67 @@ describe('Agent', () => {
     const result1 = agent.processFinalOutput('{"message": "Hi, how are you?"}');
     expect(result1).toEqual({ message: 'Hi, how are you?' });
   });
+
+  it('should return a RunResult when returnRunResult option is true', async () => {
+    const agent = new Agent({
+      name: 'Test Agent',
+      instructions: 'You do tests.',
+    });
+    const tool = agent.asTool({ returnRunResult: true });
+    setDefaultModelProvider(new FakeModelProvider());
+    const result = await tool.invoke({} as any, '{"input":"hello"}');
+    expect(result).toBeInstanceOf(RunResult);
+    expect((result as RunResult<any, Agent<any, any>>).finalOutput).toBe(
+      'Hello World',
+    );
+  });
+
+  it('should expose finalOutput with stopAtToolNames using returnRunResult', async () => {
+    setDefaultModelProvider(new FakeModelProvider());
+
+    const subAgent = new Agent({
+      name: 'Echo',
+      instructions: 'Repeat what the user says.',
+    });
+
+    const queryTool = subAgent.asTool({
+      toolName: 'query_action_logs',
+      toolDescription: 'Echo tool that represents a long-running tool',
+    });
+
+    const outerAgent = new Agent({
+      name: 'Parent',
+      instructions: 'Use the tool then stop.',
+      tools: [queryTool],
+      toolUseBehavior: { stopAtToolNames: ['query_action_logs'] },
+    });
+
+    const outerToolDefault = outerAgent.asTool({
+      toolName: 'get_action_logs',
+    });
+
+    const outerToolWithRunResult = outerAgent.asTool({
+      toolName: 'get_action_logs_rich',
+      returnRunResult: true,
+    });
+
+    const input = JSON.stringify({ input: 'hello' });
+
+    const resultDefault = await outerToolDefault.invoke(
+      new RunContext({}),
+      input,
+    );
+    expect(resultDefault).toBe('Hello World');
+
+    const resultWithRunResult = await outerToolWithRunResult.invoke(
+      new RunContext({}),
+      input,
+    );
+    expect(
+      (resultWithRunResult as RunResult<any, Agent<any, any>>).finalOutput,
+    ).toBe('Hello World');
+  });
+
   it('should process final output (json schema)', async () => {
     const agent = new Agent({
       name: 'Test Agent',