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