Support serializable object as input to agent run

[strawgate]

Description

I find myself building agents and always having to either 1) place their inputs in their deps_type 2) forcing the caller to know what information to provide the Agent in the user prompt or 3) providing a helper function that translates input into instructions before calling run

Placing required inputs in deps_type is awkward as ideally you'd share dependencies but inputs are not often shared when running multi agent

It would be nice if the agents had a definable input_model -- this would remove a lot of boiler plate for making agents callable as tools (and thus callable by other agents)

References

No response

[HamzaFarhan]

Defining an output_type means that we will get an instance of that when the run completes.
So defining an input_model would mean it would get an instance of that for a run, right? But then how would it be added to the prompt? Automatic model_dump_json() appended to the instructions? or user_prompt?

[strawgate]

I think the default could certainly be a model_dump_json (or string repr?) but ideally it would be made available via the instructions decorator so you could automatically turn the input model into instructions

[DouweM]

@strawgate This makes sense, I've wanted it myself as well. The way I imagine it is that you'd pass an input argument to run/run_sync/run_stream/iter, which would then be available on RunContext inside a dynamic instructions function so you can do your own serialization.

It should also be respected if there are no dynamic instructions though, so maybe if user_prompt is ommitted from the run call, we automatically insert format_as_xml(input)? (XML generally works better than JSON for input)

[strawgate]

moving discussion from #2393 (comment) back to the issue

maybe a simpler approach could be that InputAgent is defined with an Agent, an input_model, and a func which takes the input_model and returns the deps_type or deps_type + add't instructions?

maybe the input agent model has its own deps_type as well? That way the inputagent deps_type could be the same as the rest of the graph but the underlying Agent could leverage the add't information?

[DouweM]

maybe a simpler approach could be that InputAgent is defined with an Agent, an input_model, and a func which takes the input_model and returns the deps_type or deps_type + add't instructions?

@strawgate I like the concept of an InputAgent with a custom function to process the input_model argument into args for the wrapped run and iter methods' deps, instructions, or user_prompt args. Instead of one method that can return some combination of those, it may be nice to have a function arg for each that takes a lambda that takes the input model (and deps?) and can then return a value.

maybe the input agent model has its own deps_type as well? That way the inputagent deps_type could be the same as the rest of the graph but the underlying Agent could leverage the add't information?

Can you show an example of this? Having the InputModel take some deps object + input_model that are then merged into a new deps for the wrapped agent, seems reasonable.

[strawgate]

I spent some time implementing this today and I definitely think this can work well.

However, I can't shake the feeling that if all we're doing is preparing the agent to be run that perhaps we should actually just do this in an AgentToolset with an AgentToolsetTool which does this.

I may make a PR to this effect for us to look at

I'm also starting to think that adding an input model to the agent is probably not worth it if it means requiring custom dep classes.

[HamzaFarhan]

Also I'm assuming in most cases having dynamic instructions with ctx.something or even ctx.toolset.call_tool would be good enough and more adaptable.

[strawgate]

I made a quick draft PR here #2589 which shows handoffs via an Agent Toolset / .handoff method on the Agent

Includes input model, func to go from input model to user_prompt and a func to go from input model + calling agent deps to called agent deps