Allow to pass both session and input list

[DanieleMorotti]

Summary

This PR has been implemented to resolve #1140 . I added a parameter to the RunConfig object such that it can be specified if the given input list will replace the session history or it will be appended to it.

The current implementation is a possible approach but I would be happy to change the code if there are better solutions.

@seratch @rm-openai whenever you have a moment, please let me know your thoughts.

Test plan

I added 2 unit tests in tests/test_session.py.

Checks

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run make lint and make format
• I've made sure tests pass

[seratch]

To me, allowing to pass callback function here to combine the item list to save sounds more flexible. @rm-openai what do you think?

[DanieleMorotti]

Yes, this would offer much more flexibility.
However, would you still preserve the option for the users to specify "replace" or "append" in order to apply some predefined processing?

In that scenario, the RunConfig attribute could accept a Callable, a str or None.

Or would you prefer to have a more complex implementation like the one done for MCP filters (ToolFilterCallable, etc)?

[seratch]

Sessions are supposed to be used for maintaining conversation history across multiple agent runs. So, I don't think "replace" is a common use case. If "replace" works well, do you really need a session for the case?

If a developer would like to make some adjustments to stored history based on some conditions, that could be a valid use case (I still think it's an edge case though). That's why I thought enabling callback functions here would make more sense.

Let me know if I am missing anything!

[DanieleMorotti]

I agree. And what should happen if the callback function is left unspecified (None) and the input is a list? We may raise an error, as in the current implementation.

Moreover, does the callback function only take the history and the list of new items as input, or should I allow additional parameters?

[DanieleMorotti]

I implemented a new version, where the RunConfig attribute accepts a callback function that takes as input the history from the session and the new inputs.

Let me know what else should be improved.

[rm-openai]

I'm missing some context, what's the use case for this? I read the issue but couldn't quite figure it out

[gonzamordecki]

@rm-openai Adding some context, as I just faced this limitation:

An agent currently cannot be run using built-in sessions from the SDK while receiving two new inputs from the user. This is requested, for example, when passing an image and text (i.e., Product Image + “Do you have this product in black?”).