Added support for "return" handoffs (#1)

[niv-hertz]

Related to issue: #847

[niv-hertz]

Could also solve the problem specified in: #858

@rm-openai - Would love your review

[rm-openai]

I thought about this for a while, and ultimately I think this doesn't belong in handoffs because the definition of a handoff is something that takes over control. Whether it chooses to return control should be up to the new agent.

That said, the problem identified is a real one. I think the right way to do it is via a FunctionTool that also receives the full conversation history. i.e. you do something like

@function_tool
def my_function(context, history, ... other args):

That function could then use an agent or not, but either way it has access to the conversation history.

Thoughts?

EDIT: Also, this should be really easy now bc of the ToolContext you added - can just add a history field with all the prev items in there.

[niv-hertz]

@rm-openai - Generally, I agree - this was actually my goto as well. There are, however two gaps with that implementation:

1. This doesn't affect the turns counting. Which you may want to control on a general scope, instead of on a per-function call level.
2. There's no easy support for streaming. One of the huge benefits of handing off, is that streaming is pretty much covered for you.

If you have any good solution for either of these with the function calls \ agent as tool approach, I'd love your input :)

EDIT: I also thought about using the existing handoffs mechanism, and as you suggested, giving the new agent the choice of whether to return control or not. But that seemed unnatural to me for two reasons:

1. The sub-agent is not aware of the wider instructions that the orchestrator has, so the choice of whether to return control or not, is not one it can properly make.
2. The Handoff object requires a reference to the agent (in the _on_invoke_handoff function), and the agent also contains a reference to the Handoff object. So if you want two agents to be able to handoff to each other, you're forced to implement some sort of circular reference (or hack around it) which is not good practice.

EDIT 2: Another option is to support something parallel to Handoffs, like SupervisedHandoff/Assignment/Sub-Workers

[niv-hertz]

@rm-openai @akhilsmokie - Bumping this :)

[sibblegp]

I assumed this was how it worked from the start and was surprised to find it didn't. This is a great addition.

How do we set it up after this is implemented to make sure sub-agents hand back off to the overall agent?

Also, does this slow things down since presumably the top agent is doing some AI API calls of its own? That would of course not be ideal.

[rm-openai]

@niv-hertz
The proposal makes sense and feels important. Do you mind if I take a bit of time and try and implement it myself? I think it's going to have some edge cases and documentation updates and it would overall probably be faster - happy to add you as co-author on the PR and get your feedback before merging.

Also happy to go back-and-forth on this PR, though that may take a little bit longer. LMK what you think!

[sibblegp]

@rm-openai I agree this is important. Is there any way I can help?

[niv-hertz]

@rm-openai - I'm definitely happy with you implementing it :)
If you need any helping hand, i'll obviously be happy to assist!

[niv-hertz]

@rm-openai - I'll close this PR for now, please let me know if you need any assistance or want to go back-and-forth on this PR :)

[built-by-as]

any movement here?

[github-actions]

This PR is stale because it has been open for 10 days with no activity.

[dhruvrnaik]

Any updates on this feature @rm-openai?
I think it is easy to get the input_history through context or session object if you define the function tool (instead of Agent.as_tool), but I am wondering what is the easiest way to get the pre_function_call_items ( same thing as pre_handoff_items ) in the function definition?