4.1

create_agent and the graph it builds

create_agent compiles a LangGraph graph with a model node, a tools node when tools exist, and one node for each middleware hook, with a recursion limit of 9999.

You pass a model, two tools, and a prompt to create_agent, and you get back an object with invoke and stream. It looks like a chat helper. It is a compiled LangGraph graph, and every error, stream chunk, and checkpoint of the agent names one of its nodes.

When you finish this section, you can say which node each argument of create_agent adds, and when the loop between them stops. You can also read the defaults on the compiled graph and say what the agent layer costs.

What create_agent takes

create_agent: the function in langchain.agents that turns a model, tools, a prompt, and middleware into a CompiledStateGraph.

The signature at the pin has two positional parameters and thirteen keyword parameters. This table lists what each one changes in the graph:

ParameterDefaultWhat it changes
modelrequiredA string goes through init_chat_model. The model is called from the model node.
toolsNoneFunctions and BaseTool objects run in the tools node. A dict is a provider tool, which is bound to the model and never run by the graph.
system_promptNoneA string becomes a SystemMessage. It goes in front of the messages on each model call and stays out of the state.
middleware()Each hook of each middleware becomes a node or a wrapper. Middleware can also add tools and state keys.
response_formatNoneA schema adds a structured output tool or a provider format. Section 4.2 explains both.
state_schema, context_schemaNoneThe state type and the type of context for each run.
checkpointer, storeNoneSaved state per thread, and long-term memory. Part 5 covers both.
interrupt_before, interrupt_afterNoneStatic pauses before or after named nodes.
name, debug, cache, transformersNone, False, None, NoneA graph name, debug output, a node cache, and stream transformers.

Section 3.2 shows how a model string resolves. Section 3.5 shows why the prompt stays out of the state.

The nodes

The kit builds the agent of section 1.3 with one tool and no middleware. The compiled graph has four nodes:

jsonthe nodes of an agent with one toolFull log
[
  "__start__",
  "model",
  "tools",
  "__end__"
]

The tools node exists only when the agent has a tool to run, or a middleware with a wrap_tool_call hook. With no tools, the same call builds three nodes:

jsonthe nodes of an agent with no toolsFull log
[
  "__start__",
  "model",
  "__end__"
]

Middleware adds nodes. Each before_agent, before_model, after_model, and after_agent hook becomes a node named after the middleware and the hook. The kit adds three middlewares named A, B, and C, each with every hook:

jsonthe nodes with three middlewaresFull log
[
  "__start__",
  "model",
  "tools",
  "A.before_agent",
  "A.before_model",
  "A.after_model",
  "A.after_agent",
…
  "__end__"
]
The B and C nodes are cut. They follow the same pattern.

The wrap_model_call and wrap_tool_call hooks add no node. They run inside the model node and the tools node. Section 4.5 gives the order of all six hooks. Figure 4.1 maps each argument to the part of the graph it builds.

Fig. 4.1what each argument of create_agent buildsstructure
What each argument of create_agent builds Three compiled graphs read from the capture kit. create_agent with a model and no tools has 3 nodes: __start__, model, __end__. Adding tools=[add] adds the tools node, 4 nodes. Adding middleware=[A, B, C] with all four node hooks adds 12 hook nodes, 16 in all, drawn as a grid with the 17 edges of the graph: the before hooks run A, B, C, the after_model hooks run C, B, A, and A.after_model routes to tools, back to A.before_model, or to the after_agent hooks. A dashed amber edge leaves a node with more than one next node. The system_prompt and the response_format add no node. They change each request inside the model node. Every agent gets the config recursion_limit 9999 and stream_mode updates. THE NODES OF THE COMPILED GRAPH create_agent(model) 3 nodes __start__ model __end__ create_agent(model, tools=[add]) 4 nodes __start__ model tools __end__ a graph with no tools has one next node after model. Tools add the tools node and a choice. create_agent(model, tools=[add], middleware=[A, B, C]) 16 nodes, 12 of them hooks __start__ model tools A.before_agent A.before_model A.after_model A.after_agent B.before_agent B.before_model B.after_model B.after_agent C.before_agent C.before_model C.after_model C.after_agent __end__ Solid: the only next node. Dashed amber: a conditional edge, the next node is chosen at run time. system_prompt and response_format add no node: they change each request inside model. Every agent also gets recursion_limit 9999 and stream_mode updates in its config.
Tools build the tools node, middleware builds hook nodes and wrappers, and the prompt and response format change each model call without a node of their own. Read the three graphs from the top. Each one adds one argument to create_agent. A solid edge has one next node, and a dashed amber edge chooses the next node at run time.

The state

AgentState: the state type of every agent, with the keys messages, jump_to, and structured_response.

messages uses the add_messages reducer, so each node appends or replaces messages by id. jump_to is private and lasts for one step. A middleware sets it to move the run to model, tools, or the end. structured_response is in the output and never in the input. Middleware can add keys of its own, and the state_schema you pass wins a conflict.

The loop and when it stops

The edges after model are conditional:

jsonthe edges of the agent graphFull log
[
  "__start__ -> model",
  "model -> __end__ (conditional)",
  "model -> tools (conditional)",
  "tools -> model (conditional)"
]

The edge function reads the state after each model call, in this order:

  1. A jump_to value set by a middleware wins.
  2. No AI message in the state ends the run.
  3. An AI message with no tool calls ends the run.
  4. Tool calls that have no result yet go to tools, each as its own Send, so parallel calls run as parallel tasks.
  5. A new structured_response ends the run.
  6. Otherwise the run goes back to model.

A structured output tool call is not sent to tools. The model node handles it, as section 4.2 shows. An agent with no tools and a ToolStrategy or AutoStrategy has a model to model edge in place of the tools node. That edge checks jump_to, then a new structured_response, and otherwise loops. With no tools and a ProviderStrategy, the model node goes straight to the end.

Draw your graph

You built an agent and want to see its graph before you run it. The compiled graph can describe itself, with no model call and no run.

get_graph(): the method of a compiled graph that returns a Graph object from langchain_core, with its nodes and its edges.

jsonthe nodes that get_graph() returnsFull log
graph.nodes:
{
…
  "tools": {
    "name": "tools",
    "data": "ToolNode",
    "metadata": {
      "__tools": [
        "add"
      ]
    }
  },
…
}
Cut to the tools node. The other nodes have no metadata.

Each node holds the object that runs it, such as the ToolNode of tools. Each edge has a conditional flag. The tools node keeps the names of its tools as metadata.

draw_mermaid(): the method of Graph that returns the graph as Mermaid flowchart text. It needs no extra package and no network.

outputdraw_mermaid() of the agent with one toolFull log
graph TD;
	__start__([<p>__start__</p>]):::first
	model(model)
	tools(tools<hr/><small><em>__tools = add</em></small>)
	__end__([<p>__end__</p>]):::last
	__start__ --> model;
	model -.-> __end__;
	model -.-> tools;
	tools -.-> model;
	classDef default fill:#f2f0ff,line-height:1.2
	classDef first fill-opacity:0
	classDef last fill:#bfb6fc

A node line gives an id and a label. :::first marks __start__, and :::last marks __end__. An edge line with --> is a plain edge, and one with -.-> is a conditional edge. Figure 4.2 matches each line to the drawing. Every graph figure in this manual is drawn from such a text, captured from the compiled graph.

Fig. 4.2from draw_mermaid lines to a drawingstructure
From draw_mermaid lines to a drawing The draw_mermaid output of the agent with one tool, line by line, next to the drawing it describes. 4 node lines give each node an id and a label: the :::first and :::last classes mark __start__ and __end__, and the label of tools carries the metadata __tools = add. 4 edge lines follow: --> is a plain edge and -.-> is a conditional edge. The drawing has 4 nodes, 1 plain edge, and 3 conditional edges. THE LINES OF DRAW_MERMAID() THE DRAWING node lines: id(label), number matches the drawing 1 __start__([<p>__start__</p>]):::first 2 model(model) 3 tools(tools<hr/><small><em>__tools = add</em></small>) 4 __end__([<p>__end__</p>]):::last edge lines: --> plain, -.-> conditional __start__ --> model; model -.-> __end__; model -.-> tools; tools -.-> model; __start__ model tools __tools = add __end__ 1 2 3 4 The frontmatter and the classDef lines only set the style.
Each node line of draw_mermaid becomes one node, and each edge line becomes one arrow, solid for --> and dashed for -.->. Match the numbered node lines on the left to the numbered nodes on the right. Each edge line shows the arrow style it becomes.

xray: the argument of get_graph that opens each subgraph node and draws its nodes inside a box. True opens every level, and an integer opens that many levels.

A parent graph with one subgraph shows the difference. get_graph() gives the subgraph as one node, inner. get_graph(xray=True) gives its two nodes in its place:

jsonthe nodes of a parent graph with xray=TrueFull log
[
  "__start__",
  "prepare",
  "finish",
  "__end__",
  "inner:shout",
  "inner:ask_ok"
]

Section 6.7 draws the parent graph both ways. An agent from create_agent has no subgraph node, so xray changes nothing in its graph.

draw_ascii(): the method of Graph that draws the graph as text. It needs the grandalf package, and langchain-core does not install it. The kit pin leaves it out, so the call raises:

outputdraw_ascii() at the pinFull log
draw_ascii():

raised builtins.ImportError: Install grandalf to draw graphs: `pip install grandalf`.

Install grandalf in your own environment when you want a drawing in the terminal.

draw_mermaid_png(): the method of Graph that turns the Mermaid text into a PNG image. Its default draw method is the API method:

jsonthe defaults of draw_mermaid_png() at the pinFull log
keyword defaults:
{
  "draw_method": "api",
  "base_url": null,
  "max_retries": 1,
  "output_file_path": null
}

The API method encodes the whole Mermaid text in base64. It puts the result in the URL of a GET request to a public rendering service. So your node names, tool names, and node metadata leave your machine in that URL. Do not call the default on a graph whose names are private.

base_url sends the same request to a Mermaid server that you run. The PYPPETEER method renders in a local headless browser, with the pyppeteer package. That page still loads the Mermaid script from a public content delivery network, so it needs the network too. The kit calls neither method. It captures the Mermaid text, and the figures of this manual draw that text offline.

Parallel tool calls and max_concurrency

max_concurrency: the key of the run config that caps how many tasks of one step run at the same time.

We measured parallel tool calls on the x86 server guest, 32 vCPU. Qwen3 4B was asked for 1 to 16 parallel calls and made 2, 2, 4, 8, 16. The ToolNode cells ran its real reply, 5 times each. create_agent called the model in every run, asked for 8, 3 times each. The tool ran a 200 ms pg_sleep on PostgreSQL. Raw runs

ToolNode and call16 calls, cap 116 calls, cap 816 calls, no cap
invoke, sync tool3,331.0 ms, 1 at a time460.0 ms, 8 at a time264.2 ms, 16 at a time
ainvoke, async tool233.7 ms, 16 at a time233.1 ms, 16 at a time233.7 ms, 16 at a time
ainvoke, sync tool267.1 ms, 16 at a time266.5 ms, 16 at a time269.2 ms, 16 at a time
create_agent and call8 calls, cap 18 calls, cap 48 calls, no cap
invoke, sync tool1,674.0 ms, 1 at a time437.2 ms, 4 at a time229.2 ms, 8 at a time
ainvoke, async tool1,668.7 ms, 1 at a time421.9 ms, 4 at a time210.5 ms, 8 at a time
ainvoke, sync tool1,669.7 ms, 1 at a time431.0 ms, 4 at a time231.2 ms, 8 at a time

Each ToolNode cell gives the median wall time and the largest number of calls that ran at one time. Each create_agent cell gives the median time from the first tool start to the last tool end. A whole run took 12 to 14 s with the model. Every successful run executed each call once and wrote one ToolMessage for it.

create_agent applied the cap in every mode, because each call is its own Send task. With no cap, sync tools run in a thread pool. The Python default pool is min(32, cpu+4). That is 14 on the 10-core Mac and 32 on the guest, where 16 sync calls ran at once in 264 ms.

The max_concurrency key also sets the size of that pool, so a value above the default makes it larger. Async tools under ainvoke had no default cap. A tool with only an async body raised NotImplementedError under invoke in 125 of 125 ToolNode rows and 9 of 9 agent runs.

A plain ToolNode under ainvoke ignored the cap, for async tools and for sync tools. Issue langgraph#8517 reports the async case. Our runs reproduce it and show that sync tools on the async path are affected too. Under invoke, ToolNode applied the cap. Set max_concurrency on the run when a tool calls a service with a rate limit, and use create_agent when you need the cap under ainvoke.

The defaults on the compiled graph

create_agent sets a config on the graph before it returns it:

outputthe config and the stream mode of every agentFull log
agent.config:
{
  "recursion_limit": 9999,
  "metadata": {
    "ls_integration": "langchain_create_agent"
  },
  "configurable": {}
}

agent.stream_mode = 'updates'
type langgraph.graph.state.CompiledStateGraph
Cut to the config, the stream mode, and the type.

The limit of 9999 steps applies to every run that does not pass its own recursion_limit. The default stream mode is updates, so a stream with no mode yields one chunk for each node that ran. Section 1.3 runs an agent into the limit and shows the chunks. A name also adds lc_agent_name to the metadata.

What the agent layer costs

We measured one task on the Mac: two tools and three model calls, against Qwen3 4B on Ollama, 40 shuffled runs each. A plain openai loop and create_agent sent the same tool schemas and got the same answer in every run. A proxy timed each model call, and the time outside the model is the rest of the run. Raw runs

VariantTime outside the model, medianMore than the plain loop, same round
plain openai loop25.1 msthe baseline
ChatOpenAI.bind_tools loop29.3 ms6.6 ms
create_agent37.6 ms15.6 ms
create_agent with InMemorySaver37.6 ms12.2 ms
hand-built StateGraph36.7 ms11.5 ms

The agent layer added about 5 ms for each model call. With create_agent, 2.3% of a 1.8 s run was outside the model. Section 8.3 gives the full cost story, with tokens, request bytes, and import time.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11