enhancement(agent): include interruptions in run result when using agent-as-tool

Author: vrtnis

.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.
 
 ---
 

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,21 @@ 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 process final output (json schema)', async () => {
     const agent = new Agent({
       name: 'Test Agent',