The problem with plain text responses

Let’s see what happens when we just ask a model a normal question.

groq_model_name = os.getenv("GROQ_MODEL")
groq_model = init_chat_model(
    os.getenv("GROQ_MODEL"),
    model_provider="groq"
)
unstructured_response = groq_model.invoke("Give me details about the movie 'Jersey' acted by Nani.")
print(unstructured_response.content)

You’ll get back a paragraph of text describing the movie, its plot, cast, release details, all mixed together in prose. Sounds fine to read, but try extracting just the release year out of that paragraph programmatically. You’d be writing fragile regex or string parsing, and it would break the moment the model phrases things slightly differently next time

Not great, right? This is exactly the kind of unpredictability that breaks production systems. Before moving forward,

Subscribe now

The fix: give the model a schema

Instead of hoping the model’s text happens to contain what you need, you tell it exactly what shape of data to return. LangChain calls this Structured Output, and the most common way to do it is with pydantic.

Step 1: Define your schema with Pydantic

from pydantic import BaseModel, Field

class Movie(BaseModel):
    title: str = Field(..., description="The title of the movie")
    release_year: int = Field(..., description="The year the movie was released")
    genre: str = Field(..., description="The genre of the movie")

Notice the Field(..., description="...") part. Just like a tool’s docstring tells the model when to use it, the description here tells the model exactly what each field means. Don’t skip these, they genuinely affect how accurate the output is.

Step 2: Ask the model to follow that schema

structured_response = groq_model.with_structured_output(Movie).invoke(
    "Give me details about the movie 'Jersey' acted by Nani."
)
structured_response

And now, instead of a paragraph, you get back a clean Movie object with exactly three fields, title, release_year, and genre. Nothing extra, nothing missing. That’s the whole point, predictable output that your code can rely on every single time.

What do you think happens if you need both the raw AI message and the structured data? Turns out, there’s an option for that too.

structured_response_with_ai_message = groq_model.with_structured_output(
    Movie, include_raw=True
).invoke("Give me details about the movie 'Jersey' acted by Nani.")

Setting include_raw=True gives you both, the full AIMessage (with metadata, token usage, all of it) and the parsed structured object. Handy when you want the clean data but also want to log or debug the raw response.

Nested structured output

Here’s where it gets genuinely useful. Schemas aren’t limited to flat fields, you can nest them, just like you’d nest objects in any normal data model.

class Player(BaseModel):
    name: str = Field(..., description="The name of the player")
    role: str = Field(..., description="The role of the player in the team. Ex: Batsman, Bowler, All-rounder, Wicket-keeper, Captain")

class Team(BaseModel):
    name: str = Field(..., description="The name of the team")
    players: list[Player] = Field(..., description="List of players in the team")

structured_response_nested = groq_model.with_structured_output(Team).invoke(
    "Give me best playing 11 of the Indian cricket team in batting order."
)
for player in structured_response_nested.players:
    print(f"{player.name} - {player.role}")

Look at what’s happening here. Team contains a list of Player objects, and the model correctly fills in an entire list, each with its own name and role, all nested inside one clean response. This is genuinely powerful for anything like generating structured reports, populating UI components, or feeding data into another system, all without writing a single parser yourself.

Pydantic isn’t the only option

Pydantic gives you the richest feature set, validation, descriptions, and nested structures, but it’s not the only way to define a schema. Here’s how the three options compare:

The good news? Once you’ve defined the schema, using it is basically the same regardless of which approach you picked. For TypedDict and Dataclass, you plug the schema into create_agent() using response_format instead of calling .with_structured_output() directly:

agent = create_agent(
    model=groq_model,
    response_format=Movie   # Movie schema, defined using any of the three approaches
)

So really, the only thing that changes across all three approaches is how you write the schema itself. Everything downstream stays the same.

Recap

• Plain text responses are unpredictable and fragile to parse, structured output fixes that.

• Define a schema using Pydantic’s BaseModel and Field, then call model.with_structured_output(<Schema>).

• Use include_raw=True if you want both the full AI message and the parsed structured data.

• Schemas can be nested, letting the model return complex, structured objects like a full team of players.

• Pydantic, TypedDict, and Dataclass all work as schema options, only the schema definition changes, everything else stays consistent.

Not bad at all. You’ve now gone from a single invoke() call all the way to building agents that use tools, understand structured conversations, and return clean, predictable data.

Let’s break it down.

What is a message, really?

A message is the basic unit of context that a model works with. Every single message, whether it’s from a human, the AI, or a system instruction, is built from three parts:

Here’s the good part. LangChain gives you one standard message format that works the same way regardless of which provider you’re using underneath. So whether it’s OpenAI, Gemini, or Groq answering, your code dealing with messages doesn’t have to change.

You’ve actually already seen this without realizing it. Every time you call .invoke(), the response you get back isn’t just plain text, it’s an actual message object.

groq_model.invoke("Hello, how are you?")   # Returns an AIMessage

That response has a type, ai, because the model generated it. Makes sense, right?

Subscribe now

The four message types

LangChain gives you four message types, all available from langchain.messages.

Notice how each one has a clear job. You wouldn’t put user input inside a SystemMessage, and you wouldn’t expect the model’s answer to show up as a HumanMessage. Keeping these separate is exactly what lets the model understand who said what in a conversation.

Text prompts vs message prompts

Ok, here’s where it gets practical. There are two ways to send input to a model, and beginners often don’t realize there’s a difference.

Option 1: Text prompts

This is what we’ve been doing so far, just sending a plain string.

groq_model.invoke("Hello, how are you?")

Use this when:

• You want to send a single, standalone message

• You don’t care about keeping any conversation history

• You just want a quick, one off response

Simple and fast. But it has no memory of anything before it.

Option 2: Message prompts

This is where you send a list of messages instead of a single string, giving the model actual context to work with.

from langchain.messages import SystemMessage, HumanMessage

conversation = [
    SystemMessage("You are a helpful assistant. Don't be rude to the user."),
    HumanMessage("Hello!")
]

groq_model.invoke(conversation)

Here’s what actually comes back when you run this:

AIMessage(
    content='Hello! How can I help you today?',
    additional_kwargs={'reasoning_content': 'The user says "Hello!" The assistant should respond politely.'},
    response_metadata={
        'token_usage': {'completion_tokens': 31, 'prompt_tokens': 89, 'total_tokens': 120, ...},
        'model_name': 'openai/gpt-oss-20b',
        'finish_reason': 'stop', ...
    },
    id='lc_run--019fb61b-cafa-7750-bbe0-82500e8f8576-0',
    tool_calls=[], invalid_tool_calls=[],
    usage_metadata={'input_tokens': 89, 'output_tokens': 31, 'total_tokens': 120, ...}
)

Look at all that detail packed into one response. You get the actual content, but also response_metadata (token counts, which model generated it, why it stopped), and usage_metadata (a clean breakdown of input versus output tokens). This is exactly the kind of information you’d want if you’re tracking cost or debugging behavior in production.

You’ll also notice reasoning_content in there, which basically shows how the model interpreted the system prompt before responding. Pretty useful for understanding why the model answered the way it did.

Use message prompts when:

• You need to maintain a proper conversation with history

• You want to set clear rules for how the model should behave

• You’re building anything beyond a single throwaway question

Why your system prompt quality actually matters

Here’s a small but important detail. The example above showed reasoning_content referencing the system prompt directly. That’s not a coincidence.

The more clearly you define your SystemMessage, the better and more consistent the model performs.

Vague system promptClear system prompt“You are an assistant.”“You are a customer support assistant for an e-commerce app. Be concise, polite, and never make up order details you don’t have.”Model behavior is inconsistent across runsModel stays on-brand and predictable

Think of the system prompt as the model’s job description. A vague job description gets vague results. A specific one gets specific, reliable behavior. This is genuinely one of the highest leverage things you can improve in any LLM application, and it costs you nothing extra to write it properly.

Recap

• A message has three parts, role, content, and metadata, and LangChain standardizes this across every provider.

• There are four message types, SystemMessage, HumanMessage, AIMessage, and ToolMessage, each with a clear, distinct job.

• Text prompts (plain strings) work for quick, one off questions with no memory needed.

• Message prompts (a list of message objects) are what you use for real conversations with context and history.

• A clear, specific SystemMessage genuinely improves how consistent and reliable your model’s behavior is.

So basically, once you start thinking in messages instead of plain strings, your agents start feeling a lot more like real conversations instead of disconnected one liners.

Up next in the series: we’ll wrap up this series with Structured Output, how to make a model return exactly the data shape you want, instead of a wall of unpredictable text. Catch it here!

In this post, we’re going deep into Tools. What they are, how to create them properly, and two different ways to actually use them. Let’s get into it.

So, what exactly is a tool?

Think of a tool as a regular Python function that you hand over to the model, and say “hey, use this whenever you need it.” The model itself doesn’t run your Python code. It just decides when a tool is needed, and with what input, then your code runs it and hands the result back.

Tools can do pretty much anything you can code:

• Fetch live data from an API (weather, stock prices, news)

• Query a database

• Do a calculation the model can’t reliably do on its own

• Even call another LLM

Simple enough, right? Now let’s actually build one. But, make sure you

Subscribe now

Creating a tool

Here’s the entire recipe. You write a normal Python function, and slap a @tool decorator on top of it.

from langchain.tools import tool

@tool
def get_current_weather(location: str) -> str:
    """
    Get the current weather for a given location.
    """
    return f"The current weather in {location} is 25°C and sunny."

That’s it. That @tool decorator is doing the heavy lifting here, it converts your plain function into something the model can understand and call.

Now, remember what we said in Post 1 about docstrings? Same rule applies here, and honestly it matters even more now. The docstring is not a comment for your teammates to read later. It is literally what the model reads to decide “should I use this tool right now, or not?”

So don’t treat the docstring as an afterthought. Write it like you’re explaining the tool to someone who has never seen your code.

Let’s create a few more tools

One tool is boring. Let’s make three, so the model actually has to think about which one fits the question.

@tool
def get_current_weather_tool(location: str) -> str:
    """
    Get the current weather in a given location
    """
    return f"The current weather in {location} is sunny with a temperature of 25°C."

@tool
def get_stock_price_tool(stock_symbol: str) -> str:
    """
    Get the current stock price of a given stock symbol
    """
    return f"The current stock price of {stock_symbol} is $150."

@tool
def get_news_tool(topic: str) -> str:
    """
    Get the latest news on a given topic
    """
    return f"The latest news on {topic} is that the stock market is up by 2% today."

Notice each one does something completely different, weather, stock prices, news. That’s on purpose. In a bit, we’ll ask the model questions and watch it pick the correct tool on its own.

Now, the interesting part: binding tools directly to a model

In Post 1, we passed tools into create_agent(), and the agent handled everything behind the scenes. But what if you don’t want a full agent? What if you just want a plain chat model that can call tools when needed?

That’s where bind_tools() comes in.

import os
from dotenv import load_dotenv
from langchain.chat_models import init_chat_model

load_dotenv(override=True)

os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["GOOGLE_API_KEY"] = os.getenv("GOOGLE_API_KEY")
os.environ["GROQ_API_KEY"] = os.getenv("GROQ_API_KEY")

google_model_name = os.getenv("GOOGLE_MODEL")
google_model = init_chat_model(
    google_model_name,
    model_provider="google_genai"
)

google_model_with_tools = google_model.bind_tools(
    [get_current_weather_tool, get_stock_price_tool, get_news_tool]
)

What’s happening here? We took a plain chat model, google_model, and called .bind_tools() on it, passing in our list of tools. Now this new object, google_model_with_tools, knows those three tools exist and can decide to use them whenever it needs to.

So basically, this is the “lighter” way of giving a model tool access, no full agent setup required.

Ok, now what? Let’s actually test it

Here’s where it gets fun. We’ll ask three completely different questions and watch what the model decides to do each time.

tool_response = google_model_with_tools.invoke("What is the current weather in New York?")
print(tool_response.type)  # ai

tool_calls = tool_response.tool_calls

if tool_calls:
    for tool_call in tool_calls:
        print(f"Tool: {tool_call['name']}")
        print(f"Args: {tool_call['args']}")
else:
    print("No tool calls were made for this response.")

Run this, and you’ll see the model correctly picks get_current_weather_tool, with location set to New York. It didn’t guess. It matched the question against the docstrings of all three tools and picked the one that actually fits.

Let’s try another one.

tool_response = google_model_with_tools.invoke("What is the current stock price of PYPL?")

tool_calls = tool_response.tool_calls

if tool_calls:
    for tool_call in tool_calls:
        print(f"Tool: {tool_call['name']}")
        print(f"Args: {tool_call['args']}")
else:
    print("No tool calls were made for this response.")

This time it picks get_stock_price_tool, with stock_symbol set to PYPL. Notice how it also figured out the right argument name and value from a plain English question. That’s not magic, it’s the model reading your function’s type hints and docstring together.

And here’s a fun one to try.

tool_response = google_model_with_tools.invoke("Who won the IPL-2025?")

tool_calls = tool_response.tool_calls

if tool_calls:
    for tool_call in tool_calls:
        print(f"Tool: {tool_call['name']}")
        print(f"Args: {tool_call['args']}")
else:
    print("No tool calls were made for this response.")

What do you think happens here? We don’t have a tool for IPL match results, only weather, stock, and news. So depending on the model, it might either call get_news_tool with topic set to something like “IPL 2025” since that is the closest fit, or it might make no tool call at all and just answer from its own memory. Either way, this shows you something important: the model only picks from what you gave it. If none of your tools genuinely fit, don’t expect a miracle.

Two ways to use tools, side by side

Let’s put both approaches next to each other, since it’s easy to mix them up as a beginner.

Neither one is “better.” It really depends on how much control you want versus how much you want LangChain to handle for you.

Notice the difference in that last box. With bind_tools(), the model just tells you which tool it wants to call and with what arguments, it does not actually run the tool for you. You are responsible for executing the function yourself and feeding the result back if needed. With create_agent(), all of that is handled automatically behind the scenes.

One thing worth repeating

We’ve said this before, but it deserves repeating here: the model is not reading your code. It is reading your docstring, your function name, your parameter names, and your type hints. That’s the entire “instruction manual” it has.

So a quick checklist before you ship any tool:

• Does the function name clearly describe what it does?

• Does the docstring explain exactly when to use it?

• Are the parameter names and types clear (location: str, not x: str)?

• Would a stranger reading only the docstring know when to call this?

If you can say yes to all four, your tool is production ready.

Recap

• A tool is just a Python function decorated with @tool, that a model can choose to call.

• The docstring is what tells the model what the tool does and when to use it, so write it carefully.

• You can bind tools directly to a model using bind_tools(), without needing a full agent.

• The model reads your question, compares it against every tool’s docstring, and picks the best match, or none at all if nothing fits.

• create_agent() and bind_tools() both work, just at different levels of control.

Not bad, right? You now know two solid ways to give your model real world abilities.

Up next in the series: we’ll look at Messages, the actual format models use to understand conversations, and why getting this right matters more than most beginners realize. Catch it here!

Turns out, there’s more than one way. In this post, we’ll cover how to load models from different providers using one single function, and then we’ll look at three different ways to call a model, invoke(), stream(), and batch(). Each one fits a different situation, and picking the wrong one can actually hurt your app’s user experience. Let’s get into it.

Loading a model, the LangChain way

Here’s the thing. OpenAI, Google Gemini, and Groq all have their own SDKs, their own quirks, their own way of setting things up. If you were doing this manually, you’d be writing separate code for each one.

LangChain gives you a single function, init_chat_model(), that works across all of them. You just tell it which model and which provider, and it handles the rest.

import os
from dotenv import load_dotenv

load_dotenv(override=True)

os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["GOOGLE_API_KEY"] = os.getenv("GOOGLE_API_KEY")
os.environ["GROQ_API_KEY"] = os.getenv("GROQ_API_KEY")

from langchain.chat_models import init_chat_model

Loading OpenAI

open_ai_model_name = os.getenv("OPENAI_MODEL")
openai_model = init_chat_model(
    os.getenv("OPENAI_MODEL"),
    model_provider="openai"
)
output1 = openai_model.invoke("Hello, how are you?")
print(f"Output from {open_ai_model_name}: \n{output1.content}")

Loading Google Gemini

%pip install -U langchain-google-genai

google_model_name = os.getenv("GOOGLE_MODEL")
google_model = init_chat_model(
    os.getenv("GOOGLE_MODEL"),
    model_provider="google_genai"
)
output2 = google_model.invoke("Hello, how are you?")
print(f"Output from {google_model_name}: \n{output2.content}")

Loading Groq

groq_model_name = os.getenv("GROQ_MODEL")
groq_model = init_chat_model(
    os.getenv("GROQ_MODEL"),
    model_provider="groq"
)
output3 = groq_model.invoke("Hello, how are you?")
print(f"Output from {groq_model_name}: \n{output3.content}")

Notice something? All three blocks look almost identical. Only the model name and model_provider change. That’s the whole point of init_chat_model(), one consistent way to load any provider, so switching providers later is basically a one line change.

So basically, once you learn this pattern once, you know it for every provider LangChain supports. Nice, right?

Subscribe now

Now, how do you actually talk to the model?

Once your model is loaded, you have three different methods to get a response out of it: invoke(), stream(), and batch(). Let’s go through each one, because picking the right one matters more than you’d think.

1. invoke(), the straightforward one

This is what we’ve been using so far. You send a question, and you wait until the entire response is fully generated, then you get it all at once.

google_model_name = os.getenv("GOOGLE_MODEL")
google_model = init_chat_model(
    os.getenv("GOOGLE_MODEL"),
    model_provider="google_genai"
)
output = google_model.invoke("Hello, how are you?")
print(f"Output from {google_model_name}: \n{output.content}")

Simple, but here’s the catch. If the response is long, the user just stares at a blank screen until it’s fully ready. Not exactly a great experience for something like a chatbot.

2. stream(), the “type as you go” one

Ever noticed how ChatGPT’s answer appears word by word instead of popping up all at once? That’s streaming. Most models support this, and LangChain makes it easy to tap into.

for chunk in google_model.stream("How to get a call from Google/Microsoft HR? Please guide under 5 lines."):
    print(chunk.text, end="", flush=True)
# end - Append this at the end of each chunk
# flush - Flush the output buffer to ensure that the text is printed immediately

What’s happening here? stream() returns an iterator, not a single final answer. Every time a new chunk of text is generated, it gets yielded immediately, and your loop prints it right away. The end="" keeps everything on the same line instead of adding a new line after every chunk, and flush=True makes sure Python prints it instantly instead of holding it in a buffer.

This is what you’d want for any user facing chat interface. Feels faster, even if the total time is the same.

3. batch(), the “many questions at once” one

What if you have a whole list of questions and you want answers to all of them, without writing a loop and calling invoke() five separate times? That’s exactly what batch() is for.

responses = google_model.batch([
    "Which team won IPL 2026?",
    "Which is the best cricket stadium in India?",
    "How Sanju Samson performed in 2026 World Cup?"
], config = {
    "max_concurrency": 2    # Only 2 requests will be sent to the model at a time. The rest will be queued and sent when one of the previous requests is completed.
})

for response in responses:
    print(response.content)

You pass in a list of prompts, and you get back a list of responses, in the same order. The max_concurrency setting controls how many requests go out at the same time. Set it to 2, and only 2 questions are being processed simultaneously, the rest wait in a queue until a slot frees up.

Why would you even limit concurrency? Because most providers have rate limits. Fire off fifty requests at once, and you might just get blocked. max_concurrency lets you control the pace.

Picking the right one

Here’s a quick table to keep handy:

There’s no universally “best” one here. It genuinely depends on what you’re building. A backend script that summarizes a document overnight? invoke() is fine. A live chatbot your users are staring at? stream() will feel a lot better. Running the same prompt against a hundred different inputs? batch() saves you a ton of manual looping.

Recap

• init_chat_model() gives you one consistent way to load OpenAI, Gemini, Groq, or any other supported provider.

• invoke() waits for the full response and hands it back in one go.

• stream() returns the response piece by piece, as it’s being generated, great for chat style interfaces.

• batch() takes a list of prompts and returns a list of responses, with max_concurrency controlling how many run at once.

Ok, now what? You know how to load a model and talk to it in three different ways. Time to make it smarter.

Up next in the series: we’re going to look at Messages, the actual format models use to understand a conversation, and why the words you choose in a system prompt matter more than most beginners realize. Catch it here!

Alright, let’s start from zero. No prior LangChain knowledge needed here. I’m going to walk you through this the same way I’d explain it to a friend who just asked me, “hey, what even is LangChain, and why does everyone keep talking about agents?”

By the end of this post, you will have built your very first working AI agent. Let’s go.

So, what problem does LangChain actually solve?

Here’s the thing. Large Language Models like GPT, Gemini, or Llama are genuinely powerful. But the moment you try to use them inside a real application, things get messy fast. You end up having to handle:

• Connecting to different providers (OpenAI, Google, Groq, and so on)

• Formatting conversation history so the model doesn’t lose context

• Letting the model call external tools like APIs or databases

• Parsing whatever the model sends back into something your app can actually use

Now imagine writing all of that from scratch, for every single provider you want to support. Sounds exhausting, right? That is exactly the problem LangChain was built to solve.

LangChain is basically a framework that hands you ready-made tools and abstractions so you don’t have to build all this plumbing yourself.

Think of it like this:

Without LangChainWith LangChainWrite custom code for each LLM providerOne consistent interface works across all providersManually manage conversation historyMessage objects handle this for youManually parse tool callsTools are handled automaticallyReinvent agent logic every timecreate_agent() gives you a working agent in a few lines

Makes sense so far? Good. Let’s get our hands dirty.

Step one: setting up your project

Before we write a single line of “real” code, let’s set up a clean environment. Trust me on this, it will save you headaches later when your projects start piling up and their dependencies start clashing with each other.

We’re going to use uv, a fast Python package and virtual environment manager.

# Install uv if you don't have it already
brew install uv

Once that’s installed, go to your project folder and run:

# Initialize the project
uv init

# Create a virtual environment
uv venv

# Activate the virtual environment (macOS)
source .venv/bin/activate

# Install the latest version of all dependencies listed in requirements.txt
uv add -r requirements.txt

# Install one specific dependency
uv add ipykernel

# Deactivate the virtual environment when done
deactivate

Now you might be wondering, what actually is a virtual environment? In simple terms, it’s just an isolated folder that holds all the packages your project needs, kept separate from every other project on your machine. That .venv folder you just created? It’s basically the same idea as node_modules in Node.js or target in Java. It just quietly stores your dependencies without mixing them into the rest of your system.

Ok, environment is ready. Now what?

Why do LLMs even need “agents”?

Let’s start with the simplest possible Generative AI setup. You give it an input, the LLM processes it, you get an output. That’s it.

This works great when the task only needs the model’s existing knowledge. But here’s the catch. LLMs have what’s called a knowledge cutoff. They simply don’t know about anything that happened after their training data ends, and they have zero access to live, real time information.

So watch what happens here:

See the problem? The model just shrugs. It has no idea what happened in today’s match because that information didn’t exist when it was trained.

So, how do we fix this? Simple. We let the LLM reach outside itself. It calls an API, queries a database, uses some other tool, whatever gets the job done, and brings that fresh information back into the conversation.

And that, right there, is basically what an Agent is. An agent is an LLM that can decide, on its own, to reach for an external tool when it needs to.

It’s not just answering from memory anymore. It’s making small decisions like:

• Which tool should I use here?

• What information am I still missing?

• How do I combine what the tool gave me into a proper final answer?

Pretty neat, right? Before moving forward,

Subscribe now

Quick history lesson: agents before LangChain

Before frameworks like LangChain came along, people used a pattern called ReAct (short for Reason and Act) to build this “think, use a tool, look at the result, repeat” loop by hand. It worked, sure, but it meant a lot of manual wiring every single time.

LangChain took that whole pattern and squeezed it into one function: create_agent(). That’s it. Let’s actually build one.

Building your first agent

I’m going to break this down into small steps so nothing feels overwhelming.

Step 1: Check your setup

import langchain, sys

print("LangChain:", langchain.__version__)
print("Python:", sys.version)
print("Executable:", sys.executable)
print("LangChain path:", langchain.__file__)

This just confirms LangChain is installed properly and shows you which Python environment you’re actually running in. Nothing fancy, just a sanity check.

Step 2: Load your API keys

Every LLM provider needs an API key so it knows the request is coming from you. Store these in a .env file and load them like this:

import os
from dotenv import load_dotenv

load_dotenv(override=True)

os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["GOOGLE_API_KEY"] = os.getenv("GOOGLE_API_KEY")
os.environ["GROQ_API_KEY"] = os.getenv("GROQ_API_KEY")
os.environ["MODEL"] = os.getenv("MODEL")

One important thing before we move on. Never, ever hardcode your API keys directly into your code. Keep them in a .env file, and make sure that file is added to .gitignore so it never accidentally ends up on GitHub.

Step 3: Create an agent with no tools

Let’s start simple.

from langchain.agents import create_agent
from langchain_groq import ChatGroq

model = ChatGroq(
    model="openai/gpt-oss-20b",
    api_key=os.environ["GROQ_API_KEY"]
)

agent = create_agent(
    model=model,
    tools=[],   # No tools provided
    system_prompt="You are a helpful assistant."
)

At this point, our agent is really just a chatbot wearing an “agent” costume. It has no way of reaching outside its own knowledge. Let’s fix that.

Step 4: Give the agent a tool

def get_weather(location):
    """
    A simple tool to get the weather information for a given location.
    """
    print(f">>> TOOL CALLED for {location}")
    return f"The weather in {location} is sunny with a temperature of 25°C."

agent = create_agent(
    model=model,
    tools=[get_weather],   # Introduce a tool to get weather information
    system_prompt="You are a helpful assistant."
)

Step 5: Run the agent and see what happens

# Query that needs the tool
message_1 = "What is the current condition in Chennai?"
output_1 = agent.invoke({"messages": [{"role": "user", "content": message_1}]})["messages"][-1].content
print(f"Me: {message_1}\nAgent: {output_1}")

# Query that does NOT need the tool
message_2 = "What is the capital of France?"
output_2 = agent.invoke({"messages": message_2})["messages"][-1].content
print(f"Me: {message_2}\nAgent: {output_2}")

Here’s what’s interesting. For the first question, the agent actually calls get_weather, because answering it properly needs live, real world data. For the second question, it already knows the answer from training, so it just skips the tool entirely and answers directly.

So basically, the agent is making a judgment call every single time. Cool, right?

Ok but how does the model know which tool to call?

This is probably the most common question beginners ask me at this point. And the answer is refreshingly simple: the docstring.

def get_weather(location):
    """
    A simple tool to get the weather information for a given location.
    """

That little bit of text inside the triple quotes isn’t just there for humans reading your code. The model actually reads it to figure out what the tool does and when it should be used. So writing a clear, accurate docstring isn’t optional, it directly affects how well your agent performs.

Docstring qualityResultMissing or vagueModel may not call the tool at all, or calls the wrong oneClear and specificModel reliably picks the right tool at the right moment

What do you think happens if two tools have similar, vague docstrings? Yep, the model gets confused about which one to pick. So take your time writing them well.

You’re not limited to just one tool

An agent can juggle multiple tools at once. You just pass a list, and the model figures out which one fits the situation:

agent = create_agent(
    model=model,
    tools=[get_weather, get_stock_price, get_latest_news],
    system_prompt="You are a helpful assistant."
)

The model looks at the user’s question, compares it against each tool’s docstring, and picks whichever one actually fits, or none at all, if the question doesn’t need a tool in the first place.

Let’s recap what we covered

• LangChain removes the repetitive plumbing of working with LLMs directly.

• Use uv to create a clean, isolated environment for your project.

• LLMs have a knowledge cutoff, and agents solve this by calling external tools for live information.

• create_agent() builds a working agent in just a few lines of code.

• The tool’s DocString is what actually tells the model when and how to use it.

Not bad for a first post, right? You now technically know how to build a working AI agent.

Up next in the series: we’re going to look at the three different ways to actually talk to a model, invoke(), stream(), and batch(), and figure out exactly when you’d reach for each one. Catch it here!

Understanding join strategies provides deep insight into database performance, execution planning, and system design trade-offs.

From Client Query to Execution Engine

When a client application submits a SQL query, it travels through multiple internal stages before reaching execution. The database first parses the SQL and constructs a logical query plan that represents the relational operations required to produce the result. This plan is then fed into the query optimizer, which explores multiple physical execution strategies and selects the lowest-cost plan based on statistics, available memory, indexes, and estimated I/O.

Once a physical plan is chosen, the execution engine carries out the operations by fetching data pages from disk or memory buffers, applying filters, performing joins, and producing the result stream. Join strategies are selected at this optimization stage and directly influence execution latency, memory usage, and system throughput.

1. Nested Loop Join

The nested loop join is the most straightforward join strategy. It works by scanning one table and, for each row, scanning the second table to find matching rows.

Conceptually, the algorithm can be represented as:

for (Row a : tableA) {
    for (Row b : tableB) {
        if (a.key.equals(b.key)) {
            emit(a, b);
        }
    }
}

This approach has a time complexity of O(N × M), making it impractical for large datasets. However, when one of the tables is very small, or when an index exists on the join key of the larger table, nested loop joins become highly efficient.

With indexing, the inner scan becomes an index lookup:

for (Row a : tableA) {
    Row b = indexLookup(tableB, a.key);
    if (b != null) {
        emit(a, b);
    }
}

This reduces complexity to O(N log M), often outperforming more complex strategies when selective indexes exist. Nested loop joins are therefore common in OLTP systems, where point lookups dominate.

• Very fast when:

  • One table is tiny

• Disaster when:

  • Both tables are large

2. Hash Join

Hash join is optimized for equality-based joins on large datasets. The algorithm builds a hash table from the smaller input and then probes it using rows from the larger input.

In the build phase, rows from the smaller table are hashed into memory:

Map<Key, List<Row>> hash = new HashMap<>();
for (Row c : customers) {
    hash.computeIfAbsent(c.id, k -> new ArrayList<>()).add(c);
}

In the probe phase, the larger table is scanned, and each row is matched using the hash map:

for (Row o : orders) {
    List<Row> matches = hash.get(o.customerId);
    if (matches != null) {
        for (Row c : matches) {
            emit(o, c);
        }
    }
}

This strategy runs in O(N + M) time and requires memory proportional to the size of the smaller table. If the hash table does not fit into memory, modern databases use partitioned or hybrid hash joins that spill to disk.

Hash joins dominate analytical workloads and batch processing systems, where full table scans are common and sufficient memory is available.

3. Merge Join

Merge join relies on both inputs being sorted on the join key. Once sorted, the two streams are traversed sequentially, similar to the merge step of merge sort.

sort(tableA);
sort(tableB);

int i = 0, j = 0;

while (i < tableA.size() && j < tableB.size()) {
    if (tableA.get(i).key == tableB.get(j).key) {
        emit(tableA.get(i), tableB.get(j));
        i++; j++;
    } else if (tableA.get(i).key < tableB.get(j).key) {
        i++;
    } else {
        j++;
    }
}

If the inputs are already sorted via index scans, merge join becomes extremely efficient, requiring only sequential I/O. Otherwise, the sorting cost dominates, leading to O(N log N + M log M) complexity.

Merge joins excel in range queries, time-series workloads, and analytical pipelines where sorted access patterns are common.

• Perfect for:

  • Sorted datasets

• Bottleneck:

  • Sorting cost

How the Query Optimizer Selects a Join Strategy

The optimizer evaluates multiple candidate plans by estimating their total cost, which includes disk I/O, CPU usage, memory consumption, and intermediate data size. Using table statistics, histograms, and cardinality estimates, it determines which strategy will minimize execution time and resource consumption.

If a small dimension table joins a massive fact table, the optimizer favors hash joins. When selective indexes exist, nested loop joins dominate. When sorted access paths are available, merge joins are preferred.

This decision is dynamic and recalculated for each query, ensuring that execution adapts to evolving data sizes and distributions.

End-to-End Example

A Java application executing a simple join:

String sql = """
SELECT o.id, c.name
FROM orders o
JOIN customers c ON o.customer_id = c.id
""";

PreparedStatement ps = conn.prepareStatement(sql);
ResultSet rs = ps.executeQuery();

Behind this simple interface, the database parses the query, optimizes the execution plan, selects a join strategy, fetches pages from disk into memory buffers, performs the join using one of the physical algorithms, and streams the result back to the client. The choice of join strategy largely determines whether this operation completes in milliseconds or seconds.

I’d love your feedback and suggestions to make it more production-grade!

Leave a comment

I’d love your feedback and suggestions to make it more production-grade!

PS: Used multiple queues to make the architecture visually clean.

Leave a comment

This design focuses on geo-based search, efficient indexing, and low-latency lookups to ensure high scalability and availability.

I’d love your feedback or suggestions to make it more production-ready as part of my 30-day system design challenge.

Leave a comment

I’d love your feedback — how would you improve or scale this further?

PS: Used multiple queues in the diagram to keep the flow visually clear.

I’d love your thoughts!
How would you rate this design and what improvements or trade-offs would you suggest to make it more production-grade? Your feedback will help me refine my approach throughout this challenge.

PS: Used multiple queues in the diagram to make the design visually cleaner.

Leave a comment

I’d love your feedback or suggestions to make it more real-world and scalable as part of my 30-day system design challenge.

Leave a comment

This design focuses on scalability, real-time updates, and modular service communication using Queues and WebSocket.

I’d love your feedback, suggestions, or alternate approaches to make it more production-ready and robust. Your insights will help me refine my system design thinking.

PS: I’ve used multiple queues in the diagram just to make the flow clearer and easier to understand visually.

Leave a comment

I’d love your feedback or suggestions to make it more scalable and production-ready. Your insights will help me refine my thought process.

Leave a comment

Let’s explore how it all works—from the moment a client makes a request to the way PostgreSQL stores and protects your data.

✍️ Logging Before Writing: The Core Idea

PostgreSQL uses a method called Write-Ahead Logging. As the name suggests, changes are first written to a log before they are written to the actual database files.

This log is known as WAL, and it lives in a separate directory (usually pg_wal/).

Here’s what happens when you make a change:

1. You run a query (e.g., insert a new row).

2. PostgreSQL creates a WAL entry describing this change.

3. This WAL entry is stored in memory first (WAL buffer).

4. It is flushed to disk as soon as:

   • The transaction is committed

   • The buffer is full

   • A checkpoint happens

The main database files are updated later. That’s why WAL is essential for crash recovery.

Why This Matters: The Purpose of WAL

The main goals of WAL are:

• Crash Recovery: If PostgreSQL crashes, it replays the WAL logs to restore the last consistent state.

• Durability: Once a transaction is committed, the log entry is flushed, making the commit permanent—even if the database crashes right after.

• Replication: WAL files are shipped to replica servers to mirror the primary database.

• Performance: Writing to the WAL (which is sequential and fast) is much quicker than updating many random places in the database.

In short, WAL helps PostgreSQL strike a balance between safety and speed.

When Does WAL Hit the Disk?

Although changes are first written to the WAL buffer (RAM), PostgreSQL ensures the buffer is flushed to disk at the right times to avoid data loss.

WAL gets flushed,

• On every COMMIT: A transaction is not considered "done" until its WAL records are safely written to disk.

• When WAL buffer is full: PostgreSQL doesn’t let it overflow—it flushes to disk.

• During Checkpoints: A background process called the checkpointer ensures that both WAL and dirty pages (modified memory pages) are flushed periodically.

This guarantees that data won’t be lost even if power goes off right after a COMMIT.

Inside a WAL Entry: What Gets Logged?

Each WAL entry contains just enough information for PostgreSQL to replay a change.

While the actual WAL file is binary, conceptually, it includes:

• Transaction ID

• Operation type (INSERT, DELETE, etc.)

• Affected table and page

• Row-level data (before/after)

🧠 Think of it like a mini instruction:

“Hey, I just inserted a row into the orders table. Here’s what I changed.”

Here’s a mock version of what it would look like if it were readable:

TXID: 1589
Operation: INSERT
Table: orders
Row: {order_id: 9812, total: 499.00}

Meet the Log Sequence Number (LSN)

Each WAL entry has a unique Log Sequence Number (LSN)—a kind of “address” pointing to a specific position in the WAL file.

Purpose of LSN:

• Helps PostgreSQL know how far the WAL has been written or replayed.

• Replication uses it to decide what changes replicas have already received.

• Checkpoints record the current LSN to indicate up to where data is safely on disk.

An LSN looks like this: <log segment>/<offset>. Example: 0/16D328F0

• LSNs don’t increment by 1. They grow based on how much data is written. Some operations write more to WAL and increase LSN faster.

The Silent Guardian: PostgreSQL Checkpointer

The checkpointer is a background process that periodically:

• Flushes all dirty memory pages to disk

• Flushes WAL up to the current LSN

• Writes a checkpoint record to the WAL

Why this matters:

Checkpoints reduce how far PostgreSQL needs to go back when replaying WAL during a crash. Instead of replaying all logs from the beginning, it starts from the last checkpoint.

Checkpoints are crucial for speeding up recovery and keeping the WAL size under control.

Replaying WAL: Bringing PostgreSQL Back to Life

When PostgreSQL starts after a crash, it performs WAL replay to ensure data consistency.

Recovery Steps are as follows.

1. Find the last checkpoint and its LSN.

2. Start reading WAL from that point.

3. Apply all operations (INSERT, UPDATE, etc.) in sequence.

4. Stop once it reaches the last flushed WAL entry.

This process is automatic and ensures that the database reflects all committed transactions, even if the actual data files weren't updated yet.

Similarly, replica servers also replay WAL entries to stay in sync with the primary.

In Simple Words…

If PostgreSQL were a person keeping a diary:

• Every time it thinks of a change, it first writes it in the diary (WAL).

• It then makes the change to the actual house (data file) a bit later.

• If the house catches fire, it can rebuild everything from the diary.

• It marks “milestones” in the diary (checkpoints) to avoid reading from page 1 every time.

Final Thoughts

PostgreSQL's WAL system is the unsung hero of database reliability. It ensures that even in the face of hardware failures, crashes, or power losses, your data remains safe, recoverable, and consistent.

Knowing how WAL, LSN, and checkpoints work not only helps you understand PostgreSQL better but also prepares you to debug, optimize, and design reliable systems.