Proposal: Introduce Runnable interface to unify “runnables”

[araujof]

Hi BeeAi community, I'd love to hear your thoughts on this proposal.

Thanks to @jenna-winkler, @Tomas2D, @antonpibm, @michael-desmond, @terylt, @imolloy for your inputs and help with this proposal!

Current Challenge

BeeAI Framework currently implements many objects that can be invoked with a run method, but these implementations are inconsistent and lack a unified interface. This creates several issues:

1. Inconsistent Method Signatures: The arguments, argument names, and argument types of run methods vary across objects, even for objects of the same kind
2. Lack of Type Safety: Many classes use *args: Any, **kwargs: Any patterns that provide flexibility but sacrifice:
   • Explicitness (unclear function signatures)
   • Type checking capabilities
   • Documentation clarity
3. Loosely Defined Interfaces: For example, BaseAgent currently defines:

   @abstractmethod
   def run(self, *args: Any, **kwargs: Any) -> Run[TOutput]:
       pass

This approach limits discoverability, makes the codebase harder to maintain, and places a burden on developers to learn and manage heterogeneous abstractions.

Proposal

Introduce a unified interface and set of abstractions for "runnables" - components that encapsulate executable logic—across various modules. The goal is to standardize the interface, reduce boilerplate, and improve type safety and extensibility.

The new Runnable interface defines explicit types for input, output, and execution options for runnable objects.

Key Points:

• Unified run Method: Standardizes the run method signature across modules.
• Consistent Input Handling: The input parameter is always the first and only positional argument.
• No Generics: Avoids generics in favor of standardizing input/output types within implementations.
• Type Hints Preserved: Maintains type hints for better developer experience and static analysis.
• Simplified Implementation: Users can leverage decorators instead of manual invocation of RunContext.enter() and handler wrapping.
• Bonus it does not drastically break existing interfaces, easy to migrate.

Reference: proposal.

Questions

• This proposal aims at refactoring agents, workflows, and the chat model to implement the Runnable interface. Should tools subclass Runnable, or have their own separate interface? One issue to consider is that tools can have arbitrary input/output types.
• Should Runnable's input be typed as str | list[AnyMessage]?
• Should RunnableOutput's output be a list[AnyMessage]?

[iChintanSoni]

Here's my take on it:

1. Should tools also implement the Runnable interface? Yes. This improves composability with agents and workflows. While tools may have diverse input/output types, that can be managed with custom input/output models or by extending RunnableOptions and RunnableOutput.
2. Should Runnable inputs be typed as str | list[AnyMessage]? Yes. This makes calling agents and tools user-friendly and backward compatible. Internally, everything can normalize to list[AnyMessage].
3. Should RunnableOutput return a list[AnyMessage]? Yes. This better represents real-world outputs, especially in workflows or multi-turn interactions. It also aligns well with streaming or tracing multiple steps.

[marcosbodio]

Hello @araujof

I think this is overall a very good proposal. To answer your questions:

1. Should tools subclass Runnable, or have their own separate interface? I think tools should have their own separate interface.
2. Should Runnable's input be typed as str | list[AnyMessage]? As far as I can see we have AnyMessage: TypeAlias = Message[Any] (see here), and class Message(ABC, Generic[T]): (see here): so why do we need str | list[AnyMessage]? I think that using only list[AnyMessage] for the input type is simpler and sufficient.
3. Should RunnableOutput's output be a list[AnyMessage]? Yes, please. I think this makes things more uniform, and also simplifies composabilty where the output of one Runnable can directly be used as input of another Runnable

Let me ask a couple of questions:

1. you wrote above

No Generics: Avoids generics in favor of standardizing input/output types within implementations.
but in the end we have Message(ABC, Generic[T]). Can you explain what you mean?

2. Do you think a Runnable may need some sort of RunContext, for example for dependencies and so on?

[araujof]

Thanks much for the comments!

I updated the proposal and initial PR to reflect the discussion about the runnable output type.

@marcosbodio,

1. The statement was aimed specifically at the runnable classes in this case. In general, we want to reduce the reliance on generics and emphasize stronger and simpler abstractions, especially in externally consumable interfaces.
2. What do you mean by dependencies? We define a context dictionary in the runnable options and output object that can be used to pass and receive additional execution context in concrete implementations. The framework also defines a RunContext object that is used to wrap and place the runnable into an execution context that enables the injection of middleware, pre- and post- hooks, etc. This is why a Runnable returns Run[RunnableOutput], and not just RunnableOutput. Please let me know if you see any gaps that need to be addressed here.

[marcosbodio]

@araujof thank you for your answer: it clarifies my doubts. The context dictionary in the runnable options can be used effectively, so I think you do not need anything else: disregard my second question. Thank you.

[Tomas2D]

The proposal has been implemented and documented.