SOLID Principles in Python, Explained by Building a LangGraph Agent
SOLID principles in Python, explained by building one LangGraph support agent: single responsibility, open/closed, Liskov, interface segregation, DIP.
By Saksham Malhotra · · 15 min read
- solid principles
- python
- langgraph
- low level design
- lld
- ai agents

TL;DR
- S, Single Responsibility: one class, one reason to change.
- O, Open/Closed: add behaviour by adding a class, not by editing one that works.
- L, Liskov Substitution: every subclass must keep the parent’s promise. No type checks at the call site.
- I, Interface Segregation: small interfaces. No class implements things it can’t support.
- D, Dependency Inversion: depend on interfaces and pass the real thing in. Don’t create concrete classes inside.
What are we building?
A customer support agent with LangGraph. A ticket comes in, and the graph:
- classifies it (bug, how-to or feature request),
- searches the help docs,
- drafts a reply, calling tools like an issue lookup when it needs facts,
- posts the draft to Slack for a human to approve.
Every node reads and updates one shared state:
class TicketState(TypedDict, total=False):
ticket: str
category: str
docs: list[str]
reply: str
Each principle has a Before and After class diagram. Click to switch.
<<abstract>>marks an interface.- A hollow arrow means “inherits from”.
- A plain arrow means “uses”, and a dashed one means “creates”.
- Red is the problem. Green is new code.
What is the Single Responsibility Principle?
A class should have one reason to change.
---
title: Before
---
classDiagram
direction LR
class SupportAgent {
+handle(state) dict
}
note for SupportAgent "classifies, searches docs, drafts and posts to Slack"
SupportAgent ..> ChatOpenAI : creates
SupportAgent ..> Chroma : creates
SupportAgent ..> WebClient : creates
class SupportAgent:::broken
classDef broken stroke:#f87171,stroke-width:2px,fill:#4a1414,color:#fecaca
---
title: After
---
classDiagram
direction LR
class TicketClassifier {
+classify(state) dict
}
class DocRetriever {
+retrieve(state) dict
}
class ReplyDrafter {
+draft(state) dict
}
class SlackPublisher {
+publish(state) dict
}
StateGraph --> TicketClassifier : node
StateGraph --> DocRetriever : node
StateGraph --> ReplyDrafter : node
StateGraph --> SlackPublisher : node
Before: one class does the whole job.
class SupportAgent:
def __init__(self):
self.llm = ChatOpenAI()
self.vector_store = Chroma(collection_name=DOCS_COLLECTION, embedding_function=OpenAIEmbeddings())
self.slack = WebClient(token=os.environ["SLACK_TOKEN"])
def handle(self, state: TicketState) -> dict:
category = self.llm.invoke(CLASSIFY_PROMPT.format(ticket=state["ticket"])).content
docs = [doc.page_content for doc in self.vector_store.similarity_search(state["ticket"], k=TOP_K)]
reply = self.llm.invoke(DRAFT_PROMPT.format(docs="\n".join(docs), ticket=state["ticket"])).content
self.slack.chat_postMessage(channel=SUPPORT_CHANNEL, text=reply)
return {"category": category, "docs": docs, "reply": reply}
It’s hard to extend. Tweaking the classifier prompt, changing how many docs come back, and moving from Slack to email all mean editing handle and retesting all four steps. A slip in one step breaks the other three.
After: one class per job. Each one becomes its own node in the graph.
class TicketClassifier:
def __init__(self):
self.llm = ChatOpenAI()
def classify(self, state: TicketState) -> dict:
prompt = CLASSIFY_PROMPT.format(ticket=state["ticket"])
return {"category": self.llm.invoke(prompt).content}
class SlackPublisher:
def __init__(self):
self.slack = WebClient(token=os.environ["SLACK_TOKEN"])
def publish(self, state: TicketState) -> dict:
self.slack.chat_postMessage(channel=SUPPORT_CHANNEL, text=state["reply"])
return {}
# DocRetriever.retrieve and ReplyDrafter.draft follow the same shape.
graph = StateGraph(TicketState)
graph.add_node("classify", TicketClassifier().classify)
graph.add_node("retrieve", DocRetriever().retrieve)
graph.add_node("draft", ReplyDrafter().draft)
graph.add_node("publish", SlackPublisher().publish)
graph.add_edge(START, "classify")
graph.add_edge("classify", "retrieve")
graph.add_edge("retrieve", "draft")
graph.add_edge("draft", "publish")
graph.add_edge("publish", END)
app = graph.compile()
A prompt change touches TicketClassifier alone. The other nodes and their tests stay untouched. LangGraph nudges you this way already, since every node is a separate step.
Each class still creates its own ChatOpenAI and WebClient. Dependency Inversion fixes that, and it’s covered last.
Think of a restaurant kitchen. The chef cooks and the waiter serves. Ask the chef to wait tables too, and the food burns the moment it gets busy.
What is the Open/Closed Principle?
Open to extension, closed to modification. A new feature should be a new class, not an edit to code that already works.
The drafter calls tools when it needs facts, like whether a bug is already known or whether there’s an outage.
---
title: Before
---
classDiagram
direction LR
class ToolRunner {
+run(tool_name, query) str
}
note for ToolRunner "if/elif on tool_name. A new tool means editing run()"
ReplyDrafter --> ToolRunner
class ToolRunner:::broken
classDef broken stroke:#f87171,stroke-width:2px,fill:#4a1414,color:#fecaca
---
title: After
---
classDiagram
direction TB
class Tool {
<<abstract>>
+name str
+run(query) str
}
class ToolRunner {
+run(tool_name, query) str
}
ReplyDrafter --> ToolRunner
ToolRunner --> Tool : tools_by_name
Tool <|-- IssueLookupTool
Tool <|-- StatusPageTool
Tool <|-- ReleaseNotesTool
note for Tool "each subclass documents itself in its own docstring"
class ReleaseNotesTool:::added
classDef added stroke:#4ade80,stroke-width:2px,stroke-dasharray:4 3,fill:#0f2a17,color:#bbf7d0
Before: one function knows every tool.
class ToolRunner:
def run(self, tool_name: str, query: str) -> str:
if tool_name == "issue_lookup":
return self.issues.get(query).summary()
elif tool_name == "status_page":
return requests.get(STATUS_PAGE_URL).json()["status"]
raise ValueError(f"Unknown tool: {tool_name}")
It’s hard to extend. Every new tool means editing run, which already serves the working ones. You retest all of them, and one wrong branch breaks a tool customers rely on.
After: one abstract class, one subclass per tool. Each tool describes itself in its own docstring.
class Tool(ABC):
"""Base class for agent tools. The model never sees this docstring."""
name: str
@abstractmethod
def run(self, query: str) -> str: ...
class IssueLookupTool(Tool):
"""Looks up a known bug by its issue id, like ENG-142, and returns its status."""
name = "issue_lookup"
def run(self, query: str) -> str:
return self.issues.get(query).summary()
class StatusPageTool(Tool):
"""Checks the public status page for ongoing outages."""
name = "status_page"
def run(self, query: str) -> str:
return requests.get(STATUS_PAGE_URL).json()["status"]
class ToolRunner:
def __init__(self, tools: list[Tool]):
self.tools_by_name = {tool.name: tool for tool in tools}
def run(self, tool_name: str, query: str) -> str:
return self.tools_by_name[tool_name].run(query)
A release notes tool is a new ReleaseNotesTool(Tool) with its own docstring and tests, added to the list passed to ToolRunner. ToolRunner, the drafter and the existing tools aren’t touched, so they can’t break.
How those docstrings actually reach the model is LangChain specific, so I’ve kept it for the end.
It’s the same idea as a camera with swappable lenses. A new lens clicks onto the mount you already have, and nobody opens up the camera body to fit it.
What is the Liskov Substitution Principle?
A subclass must work anywhere its parent works. The caller shouldn’t need to know which subclass it got.
---
title: Before
---
classDiagram
direction TB
class Tool {
<<abstract>>
+run(query) str
}
class IssueLookupTool {
+run(query) raises IssueNotFoundError
}
ToolRunner --> Tool
Tool <|-- IssueLookupTool
Tool <|-- StatusPageTool
note for IssueLookupTool "a typo in the issue id crashes the whole graph run"
class IssueLookupTool:::broken
classDef broken stroke:#f87171,stroke-width:2px,fill:#4a1414,color:#fecaca
---
title: After
---
classDiagram
direction TB
class Tool {
<<abstract>>
+run(query) str
}
class IssueLookupTool {
+run(query) str
}
ToolRunner --> Tool
Tool <|-- IssueLookupTool
Tool <|-- StatusPageTool
note for Tool "always returns text the model can read. A miss is text too, never an exception"
Before: the issue lookup raises when the id doesn’t exist.
class IssueLookupTool(Tool):
"""Looks up a known bug by its issue id, like ENG-142, and returns its status."""
def run(self, query: str) -> str:
issue = self.issues.get(query)
if issue is None:
raise IssueNotFoundError(query)
return issue.summary()
A customer pastes an issue id with a typo, the exception escapes the node, and the ticket never gets a reply. The usual patch is if isinstance(tool, IssueLookupTool): try ... except inside ToolRunner. Now ToolRunner has to know every special case, and each new tool means editing it again, retesting it, and hoping the others still work.
After: write the promise on the parent’s run, and keep it in every subclass.
class Tool(ABC):
@abstractmethod
def run(self, query: str) -> str:
"""Returns text the model can read. A miss is text too, never an exception."""
class IssueLookupTool(Tool):
"""Looks up a known bug by its issue id, like ENG-142, and returns its status."""
def run(self, query: str) -> str:
issue = self.issues.get(query)
if issue is None:
return f"No issue found with id {query}. Ask the customer for the link to it."
return issue.summary()
The two docstrings have different readers. The one on run is the contract for developers writing tools. The class docstring is what the model reads. More on that at the end.
The model reads the “No issue found” text and asks the customer for the right link, which is better behaviour anyway. ToolRunner works with every tool without checking which one it has. A new tool only has to keep the promise. If a subclass truly can’t keep it, that behaviour doesn’t belong on the parent. Interface Segregation, next, deals with exactly that.
Think of booking a sedan on a rental app. You don’t care which one shows up, as long as it drives like a sedan. If it needs a special licence, the booking lied to you.
What is the Interface Segregation Principle?
No class should be forced to implement things it doesn’t use. Several small interfaces beat one that tries to describe everyone.
---
title: Before
---
classDiagram
direction TB
class KnowledgeBase {
<<abstract>>
+search(query, limit) list
+add_documents(documents)
+delete_documents(document_ids)
}
class HelpCenterSearch {
+search(query, limit) list
+add_documents() raises NotImplementedError
+delete_documents() raises NotImplementedError
}
KnowledgeBase <|-- ChromaKnowledgeBase
KnowledgeBase <|-- HelpCenterSearch
class HelpCenterSearch:::broken
classDef broken stroke:#f87171,stroke-width:2px,fill:#4a1414,color:#fecaca
---
title: After
---
classDiagram
direction TB
class Searchable {
<<abstract>>
+search(query, limit) list
}
class Indexable {
<<abstract>>
+add_documents(documents)
+delete_documents(document_ids)
}
Searchable <|-- ChromaKnowledgeBase
Indexable <|-- ChromaKnowledgeBase
Searchable <|-- HelpCenterSearch
DocRetriever --> Searchable
DocIngestor --> Indexable
Before: the docs interface was written for our own Chroma store, which we search and also re-index every night.
class KnowledgeBase(ABC):
@abstractmethod
def search(self, query: str, limit: int) -> list[str]: ...
@abstractmethod
def add_documents(self, documents: list[str]) -> None: ...
@abstractmethod
def delete_documents(self, document_ids: list[str]) -> None: ...
Then we add the public help center’s search API as a second source. It’s read only, so add_documents and delete_documents just raise NotImplementedError. Adding metadata to add_documents later changes an interface every source implements. Every source gets edited and retested, even the read only one. (Those NotImplementedError methods break Liskov Substitution too. The two often show up together.)
After: split by what each user of the interface actually needs.
class Searchable(ABC):
@abstractmethod
def search(self, query: str, limit: int) -> list[str]: ...
class Indexable(ABC):
@abstractmethod
def add_documents(self, documents: list[str]) -> None: ...
@abstractmethod
def delete_documents(self, document_ids: list[str]) -> None: ...
class ChromaKnowledgeBase(Searchable, Indexable): ...
class HelpCenterSearch(Searchable): ...
The retrieve node only needs Searchable. The nightly DocIngestor job only needs Indexable. A change to indexing touches Indexable and Chroma, and the help center source doesn’t change. Hand a HelpCenterSearch to DocIngestor and mypy or pyright flags it before it runs.
Job posts work the same way. Nobody hiring a waiter asks them to cook as well, just in case.
What is the Dependency Inversion Principle?
High level classes, like the graph’s nodes, shouldn’t depend on low level details like OpenAI, Chroma or Slack. Both should depend on an interface, and the concrete class is passed in.
---
title: Before
---
classDiagram
direction LR
TicketClassifier ..> ChatOpenAI : creates
ReplyDrafter ..> ChatOpenAI : creates
DocRetriever ..> Chroma : creates
SlackPublisher ..> WebClient : creates
class TicketClassifier:::broken
class ReplyDrafter:::broken
class DocRetriever:::broken
class SlackPublisher:::broken
classDef broken stroke:#f87171,stroke-width:2px,fill:#4a1414,color:#fecaca
---
title: After
---
classDiagram
direction TB
class BaseChatModel {
<<abstract>>
}
class Searchable {
<<abstract>>
}
class ReplyChannel {
<<abstract>>
+send(text)
}
TicketClassifier --> BaseChatModel
ReplyDrafter --> BaseChatModel
DocRetriever --> Searchable
ReplyPublisher --> ReplyChannel
BaseChatModel <|-- ChatOpenAI
BaseChatModel <|-- ChatOllama
BaseChatModel <|-- FakeListChatModel
ReplyChannel <|-- SlackChannel
ReplyChannel <|-- EmailChannel
class ChatOllama:::added
class FakeListChatModel:::added
class EmailChannel:::added
classDef added stroke:#4ade80,stroke-width:2px,stroke-dasharray:4 3,fill:#0f2a17,color:#bbf7d0
Before: every node from the Single Responsibility section creates its own ChatOpenAI, Chroma or WebClient. Running a local model in development, or posting drafts to email, means editing the nodes themselves and retesting the whole graph. And the tests can’t run without calling OpenAI and posting into a real Slack channel.
After: nodes ask for interfaces in __init__. One function wires in the real classes.
class ReplyChannel(ABC):
@abstractmethod
def send(self, text: str) -> None: ...
class ReplyPublisher:
def __init__(self, channel: ReplyChannel):
self.channel = channel
def publish(self, state: TicketState) -> dict:
self.channel.send(state["reply"])
return {}
class TicketClassifier:
def __init__(self, llm: BaseChatModel):
self.llm = llm
def build_support_graph(llm: BaseChatModel, knowledge_base: Searchable, channel: ReplyChannel, tools: list[Tool]):
graph = StateGraph(TicketState)
graph.add_node("classify", TicketClassifier(llm).classify)
graph.add_node("retrieve", DocRetriever(knowledge_base).retrieve)
graph.add_node("draft", ReplyDrafter(llm, ToolRunner(tools)).draft)
graph.add_node("publish", ReplyPublisher(channel).publish)
# same edges as before
return graph.compile()
You don’t have to write the LLM interface yourself. LangChain’s BaseChatModel already is one, and ChatOpenAI, ChatOllama and the rest all inherit from it.
# production
app = build_support_graph(ChatOpenAI(), ChromaKnowledgeBase(), SlackChannel(), [IssueLookupTool(), StatusPageTool()])
# test: no API calls, no Slack
class FakeToolCallingModel(FakeListChatModel):
def bind_tools(self, tools, **kwargs):
return self # FakeListChatModel can't bind tools, see the LangChain and LangGraph section below
llm = FakeToolCallingModel(responses=["how-to", "Go to Settings, then Export, and pick CSV."])
channel = FakeChannel()
app = build_support_graph(llm, InMemorySearch(HELP_DOCS), channel, [StatusPageTool()])
app.invoke({"ticket": "How do I export my data?"})
assert channel.sent == ["Go to Settings, then Export, and pick CSV."]
Moving drafts to email means passing in an EmailChannel, and a local model means passing in ChatOllama. The nodes and their tests don’t change.
Not everything needs an interface. ToolRunner stays a concrete class because there’s only one. Add the interface when a second implementation shows up.
Your phone charger already works like this. It plugs into the wall socket and couldn’t care less whether the power comes from coal or solar.
LangChain and LangGraph specifics: how tools reach the model
Back to the tools from the Open/Closed section. The model never sees your Python. It only sees each tool’s name and description, and picks a tool from those. LangChain’s @tool decorator reads a function’s docstring as its description and refuses a function without one. Class based tools need the same guarantee, so Tool grows three LangChain parts:
QUERY_PARAMETERS = {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}
class Tool(ABC):
"""Base class for agent tools. The model never sees this docstring."""
name: str
def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)
if not cls.__dict__.get("__doc__"):
raise TypeError(f"{cls.__name__} needs a docstring. The model reads it to decide when to call the tool.")
@property
def description(self) -> str:
return inspect.cleandoc(type(self).__doc__)
def to_schema(self) -> dict:
return {"name": self.name, "description": self.description, "parameters": QUERY_PARAMETERS}
@abstractmethod
def run(self, query: str) -> str: ...
class ToolRunner:
def __init__(self, tools: list[Tool]):
self.tools_by_name = {tool.name: tool for tool in tools}
def schemas(self) -> list[dict]:
return [tool.to_schema() for tool in self.tools_by_name.values()]
def run(self, tool_name: str, query: str) -> str:
return self.tools_by_name[tool_name].run(query)
Why type(self).__doc__ and not inspect.getdoc? Python has two ways to read a class’s docstring, and they disagree when a subclass forgot one. Without the __init_subclass__ check:
class StatusPageTool(Tool): # forgot its docstring
name = "status_page"
StatusPageTool.__doc__ # None, every class gets its own __doc__, even an empty one
inspect.getdoc(StatusPageTool) # "Base class for agent tools...", borrowed from the parent
inspect.getdochides the mistake. It falls back to the parent’s docstring. Every tool that forgot one would tell the model it’s a “Base class for agent tools”. The model can’t tell those tools apart, and nothing raises an error.type(self)is the concrete tool.descriptionis written once, inTool. But at runtimeselfis the actual tool object, sotype(self)isStatusPageToolandtype(self).__doc__is that class’s own docstring.Noneis what makes the check possible. A missing docstring reads asNone, not as a borrowed one. So__init_subclass__catches it with aTypeErrorthe moment the class is defined, not in production when the model picks the wrong tool. How does a tool call actually run? The customer never calls a tool, and neither does the graph. The model asks for one, and the draft node runs it:
sequenceDiagram
participant Graph as StateGraph
participant Drafter as ReplyDrafter
participant Model as ChatModel + bind_tools
participant Runner as ToolRunner
participant Tool as IssueLookupTool
Graph->>Drafter: draft(state)
Drafter->>Model: invoke(messages)
Model-->>Drafter: AIMessage with tool_calls
Drafter->>Runner: run("issue_lookup", "ENG-142")
Runner->>Tool: run("ENG-142")
Tool-->>Runner: "ENG-142: fixed in release 4.2"
Runner-->>Drafter: result text
Drafter->>Model: invoke(messages + ToolMessage)
Model-->>Drafter: AIMessage with the reply
Drafter-->>Graph: {"reply": ...}
MAX_TOOL_ROUNDS = 3
TOOL_LIMIT_REPLY = "This one needs a human. The agent hit its tool call limit."
class ReplyDrafter:
def __init__(self, llm: BaseChatModel, tool_runner: ToolRunner):
self.llm = llm.bind_tools(tool_runner.schemas())
self.tool_runner = tool_runner
def draft(self, state: TicketState) -> dict:
prompt = DRAFT_PROMPT.format(docs="\n".join(state["docs"]), ticket=state["ticket"])
messages = [HumanMessage(prompt)]
for _ in range(MAX_TOOL_ROUNDS):
response = self.llm.invoke(messages)
messages.append(response)
if not response.tool_calls:
return {"reply": response.content}
for tool_call in response.tool_calls:
result = self.tool_runner.run(tool_call["name"], tool_call["args"]["query"])
messages.append(ToolMessage(result, tool_call_id=tool_call["id"]))
return {"reply": TOOL_LIMIT_REPLY}
bind_toolsruns once, in__init__. It returns a copy of the model that sends every schema fromToolRunner.schemas()(name, description andQUERY_PARAMETERS) along with eachinvoke.- The model answers in one of two ways. Either plain text, which is the reply, or an
AIMessagewhosetool_callslists what it wants run, like{"name": "issue_lookup", "args": {"query": "ENG-142"}, "id": "call_1"}. TheargsfollowQUERY_PARAMETERS, which is whyruntakes a singlequery. - The node runs each call through
ToolRunner. It looks the tool up byname, and the result goes back as aToolMessagewith the sametool_call_id, so the model knows which call it answers. - The loop repeats until the model replies with text.
MAX_TOOL_ROUNDSstops a model that keeps calling tools, and hands the ticket to a human.
LangGraph can also give tools their own node, with ToolNode and tools_condition from langgraph.prebuilt, which expect LangChain tool objects. The loop above keeps our own Tool classes and does the same job inside one node.
SOLID principles cheat sheet
| Principle | You’ll notice it when | What we changed in the agent |
|---|---|---|
| Single Responsibility | Unrelated changes keep landing in the same class | Split it into one class per node: classify, retrieve, draft, publish |
| Open/Closed | Every new feature adds another elif |
Gave each tool its own Tool subclass and docstring |
| Liskov Substitution | Callers start checking isinstance before trusting a subclass |
Made every tool return text, even when it finds nothing |
| Interface Segregation | A class implements methods just to raise NotImplementedError |
Split KnowledgeBase into Searchable and Indexable |
| Dependency Inversion | Business classes build their own OpenAI, Chroma or Slack clients | Passed BaseChatModel, Searchable and ReplyChannel in through __init__ |
None of these are rules for day one. They’re what you reach for when a change starts to hurt.
Want in early?
I'm building something totally free to make job search easier for all of us. Drop your email and I'll tell you when it ships, plus new articles.
You're in! I'll email you when the tool ships.
No spam. No AI slop. Just real stuff I build and write. Unsubscribe anytime.