LangChain Agents & Tool Use

Defining tools intermediate

Here's the thing nobody tells you when you start building agents: the model can't run your code. It has never seen your functions, it can't import your module, and it certainly can't reach into your process and call anything. All it can do is say a sentence — "I'd like to call get_weather with city='Paris'" — and hope something on your side listens. A tool is how you make that sentence possible: it's the bridge between the model's words and your running code.

Think of it like ordering at a restaurant with a fixed menu. You don't walk into the kitchen and cook — you point at a menu item, and the kitchen does the rest. The menu is what the model sees: a list of names, a one-line description of each dish, and what you have to specify ("how many, what size"). The model picks from that menu; your code is the kitchen. If a dish isn't on the menu, the model literally cannot order it. This is why the quality of your tool descriptions matters so much — they're the menu the model reads, and a badly worded menu gets you the wrong dish.

So a LangChain tool is three things bundled together: a name (what to call), a description (when and why to call it), and an argument schema (what to fill in). The lovely part is you don't hand-write any of that JSON. The @tool decorator reads a plain typed Python function and builds all three from the function itself — the name from the function name, the description from its docstring, the schema from its type hints. You write ordinary code; the decorator packages it into something a model can point at.

The mistake beginners make is treating the docstring as an afterthought — a throwaway "gets weather" — and then wondering why the agent calls the wrong tool or ignores a perfectly good one. Remember the menu analogy: that docstring is the menu entry the model reads to decide. Write it the way you'd write a menu item for a stranger — say plainly when to reach for it, not just what it technically does. A LangChain tool is a function plus a schema and a description. The @tool decorator builds all three from a typed function with a docstring.

tools.pyfrom langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city. Use when the user asks about weather."""
    return f"18°C and clear in {city}"

@tool
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

print(get_weather.name)          # "get_weather"
print(get_weather.description)   # from the docstring — drives tool selection
print(get_weather.args)          # {"city": {"type": "string"}} — from the type hints

Binding tools to a model intermediate

You've defined tools. But the model still doesn't know they exist. Handing a model a tool isn't like passing a function to another function — the model runs on a server far away and only ever receives text and a bit of structured metadata. "Binding" is the act of telling the model, on every request, "here are the tools you're allowed to ask for, and here are their schemas." Skip this step and the model will happily answer your weather question by guessing a temperature, because as far as it knows there is no get_weather to call.

The analogy that makes this click: bind_tools is handing someone the menu, and invoke is them placing an order. The waiter (the model) reads the menu, decides what they want, and calls it back to you — "I'll have the get_weather, city of Paris." Crucially, saying the order out loud does not cook the food. The model returns a request — a name, some arguments, and an id — and then stops. Nothing has run. The kitchen (your code) still has to receive that order, actually execute the function, and bring back the result.

This is the single most important mental model on the whole page, so it's worth stating bluntly: the model requests; it never executes. When you call bind_tools and then invoke, what comes back in msg.tool_calls is a to-do list, not a done list. It's the exact same pattern you saw in the raw Anthropic API in C2 — the model emits a tool-use block, you run it, you feed the result back — just one convenient layer up. An agent, which you'll build in the next section, is nothing more than the machine that automates that request→run→feed-back cycle so you stop doing it by hand.

The trap here is assuming that because you got a tool_calls back, the tool actually ran — people print the message, see the tool name and the right arguments, and conclude "great, it worked." It didn't do anything yet; it only decided what to do. Understanding this gap — between deciding and doing — is what stops you from wiring a model straight to a destructive action and being surprised when it fires. Before an agent, understand the primitive under it: bind_tools. It tells the model which tools exist; the model responds with tool-call requests you then execute — exactly the C2 pattern, one layer down.

Requires: pip install langchain-anthropic (Claude) or pip install langchain-openai (OpenAI)

Binding tools to a model — in Claude or OpenAI

LangChain gives both vendors the same interface, so bind_tools and invoke are identical — only the model object changes. In Claude it's ChatAnthropic(model="claude-opus-4-8") from langchain_anthropic; in OpenAI it's ChatOpenAI(model="gpt-5.5") from langchain_openai. Toggle the tabs — your choice applies across the whole page.

bind.pyfrom langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-opus-4-8", max_tokens=512)
model_with_tools = model.bind_tools([get_weather, add])

msg = model_with_tools.invoke("What's the weather in Paris?")
print(msg.tool_calls)   # [{'name': 'get_weather', 'args': {'city': 'Paris'}, 'id': '...'}]

bind.pyfrom langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-5.5", max_tokens=512)
model_with_tools = model.bind_tools([get_weather, add])

msg = model_with_tools.invoke("What's the weather in Paris?")
print(msg.tool_calls)   # [{'name': 'get_weather', 'args': {'city': 'Paris'}, 'id': '...'}]

Lab L3.2 · A tool-calling agent intermediate

So far you've been the kitchen — you had to run every tool the model ordered and carry the plate back yourself. That's fine for one call, but real tasks need several rounds: the model asks for the weather, reads it, then asks for the arithmetic, reads that, then finally answers. Doing that dance by hand — invoke, check for tool calls, run them, append the results, invoke again, check again — is tedious and easy to get wrong. An agent is the thing that does the whole dance for you.

Picture hiring an assistant instead of micromanaging one. Before, you gave one instruction and waited for one reply. Now you hand over a goal — "tell me the weather in Paris and what 12 + 30 is" — and a set of tools, and the assistant loops on its own: decides a tool is needed, uses it, looks at the result, decides whether it needs another, and only comes back to you when it has a complete answer. You supply the capabilities (the model and the tools); the agent runtime supplies the loop that keeps calling until the work is done. That loop — think, act, observe, repeat — is exactly the ReAct pattern you met in L1, now running for you automatically.

The recommended way to get that runtime is LangGraph's create_react_agent, and the import surprises people: it comes from langgraph.prebuilt, not from langchain. That's not an accident — it's the whole reason the next section exists. For now, take it as a prebuilt, batteries-included ReAct agent: you pass it a model and a list of tools, it hands you back something you can invoke with a conversation, and it runs the reason→act→observe loop until the model produces a plain answer.

The common wrong turn is following an older tutorial that reaches for initialize_agent or AgentExecutor with cryptic "agent types" like ZERO_SHOT_REACT_DESCRIPTION. Those are the previous generation of the API — they still appear all over the internet, and they still mostly work, but they're not where LangChain is steering you anymore. Learn create_react_agent: it's more controllable, and it's the direct on-ramp to the from-scratch graphs you'll build in L4 and L5. The agent runtime closes the loop: it calls the model, executes any requested tools, feeds results back, and repeats until the model answers. The modern, recommended way to get one is LangGraph's create_react_agent — a prebuilt ReAct agent (L1) that LangChain now points to as the default.

shellpip install langgraph langchain-anthropic

agent.pyfrom langgraph.prebuilt import create_react_agent
from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-opus-4-8", max_tokens=1024)

agent = create_react_agent(model, tools=[get_weather, add])   # prebuilt ReAct loop

result = agent.invoke({"messages": [("user", "Weather in Paris, and what's 12 + 30?")]})
for m in result["messages"]:
    m.pretty_print()   # see the full reason→act→observe trace

shellpip install langgraph langchain-openai

agent.pyfrom langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-5.5", max_tokens=1024)

agent = create_react_agent(model, tools=[get_weather, add])   # prebuilt ReAct loop

result = agent.invoke({"messages": [("user", "Weather in Paris, and what's 12 + 30?")]})
for m in result["messages"]:
    m.pretty_print()   # see the full reason→act→observe trace

Why the agent lives in LangGraph now advanced

You just imported your agent from langgraph and probably didn't blink. But that one import is a signpost for a genuine shift in how the whole ecosystem thinks about agents, and it's worth stopping on — because it explains why L4 and L5 exist at all. The short version: LangChain's original building block, the chain (L2), turned out to be the wrong shape for an agent, and LangGraph is the right one.

Here's the mismatch in plain terms. A chain is a pipeline — data flows in one direction, step A to step B to step C, and then it's done. That's perfect for "retrieve, then prompt, then parse." But an agent doesn't flow in one direction; it loops. It might call a tool once, or five times, or not at all, and it decides at runtime. A pipeline that can only go forward simply cannot express "go back and try again," and that backward edge — the cycle — is the beating heart of an agent. Ask a chain to loop and you're fighting the abstraction.

The clean way to picture the difference is a subway map versus an assembly line. An assembly line (a chain) has one path from start to finish. A subway map (a graph) has stations connected by edges you can traverse in any order, including loops back to where you were. LangGraph models your agent as exactly that: nodes (the model, the tools) joined by edges, some of them conditional ("if the model asked for a tool, go to the tools node; otherwise, stop"). That structure buys you four things a chain can't give you — cycles, persistent state that survives across steps, conditional branching, and the ability to pause for a human and resume later — and the table below lines each one up against why a chain falls short.

The nuance worth holding onto: create_react_agent hasn't hidden the graph from you, it has merely pre-assembled one. It's a convenient, opaque box that happens to be a compiled LangGraph graph underneath. That's a fine place to start — but the moment your needs stray outside the standard ReAct loop, you don't abandon the framework, you open the box and wire the nodes yourself. That's the entire arc of L4 and L5, and it's why this section is the on-ramp rather than a detour. Notice the import: the recommended agent comes from langgraph, not langchain. That's deliberate. A real agent needs things a plain chain can't express:

Lab L3.3 · Making the agent safe advanced

Everything that made the agent powerful just became the reason it's dangerous. A chatbot that only talks can, at worst, say something wrong. An agent that calls tools can do something wrong — delete a record, send an email, run a command, spend money — and it decides to do so based on text from a model that you do not fully control. The instant you gave the model the ability to act, you took on the responsibility of bounding what it's allowed to act on. This section is about the brakes.

The mindset shift is the same one every ops engineer learns the hard way: treat the model's tool arguments as untrusted input, exactly as you'd treat a form field filled in by an anonymous stranger on the internet. That's not paranoia — the arguments really can be steered by content the model read along the way. A poisoned document pulled in by your retriever, or a crafted string returned by another tool, can nudge the model into calling delete_record on the wrong id (this is prompt injection, covered in T1). If you wouldn't run a shell command typed by a stranger without checking it, don't let the model run one either.

So the safety discipline comes down to a few concrete, layered habits, and the good news is they're cheap. Least privilege: only hand the agent the tools it genuinely needs, and prefer read-or-notify over write-or-delete wherever you can — a tool that doesn't exist can't be misused. Approval gates: a destructive tool checks for confirmation before it acts, so the model can request the deletion but a human (or a rule) has to bless it. Return errors, don't raise: when a tool fails, hand the agent a plain error string instead of throwing — an exception kills the whole run, but an error message is just another observation the agent can read and route around. Step limits: cap how many times the loop can go around, so a confused agent burns a few dollars instead of looping until your bill does.

One honest caveat before the lab: the approval gate you're about to see is a tool-level check — the tool inspects a flag and refuses if it isn't set. That's a real and useful guard, but it can only say "no." What it can't do is pause the entire run, surface the pending action to a human, and resume exactly where it left off once they approve. That production-grade version needs LangGraph interrupts plus a checkpointer, which is L5's territory. For now, learn the per-tool pattern; it's the foundation the durable version is built on. An agent that can call tools can cause effects. The same discipline from Chapter 4 and Claude Code (C3) applies here.

safe_tools.pyfrom langchain_core.tools import tool

@tool
def delete_record(record_id: str) -> str:
    """Delete a record by id. Destructive — requires confirmation."""
    if not _approved(record_id):          # human-in-the-loop gate
        return "BLOCKED: awaiting human approval."
    try:
        _do_delete(record_id)
        return f"Deleted {record_id}."
    except Exception as e:
        return f"ERROR: {e}"          # return errors so the agent can adapt

Common pitfalls expert

Exercises expert

import inspect

def tool(fn):
    fn.tool_name = fn.__name__
    fn.description = (fn.__doc__ or "").strip()
    sig = inspect.signature(fn)
    fn.args = {p.name: (p.annotation.__name__ if p.annotation != inspect._empty else "any")
               for p in sig.parameters.values()}
    return fn

@tool
def get_weather(city: str) -> str:
    "Get the current weather for a city."
    return f"18C and clear in {city}"

print(get_weather.tool_name)    # get_weather
print(get_weather.description)  # from the docstring
print(get_weather.args)         # {'city': 'str'}

TOOLS = {"get_weather": lambda city: f"18C in {city}",
         "add": lambda a, b: a + b}

def model_with_tools(msg):
    # stub: decide which tool the model would ask for
    if "weather" in msg.lower():
        return {"tool_call": {"name": "get_weather", "args": {"city": "Paris"}}}
    return {"text": "I can answer directly."}

def dispatch(resp):
    if "tool_call" in resp:
        tc = resp["tool_call"]
        return TOOLS[tc["name"]](**tc["args"])
    return resp["text"]

print(dispatch(model_with_tools("what's the weather?")))   # 18C in Paris
print(dispatch(model_with_tools("hi")))                     # I can answer directly.

TOOLS = {"add": lambda a, b: a + b, "mul": lambda a, b: a * b}

def model(msgs):
    # stub reasoner: (2+3)*4 in two tool calls, then answer
    done = [m for m in msgs if m["role"] == "tool"]
    if len(done) == 0:
        return {"call": ("add", {"a": 2, "b": 3})}
    if len(done) == 1:
        return {"call": ("mul", {"a": done[0]["content"], "b": 4})}
    return {"final": done[-1]["content"]}

def run(task, max_steps=6):
    msgs = [{"role": "user", "content": task}]
    for _ in range(max_steps):
        resp = model(msgs)
        if "final" in resp:
            return resp["final"]
        name, args = resp["call"]
        result = TOOLS[name](**args)
        msgs.append({"role": "tool", "content": result})
    return "step limit"

print(run("compute (2+3)*4"))   # 20

DANGEROUS = {"delete_file"}
TOOLS = {"read_file": lambda p: "contents", "delete_file": lambda p: "deleted"}

def guarded_call(name, args, approve):
    if name in DANGEROUS and not approve(name, args):
        return {"blocked": f"approval denied for {name}"}
    try:
        return {"result": TOOLS[name](**args)}
    except Exception as e:
        return {"error": repr(e)}       # errors don't crash the loop

def auto_deny(name, args):
    return False                        # a human would decide here

print(guarded_call("read_file", {"p": "a.txt"}, auto_deny))     # result
print(guarded_call("delete_file", {"p": "a.txt"}, auto_deny))   # blocked
print(guarded_call("read_file", {"nope": 1}, auto_deny))        # error, caught

def agent_choice(needs_custom_routing, needs_extra_state,
                 needs_human_pause, needs_multi_agent):
    if any([needs_custom_routing, needs_extra_state,
            needs_human_pause, needs_multi_agent]):
        return "raw LangGraph -- you need control create_react_agent hides"
    return "create_react_agent -- prebuilt ReAct loop, don't hand-write it"

print(agent_choice(False, False, False, False))  # prebuilt
print(agent_choice(True,  False, True,  False))  # raw LangGraph

from langchain_core.tools import tool
from langchain_anthropic import ChatAnthropic      # Claude
# from langchain_openai import ChatOpenAI          # OpenAI
from langgraph.prebuilt import create_react_agent

@tool
def get_weather(city: str) -> str:
    "Get the current weather for a city."
    return f"18C and clear in {city}"

model = ChatAnthropic(model="claude-opus-4-8", max_tokens=512)   # Claude
# model = ChatOpenAI(model="gpt-5.5", max_tokens=512)            # OpenAI
agent = create_react_agent(model, tools=[get_weather])

result = agent.invoke(
    {"messages": [{"role": "user", "content": "weather in Paris?"}]}
)
print(result["messages"][-1].content)   # model answers using the tool

Knowledge check check yourself