LangGraph — Agentic Workflows

The graph you can't change, and the model that can't act#

Picture a support agent that has just correctly classified a ticket as "billing." What happens next? In the version we built first: nothing. The model returned the word "billing" and stopped. A real human agent would open the customer's account, check the payment history, pull the invoice, confirm whether they were really charged twice. The model can't do any of that — not because it's dumb, but because it has no hands. This lesson is about two structural facts that shape every serious LangGraph app: the graph is frozen once you build it, and the model at its center can only produce text until you give it tools.

Edges: the wiring, in one breath#

An edge connects one node to the next; the type of edge decides whether that connection is fixed or chosen. Before compilation makes sense, the four edge types need to be clear.

Compilation: turning a definition into a frozen machine#

Calling builder.compile() validates the entire graph definition and produces an immutable, executable graph object. Up to this point you've been describing a graph — adding nodes, drawing edges. Compilation is the moment the description is checked for correctness and then sealed.

The validation pass runs several critical checks before it will hand back a graph:

• The declared entry point points to a node that actually exists.
• Every node referenced by an edge is a registered node.
• Every conditional edge has a mapping covering all the return values its router function can produce.
• Every path through the graph has a terminal condition — it can reach END.

Once those pass, the graph becomes immutable. You cannot add nodes, remove edges, or change routing logic at runtime. This is deliberate: if behavior is fully fixed by the definition, the graph is predictable, inspectable, and safe to run in concurrent environments where many invocations execute at once. The compiled graph is thread-safe and can be shared across invocations — each graph.invoke() spins up its own isolated state, so parallel requests never step on each other.

Where you compile matters more than it looks#

There are two ways to place the graph definition. The wrong way puts build_graph().compile() inside the function that handles each request. The right way defines and compiles the graph once at module level, then reuses that compiled object across every invocation.

# WRONG — recompiles on every call
def handle_request(ticket: str):
    builder = StateGraph(SupportState)
    # ... add nodes / edges ...
    graph = builder.compile()          # ~50-200ms wasted, every request
    return graph.invoke({"raw_input": ticket})

# RIGHT — compile once, at module level
builder = StateGraph(SupportState)
# ... add nodes / edges ...
graph = builder.compile()              # runs ONCE when the module loads

def handle_request(ticket: str):
    return graph.invoke({"raw_input": ticket})   # reuse the frozen graph

The classifier agent: a graph that decides#

The worked example is a support-ticket classifier: it takes a raw ticket, classifies it as technical, billing, fraud, or general, and routes it to the matching handler. The model is Gemini 2.5 Flash at temperature 0. [!] The session summary mentions "Gemini 1.5 Flash," but the actual code sets gemini-2.5-flash; the code is authoritative here.

The central contract is the state — a typed dictionary that flows through every node (the real thing carried ~17 fields). The classifier node runs a defensive pipeline rather than trusting the model's raw output:

Normalize strips stray spaces and punctuation and lowercases the result; validate checks it against the four known categories; if it doesn't match, the category falls back to general rather than crashing. The graph then routes on that category to one of four handler nodes.

Why an LLM is a read-only system#

An LLM is a text-transformation function: tokens in, tokens out. Reasoning, summarizing, coding, answering — all of it is an emergent property of that single token-in/token-out architecture. That architecture has three consequences every engineer has to internalize before shipping.

The passivity is a deliberate design choice, not a bug: it's what makes a model safe to run across shared, multi-tenant cloud environments. But it means anything that depends on information outside the training data will be fabricated, hallucinated, or refused — none of which is acceptable in production.

These map onto four hard limits of a tool-free LLM, useful as a debugging checklist when a production agent misbehaves — is the root cause a missing tool, or something else?

The tool-calling paradigm: three components, one loop#

A tool is a Python function the LLM can request to be called, whose result is returned to the LLM as part of its context. That single sentence hides a three-party contract.

That last step closes the loop that turns a read-only transformer into an actor: request → execute → append result → answer.

Defining a tool: @tool, type hints, and the docstring#

The @tool decorator (from langchain_core.tools) turns a plain function into something the LLM can understand. It performs three operations: schema extraction (inspects the signature and parameter types), docstring parsing (uses the docstring as the tool's description), and wrapping (returns a structured tool object that carries its own name, schema, and description).

from langchain_core.tools import tool

@tool
def get_customer_details(customer_id: str) -> dict:
    """Retrieve a customer's billing information and purchase history from the CRM.

    Call this tool when the user's query involves billing, invoices, payment
    status, or subscription management and is actionable.

    Args:
        customer_id: The unique customer identifier, format 'CXXXX' (e.g. 'C1042').

    Returns a dict with billing_status, last_payment_date, and purchase_history.
    """
    record = crm.lookup(customer_id)          # real DB call, in the agent runtime
    # return ONLY the fields the LLM needs — not the whole raw row
    return {
        "billing_status":    record["billing_status"],
        "last_payment_date": record["last_payment_date"],
        "purchase_history":  record["purchase_history"][:3],
    }

A production docstring answers four questions, in the order the model needs them: what does this do (describe the action), when should it be called (explicit triggering conditions), what does each parameter mean and what format (with an example like C1042), and what does it return (so the model doesn't guess).

Binding tools to the LLM#

Defining a tool and binding it are two distinct operations. @tool creates the object; bind_tools() tells a specific LLM those tools are available. Binding sends no API request — it returns a new model object that, when invoked, will include the tools' JSON schema in every request. Under the hood, bind_tools calls each tool's schema method (the schema the decorator built from the signature and docstring) and attaches it.

llm_with_tools = llm.bind_tools([get_customer_details])   # no request sent; new object

response = llm_with_tools.invoke("Check account C1042")
print(type(response))          # AIMessage
print(response.tool_calls)     # [{'name': 'get_customer_details',
                               #   'args': {'customer_id': 'C1042'},
                               #   'id':   'call_abc123'}]

When a tool-bound LLM decides to call a tool, it doesn't produce normal text — it produces an AI message whose tool_calls attribute holds a list of dicts, each with three fields:

An AI message can carry several shapes, worth recognizing when debugging:

ToolNode: execution and error containment#

ToolNode is LangChain's built-in execution layer that sits between the LLM and the rest of the graph. It intercepts the tool-call request, runs the matching Python function, and packages the result as a tool message. Its existence as a separate component is a deliberate principle: separate reasoning from execution. The LLM node reasons about what to do; the tool node does it. That separation buys three things.

ToolNode is instantiated with the same list of @tool objects bound to the LLM — that's what connects tool names to references. The tool name in the LLM's response must exactly match a tool name in the node's list.

Interview & practice questions#

Key takeaways#

• compile() validates and freezes the graph; do it once at module level and invoke many times.
• A compiled graph is immutable and thread-safe; every invocation gets isolated state.
• An LLM is a read-only text function — temporally isolated, environment-isolated, and passive.
• Never trust an LLM's text for deterministic work (money, IDs, DB writes); delegate to a tool.
• Tool calling has three parts: the Python function, the model's structured request, and the returned tool message.
• The docstring and type hints are the tool's real spec — the model never sees the source.
• Return trimmed dicts, not strings, to keep the context window clean.
• bind_tools() sends nothing; ToolNode executes and contains errors so the graph doesn't crash.