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

[vrtnis]

This adds a returnRunResult option to agent.asTool() that allows developers to access the full RunResult of the sub-agent when invoked as a tool.

By default, asTool() only returns the final output string of the sub-agent, which means any interruptions (e.g. approval requests via needsApproval) are hidden from the parent agent.

With this flag enabled:

• The full RunResult is returned
• Interruptions are visible to the outer agent
• Human-in-the-loop and nested approval workflows now work as expected

This change is backward-compatible and opt-in. It does not affect any existing users of asTool().

Also, note that we have,

• Updated the "Agents as Tools" section in tools.mdx to explain the returnRunResult flag.
• Expanded the example in agentsAsTools.ts to include an echoTool using returnRunResult.
• Added a live usage example in tool-use-behavior.ts that demonstrates how to inspect RunResult.newItems.

Added tests to verify that:

• asTool({ returnRunResult: true }) returns a RunResult with the correct finalOutput.
• stopAtToolNames works without needing a customOutputExtractor, fixing #247.
• RunContext is properly used in .invoke() to satisfy typing and test runtime behavior.

Example usage:

agentB.asTool({
  toolName: 'agentB',
  returnRunResult: true,
});

Resolves #243 and also
Resolves #247 – asTool() now correctly returns finalOutput with stopAtToolNames, without requiring a custom extractor

Tested with pnpm test, pnpm link, and pnpm build-check.

[changeset-bot]

🦋 Changeset detected

Latest commit: 665a260

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@openai/agents-core	Patch
@openai/agents-openai	Patch
@openai/agents-realtime	Patch
@openai/agents	Patch
@openai/agents-extensions	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[seratch]

Thanks for sending this PR.

I don't yet have a clear idea of the best approach for this issue, but at a glance, this PR doesn't seem like the best solution for the linked issues to me. When an agent is attached as a tool, it should behave as a tool. Therefore, exposing the agent's run result as a tool output sounds like a different type of tool definition. Also, the agent that calls the sub-agent as a tool shouldn't need to know the difference between agent tools and other types of tools.

There are a few other things I am currently working on, but will check this issue sometime soon.

[vrtnis]

Thanks for the quick intial feedback!...yep, totally agree that when an agent is used as a tool, it should behave like one. The flag felt like the simplest, least disruptive way to support these issues. When returnRunResult is off, everything behaves as before (returning the usual string or object) and so existing code stays unchanged.

We only get the richer RunResult when we explicitly opt in, which means the parent agent doesn’t need to treat agent tools differently unless that extra detail is wanted (like in #247’s missing finalOutput).

We could also ship an AgentAsToolWithInterruptions helper (see LuminaX-alt#6) to auto-copy interruptions, but that wouldn’t address the finalOutput issue either, so the flag felt like the cleaner path overall.

I guess the broader question is: since there are already other flags and possibly more coming wondering if it might be worth thinking about whether these kinds of options should live under an experimental umbrella, similar to how Cloudflare Workers support is presently marked. Just some thoughts. Happy to address changes or restart with a different approach.

[mhashas]

Ok, so as I understand, there's a bit of incompatibility between the two options:

stopAtToolNames

• The final output will be the output of the first tool in the list that was called.

asTool

• If not provided, the last message from the agent will be used.

When we talk about the last message from the agent, we're talking about the last message from the history that comes from the assistant, not the last message from the history? Any reason why we want the last message to strictly be from the assistant?

[vrtnis]

Ok, so as I understand, there's a bit of incompatibility between the two options:

stopAtToolNames

• The final output will be the output of the first tool in the list that was called.

asTool

• If not provided, the last message from the agent will be used.

When we talk about the last message from the agent, we're talking about the last message from the history that comes from the assistant, not the last message from the history? Any reason why we want the last message to strictly be from the assistant?

@mhashas i've answered this in #247 (comment). thought this clarification belongs in #247 as #249 is the proposed implementation path that avoids needing a custom extractor.