feat: automatic back-handoff to orchestrating agents

[Oxygen56]

Implements automatic back-handoff support as requested in #847.

When an agent is reached via a handoff, it can now automatically hand back to the originating agent upon completion by setting auto_handoff_back=True on the handoff configuration.

Problem

Currently, handoffs are one-way. Once an agent hands off control to another agent, it will never regain control without explicit circular handoff configurations. This makes orchestration patterns (where a main agent delegates to specialists and expects results back) tedious to implement.

Solution

This PR adds an auto_handoff_back: bool = False parameter to the Handoff class and handoff() factory function. When enabled:

• The handoff chain is tracked in the run loop
• When the child agent produces a final output, control automatically returns to the originating agent
• The child's output is appended as a message in the conversation so the parent can use it

Changes

• src/agents/handoffs/__init__.py: Add auto_handoff_back field to Handoff class and handoff() factory
• src/agents/run_internal/run_steps.py: Extend NextStepHandoff to carry auto-handoff-back metadata
• src/agents/run_internal/turn_resolution.py: Pass auto-handoff-back info through execute_handoffs()
• src/agents/run.py: Track handoff chain and handle auto back-handoff in non-streaming path
• src/agents/run_internal/run_loop.py: Track handoff chain and handle auto back-handoff in streaming path
• tests/test_auto_handoff_back.py: Comprehensive tests for auto back-handoff behavior

Usage

from agents import Agent, Runner, handoff

specialist = Agent(name="specialist", instructions="...")
orchestrator = Agent(
    name="orchestrator",
    instructions="...",
    handoffs=[
        handoff(specialist, auto_handoff_back=True)
    ]
)

result = await Runner.run(orchestrator, "help me with this")
# After specialist finishes, control returns to orchestrator
assert result.last_agent.name == "orchestrator"

Closes #847

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 792258f496

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Preserve positional is_enabled binding

This inserts auto_handoff_back before the existing is_enabled positional slot in the runtime implementation, so existing callers that passed is_enabled positionally now bind that value to auto_handoff_back and leave is_enabled at its default True. For example, a previously disabled handoff using positional arguments is silently re-enabled, which breaks the public API positional-compatibility contract; the new optional parameter needs to be appended after is_enabled or handled with a compatibility shim.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Feed the back-handoff result to streamed parent turns

In the streaming path, this synthetic child-result message is appended only to new_items/session items, but the next streamed turn is built from streamed_result._model_input_items (set earlier to pre_step_items + new_step_items). When Runner.run_streamed() auto-hands back, the parent agent is invoked without the specialist's final output in its model input, so the advertised orchestration pattern fails for streaming runs.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Persist the auto-handoff stack across resume

This stores the originating agent only in a local handoff_chain, but interruption results persist and resume from RunState, which does not include that local stack. If the child agent pauses for approval or another interruption after an auto handoff, resuming the run loses the parent agent, and the child's eventual final output is returned as the run result instead of handing control back.

Useful? React with 👍 / 👎.