My Week Wrestling with the LangChain Python SDK

Hey there, agntbox readers! Nina here, fresh off a particularly intense week of digging into the latest AI dev tools. Today, I want to talk about something that’s been buzzing in my Slack channels and Twitter feed: SDKs. Specifically, I’ve been wrestling with a particular beast that many of you are probably familiar with, or at least have heard whispers about: LangChain. But not just LangChain in general – no, we’re getting granular today. We’re going to dive into how the LangChain Python SDK is evolving, specifically with its new Expression Language (LCEL) and what that means for actually *building* complex AI applications in 2026.

If you’ve been in the AI space for more than a minute, you know LangChain. It burst onto the scene promising to make LLM application development easier, and for a while, it did. But it also grew… complex. A lot of us, myself included, started feeling like we were spending more time debugging LangChain’s internal representations than actually building our application logic. It was like trying to tie a shoelace with oven mitts on – you could do it, but it was clunky and frustrating. Then LCEL started appearing, and I initially approached it with a healthy dose of skepticism. Another abstraction? Another learning curve? My internal monologue was basically a series of eye-rolls.

But after spending the last few weeks really digging into it for a client project (a knowledge retrieval system for a legal tech startup, if you’re curious – very specific domain, very high stakes for accuracy), I’m ready to eat a bit of crow. LCEL, while still having its quirks, is genuinely starting to make good on the promise of building more maintainable, understandable, and performant LLM chains. It’s not perfect, but it’s a significant step forward from the wild west of nested agents and custom tools we were dealing with just a year ago.

Why LCEL? My Journey from Skeptic to Believer

Let’s rewind a bit. My initial experience with LangChain was a mixed bag. I loved the concept: stringing together LLMs, retrievers, tools, and agents to create intelligent workflows. My first few projects with it were exhilarating. “Look, Ma, I built a chatbot that can search the web!” But as the complexity grew, so did the headaches. Debugging became a nightmare. The chain definitions felt like an opaque blob of nested dictionaries and function calls. Changing one part of a chain often meant refactoring half of it. It was flexible, sure, but that flexibility often came at the cost of clarity and maintainability.

My client’s legal tech project was the crucible. We needed a system that could take a natural language query, search a private document database, synthesize answers, and cite sources. Accuracy was paramount, and the ability to easily audit and modify the flow was non-negotiable. My first attempt using older LangChain patterns was, frankly, a mess. The input/output parsing was brittle, the intermediate steps were hard to trace, and the whole thing felt like a house of cards. Any slight change in the prompt or retriever output would send the whole thing tumbling.

That’s when I decided to really commit to LCEL. The core idea behind LCEL is that chains are just sequences of components, and these components can be composed using simple operators like the pipe |. It makes the flow explicit and, crucially, composable. You define small, focused steps, and then you string them together. It felt like moving from writing assembly code to using a high-level programming language – a bit of an exaggeration, but you get the idea.

The Core Idea: Building Blocks and the Pipe Operator

At its heart, LCEL is about defining steps as small, independent functions or components and then piping their outputs into the next step’s input. This might sound obvious, but the way LangChain implements it makes a significant difference. Each component in an LCEL chain is expected to take an input and produce an output, much like a Unix pipe. This functional approach encourages modularity and makes debugging much, much easier.

Let’s look at a super simple example to illustrate the point. Imagine we want to take a user’s query, append a specific instruction, and then pass it to an LLM.

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI

# 1. Define the LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

# 2. Define the prompt template
prompt = ChatPromptTemplate.from_template("Tell me a fun fact about {topic}. Be concise.")

# 3. Define an output parser
output_parser = StrOutputParser()

# 4. Chain them together using LCEL
chain = prompt | llm | output_parser

# 5. Invoke the chain
result = chain.invoke({"topic": "sloths"})
print(result)

This looks deceptively simple, but the power comes from how each component clearly defines its input and output. The prompt takes a dictionary with topic, the llm takes a message (which the prompt transforms into), and the output_parser takes the LLM’s output. If something goes wrong, you can isolate which step failed. This was a monumental shift from the earlier days where a single “chain” object might encapsulate all these steps, making introspection difficult.

Input/Output Schemas and Type Safety (or Lack Thereof, but Getting Better)

One of my biggest frustrations with earlier LangChain implementations was the lack of clear input/output schemas. You often had to guess what a tool or a chain expected as input, and what it would return. This led to a lot of runtime errors and defensive coding to handle unexpected types or missing keys.

LCEL doesn’t magically give you full type safety (Python, right?), but it significantly improves clarity. Each component in an LCEL chain has defined input_schema and output_schema properties. While these are Pydantic models and require some manual effort to define for custom components, they provide invaluable documentation and allow for some basic validation. For the legal tech project, this was a lifesaver. We could define exactly what our retriever expected (a query string) and what it would return (a list of Document objects), and then ensure the subsequent synthesis step was prepared for that format.

from langchain_core.runnables import RunnableParallel, RunnablePassthrough
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.documents import Document
from typing import List

# ... (llm and output_parser defined as above)

# Dummy retriever for demonstration
def dummy_retriever(query: str) -> List[Document]:
 # In a real app, this would query a vector DB
 if "Nina" in query:
 return [Document(page_content="Nina Torres is a tech blogger.")]
 return [Document(page_content="No specific information found for your query.")]

# Create a Runnable from our function
retriever_runnable = RunnablePassthrough.assign(
 context=lambda x: dummy_retriever(x["query"])
)

# Now, let's create a prompt that expects context and query
context_prompt = ChatPromptTemplate.from_template(
 "Based on the following context, answer the question.\n\nContext: {context}\n\nQuestion: {query}"
)

# A more complex chain
full_chain = (
 RunnableParallel(
 query=RunnablePassthrough() # Passes the initial input as 'query'
 )
 | retriever_runnable
 | {
 "context": lambda x: "\n".join([doc.page_content for doc in x["context"]]),
 "query": lambda x: x["query"]
 }
 | context_prompt
 | llm
 | output_parser
)

print(full_chain.invoke("Who is Nina Torres?"))
print(full_chain.invoke("What is the capital of France?"))

Notice how we’re using RunnableParallel and RunnablePassthrough here. These are LCEL primitives that allow for more complex data flows. RunnableParallel lets you run multiple components in parallel and combine their outputs into a dictionary. RunnablePassthrough simply passes its input through, often used when you need to retain the original input or assign it to a specific key.

The dict mapping {"context": ..., "query": ...} before context_prompt is a powerful LCEL feature. It allows you to transform or select specific keys from the previous step’s output to match the expected input of the next step. This explicit mapping drastically reduces ambiguity compared to older chain patterns where inputs magically appeared from previous steps without clear declaration.

Streaming and Async by Default

This is where LCEL really shines for modern AI applications. Back in the day, if you wanted streaming output from an LLM, you had to jump through hoops. With LCEL, it’s baked in. Any LCEL chain automatically supports asynchronous execution (using .ainvoke()) and streaming (using .stream()). This isn’t just a nice-to-have; it’s essential for building responsive user interfaces and efficient backend services.

For my legal tech client, streaming was a critical requirement. Users expect immediate feedback, even if the full answer takes a few seconds to generate. With LCEL, I could easily switch from .invoke() to .stream() on my complex retrieval-augmented generation (RAG) chain without rewriting the core logic. This alone saved me days of development time and made the user experience so much smoother.

# Re-using the 'chain' from the first example
# chain = prompt | llm | output_parser

print("Streaming output:")
for chunk in chain.stream({"topic": "penguins"}):
 print(chunk, end="", flush=True)
print("\n--- End of Stream ---")

# Asynchronous invocation (requires an async context)
import asyncio

async def async_run():
 async_result = await chain.ainvoke({"topic": "dinosaurs"})
 print(f"\nAsync result: {async_result}")

# To run this in a script:
# asyncio.run(async_run())

The ability to easily switch between synchronous, asynchronous, and streaming execution without altering the chain definition is, in my opinion, one of LCEL’s strongest arguments. It means your core business logic remains consistent, and you adapt the execution method based on your application’s needs.

Where LCEL Still Feels a Bit Green (and My Honest Gripes)

Okay, so I’ve sung LCEL’s praises quite a bit. But it’s not all sunshine and rainbows. There are still areas where I find myself scratching my head or wishing for a more polished experience.

1. Debugging Complex Chains: While individual steps are easier to debug, visualizing and debugging the flow of data through a very complex LCEL chain (especially with nested RunnableParallel or custom Runnable implementations) can still be challenging. LangSmith helps a lot here, providing visual traces, but without it, it’s still a bit of a manual process of adding print statements. I wish for more built-in introspection tools directly within the SDK.
2. Error Handling: Explicit error handling within chains can sometimes feel a bit clunky. While you can wrap individual runnables in try...except blocks, propagating specific errors up the chain or implementing fallback strategies isn’t always as straightforward as I’d like.
3. Learning Curve for New Primitives: While the pipe operator is intuitive, understanding when to use RunnablePassthrough, RunnableParallel, RunnableLambda, or custom Runnable classes takes time. The documentation is good, but there’s a certain “LangChain way” of thinking you need to adopt. It’s not a dealbreaker, but it’s definitely a hurdle for newcomers.
4. Custom Runnable Boilerplate: If you’re building a highly custom step that doesn’t fit into existing components, creating your own Runnable subclass can involve a fair bit of boilerplate, especially if you want proper input_schema/output_schema definitions and async support. I often find myself wanting a simpler decorator or factory function for common patterns.

These aren’t fundamental flaws, but rather areas for improvement as the SDK matures. The LangChain team is incredibly active, and I’ve seen these aspects improve rapidly over the past year.

Actionable Takeaways for Your Next AI Project

So, you’re convinced (or at least curious) about LCEL. How do you actually put this into practice today?

1. Start Small, Think Modular: Don’t try to rewrite your entire existing LangChain application in LCEL overnight. Pick a small, self-contained part of your application (e.g., a specific prompt template and LLM call, or a simple retrieval step) and convert it to an LCEL chain. Focus on defining clear inputs and outputs for that small chain.
2. Embrace the Pipe: Get comfortable with the | operator. It’s the cornerstone of LCEL. Think of your AI application as a series of transformations, each feeding into the next. This mental model will guide your chain construction.
3. Leverage RunnableParallel for Complex Inputs: If you need to combine outputs from multiple sources (e.g., a user query and retrieved context) to feed into a single prompt, RunnableParallel is your friend. It allows you to build up a dictionary of inputs for the next step.
4. Prioritize Streaming: Even if you don’t need streaming for your current application, design your chains with streaming in mind. It’s almost always easier to add streaming support from the start than to retrofit it later. Plus, it makes for a snappier user experience.
5. Use LangSmith (Seriously): I know, another tool, another subscription. But for debugging and understanding complex LCEL chains, LangSmith is invaluable. The visual traces alone are worth the investment, especially during development. It helps you see where data is going wrong and which steps are taking the longest.
6. Define Your Schemas (Even for Custom Code): If you’re writing custom Python functions and wrapping them in RunnableLambda or creating custom Runnable classes, take the extra time to define input_schema and output_schema. It’s documentation that pays dividends later, both for you and anyone else working on the code.

The LangChain Python SDK, particularly with the advancements in LCEL, is moving in a direction that genuinely facilitates building robust and understandable AI applications. It’s not a magic bullet, and there’s still a learning curve, but the benefits in terms of modularity, debugging, and performance are becoming increasingly clear. If you’ve been on the fence, or even if you’ve had a bad experience with older LangChain versions, I encourage you to revisit LCEL. It might just change how you approach your next AI build, just like it did for me.

That’s all for today, folks! Happy chaining, and I’ll catch you next time on agntbox.com. Nina out.

🕒 Published: May 11, 2026