Prebuilt Agents in LangGraph: Classes or Functions?

[sydney-runkle]

In langgraph, we offer a prebuilt agent constructor create_react_agent, available in langgraph.prebuilt.

The goal of abstractions in our prebuilt module is to make it as easy as possible to get started with an agent that has access to (dynamic) tools, prompts, etc.

Usage looks something like:

from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

model = ChatOpenAI(model="gpt-4o", temperature=0)

@tool
def get_weather(city: str) -> str:
    ...

graph = create_react_agent(
    model, 
    tools=[get_weather], 
    prompt="You're a polite weather expert."
)

We’re currently debating whether or not we should continue down this functional route, or if we should use an object oriented approach, something like:

from langgraph.prebuilt import Agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool

model = ChatOpenAI(model="gpt-4o", temperature=0)

@tool
def get_weather(city: str) -> str:
    ...

agent = Agent(
    model, 
    tools=[get_weather], 
    prompt="You're a polite weather expert."
)

We’re looking for feedback on the interface that you, as a langgraph user would prefer. Here’s a few bullets on the strengths of each approach:

Function Based Approach

• More concise customization - simple arguments instead of method overrides
  • Implies superiority for simple use cases
• Clearer API boundaries - parameters / allowed values are well defined
  • Assistance is easier when guardrails are more strict
• Easier on ramp onto state graph result (fewer API changes)

Class Based Approach

• Higher ceiling - easier to customize via subclassing
• Cleaner developer experience (potentially generic on context, like agents sdk(https://openai.github.io/openai-agents-python/agents/#context))
  • Specifically managing state, which is currently obscured in the functional API
• Similar to most other agent frameworks (more gentle learning curve)
• Composability across a larger codebase - having a default Agent subclass you can further customize
  • Alternative with function based would be a partial 😵‍💫

Excited to hear thoughts from folks as we gear up for a major sprint on prebuilt functionality!

[jacoblee93]

+1 for functions!

If we are building prebuilts that are meaningfully reliant on implementation details of other prebuilts, that seems like a code smell to me and has the potential to get us into inheritance trouble (we learned this the hard way with AgentExecutor and the various agent subclasses of old LangChain).

If a prebuilt builds on top of previous prebuilts, we can do it via composition (like https://github.com/langchain-ai/langgraph-reflection) and just enforce that the externally facing inputs and outputs are as expected.

If certain patterns and architectures become very common (like if there were now many different flavors of ReAct agent) and there are specific things we need to do with them outside of just .invoke/stream/batch (not like the ReAct agent) I'd be more supportive of this but the last thing we want is a bunch of random classes for one-off prebuilts floating around that only expose .invoke.

tl;dr, IMO subclassing prebuilts or adding other prebuilt specific methods is an anti-pattern right now. In terms of how we'd use them, create_react_agent() is really no different from Agent() since we don't and shouldn't do anything with them other than invoke them. Functions enforce less dependence on specific implementations of other prebuilts, which is a good thing.

Open to concrete counterexamples of how classes would make our lives easier in ways composition wouldn't though.

[petermiller310]

+1 for functions!

[jriedel-mai]

Yes the reflection example gives me more confidence in the function based approach. Being able to extend prebuilts is becoming more necessary for me as the react agent (main model behind the scenes) is not the most reliable and employing another LLM as a judge helps make the entire system more reliable.

[chaliy]

One problem I had with create_react_agent especially on early stages, was the ability to extend. Most of the small things, that could be done with simple override, were requiring exploding it to manual reimplementation of the graph.
Personally I think having Agent abstraction and concrete implementations like ReACT Agent, SupervisorAgent, etc, would give more flexibility. Also I think Agent class abstraction, would work more naturally in multi-Agent communicstion pattens, which will require metadata for discoverbility and contracts.

[chriszs]

Por que no los dos? That is, an Agent class for subclassing with a factory function for backwards compatibility and convenience.

[Viicos]

Having both is a common Python pattern, used in the stdlib as well. See for instance the timeit module:

def timeit(stmt="pass", setup="pass", timer=default_timer,
           number=default_number, globals=None):
    """Convenience function to create Timer object and call timeit method."""
    return Timer(stmt, setup, timer, globals).timeit(number)

or the json module, giving the ability to provide the class as an argument:

import json

class ComplexEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, complex):
            return [obj.real, obj.imag]
        # Let the base class default method raise the TypeError
        return super().default(obj)

json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'

[VishnuRathore98]

+1 For functional approach, it will be lighter, easier, and quicker for implementation.

[jriedel-mai]

+1 For Functions just based on my gut as an Software Engineer. I do have experience with create_react_agent but I ended up creating my own (using the underlying code as inspiration) because I had the desire to add an LLM judge/evaluator that works hand in hand with the main agent in the react design. The evaluator would double check the main agent's process and ensure they were taking the right steps. I could not extend the original react agent to do this out of the box but I was able to create my own version using the code behind the scenes. If anything leveraging the code behind the function helped me learn the components that allow you to customize your graph. I know there is a reflection graph but thought it would be fun to build my own react function.

[wjaskowski]

+1 for classes

More concise customization - simple arguments instead of method overrides

Classes have constructors which also have arguments. So classes are as simple as function as it comes to concise customization IMO.

Clearer API boundaries - parameters / allowed values are well defined

Again, the same API boundaries are for constructor's parameters. I don't see how function have an edge here.

Arguments for classes:

• Class implementation is easier to read. Instead of having nested functions where arguments of the inner ones are mixed up together with the outer ones, there could be clear separation.
• Classes have types so an object of a class can be passed to other function with a clear type annotation (f(x: ReactAgent)) which makes the code easier to maintain.

[Vert53]

My own personal experience was using create_react_agent for a quick prototype used to evaluate the agentic approach on the use case at my company, assuming that we will have to customize a lot of stuff when wanting it to level up to a real product.
So that point about "Higher ceiling - easier to customize via subclassing" for me is the most important.
Maybe possible to have both?
Look even o3 agrees https://chatgpt.com/share/680cf3a9-d470-800c-a98e-8c8d2ec1c7ed