Tool Binding & Execution

Notebook Summary#

Hand-copy this. Telegraphic recall notes — every point is derivable from the detailed notes below.

Detailed Study Notes#

Your support agent reads a ticket — "I was charged twice this month" — and correctly labels it billing. Then it does nothing. It can't open the customer's account, can't check whether a payment really landed twice, can't issue the refund. It classified a problem it has no way to act on. That gap — between a model that describes and a system that does — is the whole subject of this lesson.

2.1Graph compilation & immutability#

Compiling a graph turns your definition into a frozen, validated, runnable object. In LangGraph you first describe an agent as a set of nodes and edges on a builder. Calling builder.compile() walks that whole definition once, checks it, and hands back an executable graph you can no longer edit.

Analogy. Compiling is the pre-flight check. The ground crew verifies every door is wired to a real destination and no gangway leads off a cliff — and once the plane pushes back, nobody rewires it mid-air.

The compile step performs several structural checks: the declared entry point really points at a registered node; every node named in an edge actually exists; and every conditional edge's routing map covers all the values its router function can return. Miss a return value and there's a path through your graph with no destination. After these pass, the graph becomes immutable — you cannot add nodes, remove edges, or change routing at runtime.

Immutability is a deliberate design choice, not a limitation. Because the compiled graph can't change, its behaviour is fully determined by the definition, which makes it thread-safe: one compiled graph can be shared across many concurrent requests, and each call to graph.invoke() spins up its own isolated state. This is the "compile once, invoke many" principle.

# ✓ compiled ONCE at import — reused across all requests
graph = build_graph().compile()

def handle_request(ticket: str):
    # ✗ do NOT put build_graph().compile() in here
    return graph.invoke({"raw_input": ticket})

Two more production failure modes came up alongside compilation. An infinite loop happens when a conditional router keeps returning the same node with no exit — fixed by wiring at least one branch to the terminal END state and adding a retry-count field to state that caps iterations (e.g. at three). A state-mutation bug happens when a node edits the state dict in place (state["k"] = v) instead of returning a fresh dictionary.

2.2DAG vs. agent — recipe vs. chef#

A plain pipeline blindly runs fixed steps; an agent inspects what happened and decides what to do next. A directed acyclic graph (a DAG) is a static list of steps that assumes each one succeeds. A LangGraph agent adds decisions and loops on top of that skeleton.

The support-ticket agent from Session 7.1 makes this concrete. A typed SupportState dictionary is the central contract that flows through every node. A classifier node reads the raw ticket and, via Gemini 2.5 Flash [!], sorts it into one of four categories; a router then sends it to the matching handler.

The classifier is a small defensive pipeline: send the prompt, take the raw model output, normalize it (strip whitespace/punctuation, l-case), validate it against the four allowed categories, and fall back to general if it's anything else. The router then maps the category to a handler node — technical, billing, fraud, or general — and that routing is a conditional edge.

2.3Why tools exist — the LLM is read-only#

At its core a language model is one function: tokens in, tokens out. Every capability it seems to have — reasoning, summarizing, writing code — is an emergent property of that single token-to-token transform. That architecture has three consequences every engineer must internalize before shipping.

Passivity is not a bug; it's a deliberate design choice that makes the model safe to run in shared, multi-tenant cloud environments. But it's a limitation every agent architect has to work around. The practical upshot is a short debug checklist: when a production AI system misbehaves, run through the four things a tool-free model simply cannot do, and you'll immediately know whether the root cause is a missing tool or something else.

2.4What a tool is — the three-party contract#

A tool is a plain Python function the model can ask to have run, whose result is fed back into the model's context. Nothing exotic — the function can query a database, call an API, do a calculation, read a file. What makes it a tool is the contract around it: three parties, each with one job.

Without the Python function, no real-world data ever reaches the model and it may hallucinate. Without the model, nothing decides which tool to call. Without the tool node, an error inside a tool crashes the whole graph. The contract only works when all three hold.

2.5Defining a tool — @tool, type hints, docstrings#

The @tool decorator turns an ordinary function into something the model can understand and the framework can run. Imported from langchain_core.tools, it does three things to the function it wraps.

Type hints are the schema contract. Every parameter's annotation becomes the type the model is told to send. Get it right and the model passes a value the function can use; leave it off and things break silently.

The docstring is the intelligence layer — and here's the insight that reframes tool design.

A production-grade docstring answers four questions, in the order the model needs them:

from langchain_core.tools import tool

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

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

    Args:
        customer_id: unique customer id, format C-XXXX (e.g. C-1042).

    Returns:
        dict with billing_status, last_payment_date, purchase_history.
    """
    record = crm.lookup(customer_id)          # the real work
    return {                                   # only what the LLM needs
        "billing_status":    record.status,
        "last_payment_date": record.last_paid,
        "purchase_history":  record.purchases[:3],
    }

2.6Binding tools & reading the request#

Defining a tool and binding a tool are two different acts. Defining it with @tool creates the object. Binding tells a specific model "these tools are available to you." llm.bind_tools([...]) is a Python-to-JSON handshake: it calls each tool's schema method, collects the JSON schemas, and returns a new model object. It sends no API request — it just produces a model that will include those schemas in every future call.

When a bound model decides to use a tool, it doesn't emit normal text. It returns an AIMessage whose .tool_calls attribute is a list of dictionaries, each with three fields:

An AIMessage can carry both text and tool calls (the model reasons aloud, then requests a tool), or only tool calls with empty content (a pure request), or plain text with an empty tool-calls list (it can answer from context alone). It may also request several tools at once.

llm_with_tools = llm.bind_tools([get_customer_details])
resp = llm_with_tools.invoke("check account C-1042")

print(type(resp))          # AIMessage
print(resp.tool_calls)
# [{'name': 'get_customer_details',
#   'args': {'customer_id': 'C-1042'},
#   'id':   'call_abc123'}]

For Gemini models the same protocol runs over Google's function-calling API. LangChain's bind_tools transparently translates between its own tool-schema format and Google's function-declaration format, so from your side the API is identical regardless of provider — one of LangChain's core value propositions. (This standardized tool-calling shape was pioneered by OpenAI and later adopted by Google and Anthropic.)

2.7The tool node — execution & error catching#

The tool node is LangChain's built-in component that actually runs the requested tools and catches their failures. It sits between the LLM node and the rest of the graph: it intercepts the tool-call request, runs the matching Python function, and packages the return value as a ToolMessage appended to the conversation. Its existence is a deliberate principle — separation of reasoning from execution. The LLM decides what; the tool node does it.

The tool node is instantiated with the list of tool objects — the same @tool functions you bound to the LLM. That shared list is the link between the names the model uses and the functions the node runs.

Error handling is not optional. A real CRM lookup can fail many ways: the DB is briefly down, the connection times out, the model passed a malformed id, the id is valid but the record was deleted, or the tool has a bug. In every case an unhandled exception propagates up through the tool node and crashes the graph.

2.8Interview & practice questions#

2.9Key takeaways#

1. Compile once, invoke many. Building at module level gives a validated, immutable, thread-safe graph reused across requests.
2. The LLM is read-only — temporally, environmentally, and by design. Tools are how it acts on the world.
3. Three parties, one contract: the function does the work, the model decides, the tool node mediates and contains failures.
4. The docstring is the interface. The model reasons entirely from the JSON schema; type hints and a clear docstring are the whole spec.
5. Return structured, minimal data and never let a tool exception escape — convert it to an error message the model can handle.

Microexercises#

The reading proves you recognize the ideas; these prove you can use them. Attempt each before opening the walkthrough.

3.1Build it — a production-grade tool#

from langchain_core.tools import tool

@tool
def check_order_status(order_id: str) -> dict:
    """Look up the shipping status of a customer's order.

    Call this when the user asks where their order is, whether it
    has shipped, or when it will arrive.

    Args:
        order_id: unique order id, format ORD-XXXXX (e.g. ORD-90421).

    Returns:
        dict with status, carrier, and eta_days.
    """
    order = orders.lookup(order_id)
    return {
        "status":   order.status,
        "carrier":  order.carrier,
        "eta_days": order.eta_days,
    }

# check_order_status.name        -> "check_order_status"
# check_order_status.description -> the docstring above

3.2Diagnose it — the model ignores your tool#

from langchain_core.tools import tool
from langchain_google_genai import ChatGoogleGenerativeAI

@tool
def get_balance(account):
    """Return the account balance."""
    return {"balance": bank.balance(account)}

llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash", temperature=0)

def answer(question: str):
    return llm.invoke(question)   # "what's the balance on A-77?"

@tool
def get_balance(account: str) -> dict:
    """Return the balance for a bank account.

    Call this whenever the user asks about a balance.

    Args:
        account: account id, format A-XX (e.g. A-77).
    """
    return {"balance": bank.balance(account)}

llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash", temperature=0)
llm_with_tools = llm.bind_tools([get_balance])   # ← the missing step

def answer(question: str):
    return llm_with_tools.invoke(question)        # now emits tool_calls