The agent loop,
step by step.

1. The tool-calling loop is a graph

An agent is not a new idea. It is the tool-calling loop, drawn as a cycle and run automatically.

This essay drops one level down, to the engine underneath create_agent: LangGraph. You define the nodes, the edges, and the state, and you get total control over what runs, in what order, and when it stops. The price is a little more code. The reward is that you can see, and change, every part of the loop.

An agent is a loop. A loop is a cycle in a graph. Build the graph and you have built the agent.

2. Three primitives: nodes, edges, state

Everything in a graph is one of three things. Learn them once and the rest is composition.

The smallest possible graph

Define state, write a node, wire it from START to END, compile, invoke. Every graph, however large, is this shape.

from langgraph.graph import StateGraph, START, END
from typing import TypedDict

class State(TypedDict):
    value: int

def double(state: State) -> dict:
    return {"value": state["value"] * 2}

graph = StateGraph(State)
graph.add_node("double", double)
graph.add_edge(START, "double")
graph.add_edge("double", END)
app = graph.compile()

print(app.invoke({"value": 5})["value"])   # 10

START and END are virtual nodes: the entry point and the exit. compile() validates the structure (every referenced node exists, every node is reachable, END can be reached) and returns a runnable app.

Nodes are what happens. Edges are where to go next. State is what everyone can see. Keep those three jobs separate and graphs stay easy to reason about.

3. State is the agent's memory

A model has no memory. The graph's state is where the conversation lives and grows.

The code

from langgraph.graph import StateGraph, MessagesState, START, END
from typing import TypedDict, Annotated
from langgraph.graph.message import add_messages

# Written out, the chat state is just this:
class ChatState(TypedDict):
    messages: Annotated[list, add_messages]   # append, do not overwrite

# But this pattern is so common that LangGraph ships it as MessagesState.
# Subclass it when you need extra fields:
class AgentState(MessagesState):
    pass

The agent's memory is a list of messages plus a reducer that grows it. That list is the only thing the model ever sees.

4. The agent node: call the model

The first node. It hands the conversation to the model and appends whatever the model says back.

The code

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.4")
model_with_tools = model.bind_tools(tools)

def agent(state: MessagesState) -> dict:
    """Call the model on the running conversation, append its reply."""
    response = model_with_tools.invoke(state["messages"])
    return {"messages": [response]}   # add_messages appends it

Notice the node returns {"messages": [response]}, a partial update of just the one key. The add_messages reducer appends the new AIMessage to the conversation rather than replacing it.

The agent node is one line of real work: invoke the model, append the reply. Whether that reply is a tool request or a final answer is what the next edge inspects.

5. The tools node: execute the calls

The second node. It runs whatever the model asked for and appends the results.

The code

# each tool's .name is its @tool function name
tools_by_name = {t.name: t for t in tools}

def tools_node(state: MessagesState) -> dict:
    """Run every tool the last AIMessage requested."""
    last = state["messages"][-1]
    results = []
    for call in last.tool_calls:
        chosen = tools_by_name[call["name"]]
        results.append(chosen.invoke(call))   # returns a ToolMessage
    return {"messages": results}

The tools node is the "act" half of the loop. It turns the model's requests into real results and feeds them back into the state.

6. The conditional edge that closes the loop

One small function turns two nodes into a cycle. This is the whole trick.

The code

from typing import Literal
from langgraph.graph import END

def should_continue(state: MessagesState) -> Literal["tools", "__end__"]:
    """If the model asked for tools, run them. Otherwise, finish."""
    last = state["messages"][-1]
    if last.tool_calls:
        return "tools"
    return END

LangGraph ships this exact router prebuilt, so in practice you can write:

from langgraph.prebuilt import tools_condition
# equivalent to should_continue: routes to tools if the last
# message has tool_calls, otherwise to END
graph.add_conditional_edges("agent", tools_condition)

The conditional edge is the heart of the agent. "Tools, or done?" asked after every model call, is what separates a one-shot answer from an autonomous loop.

7. Assembling the loop

Two nodes, one entry, one conditional edge, one back-edge. That is a complete agent.

The graph

Read the wiring against the diagram below. START goes to agent. agent branches: to tools if it called tools, to END if it did not. tools always returns to agent. The cycle is agent → tools → agent.

from langgraph.graph import StateGraph, MessagesState, START, END

graph = StateGraph(MessagesState)
graph.add_node("agent", agent)
graph.add_node("tools", tools_node)

graph.add_edge(START, "agent")                       # enter at the model
graph.add_conditional_edges("agent", should_continue) # tools, or END?
graph.add_edge("tools", "agent")                     # observe, then loop back

app = graph.compile()

result = app.invoke(
    {"messages": [{"role": "user", "content": "..."}]},
    {"recursion_limit": 25},                          # safety net, see Step 9
)
print(result["messages"][-1].content)

There is no magic in an agent. It is two nodes and one conditional edge. The single back-edge from tools to agent is the entire difference between a function and an agent.

8. ReAct: reason, then act

The loop in motion. Watch the agent think, call a tool, read the result, and think again.

Live: a multi-step task, one tool call at a time

Pick a task. The agent has two tools: lookup (a small fact table) and calculator. Watch it gather facts one at a time, each observation feeding the next thought, until it answers. The step meter counts super-steps against the recursion limit; lower the limit in Step 9 and the same task will halt early.

ReAct is not a special algorithm. It is what the loop looks like from the outside: reason, act, observe, repeat, with each cycle adding one hard fact to the agent's memory.

9. Stopping the loop (before it loops forever)

A cycle with no exit runs until your budget is gone. Every agent needs a hard stop.

Live: shrink the budget, watch it halt

Same agent as Step 8. Lower the recursion limit below what the task needs, run it, and the loop stops mid-reasoning with a GraphRecursionError instead of finishing.

The code

from langgraph.errors import GraphRecursionError

try:
    app.invoke(
        {"messages": [{"role": "user", "content": "..."}]},
        {"recursion_limit": 6},      # too low for a long task
    )
except GraphRecursionError:
    print("Hit the recursion limit before finishing.")

Every way an agent stops

Always set a ceiling. The loop is powerful precisely because it can keep going, which is exactly why you must tell it when to stop.

10. Workflows vs agents

Who decides the path: you, or the model? Most real systems use both.

If the workflow is "call tools until done," use create_agent. Reach for raw LangGraph when you need branching, cycles, custom state, or a human in the loop. You can migrate incrementally: LangGraph is the engine underneath either way.

11. Beyond the basic loop

The two-node loop is the foundation. A handful of primitives extend it to anything.

from langgraph.types import Command, Send

# route + update in one return
def triage(state) -> Command:
    if "urgent" in state["messages"][-1].content:
        return Command(update={"priority": "high"}, goto="escalate")
    return Command(update={"priority": "normal"}, goto="agent")

# fan out a variable number of parallel tasks
def fan_out(state) -> list[Send]:
    return [Send("worker", {"task": t}) for t in state["subtasks"]]

Nodes, edges, state, plus Command and Send for routing and fan-out. With those, the basic loop generalizes to routers, branches, parallel workers, and multi-agent systems.

12. What we left out

Real machinery, deferred to keep this essay about the loop itself.

The loop is small and the extensions are few. Persistence, interrupts, streaming, and subgraphs are the same graph with more wired in, not a different idea.