Alpha Notice: These docs cover the v1-alpha release. Content is incomplete and subject to change.For the latest stable version, see the v0 LangChain Python or LangChain JavaScript docs.
create_agent()
provides a production-ready ReAct (Reasoning + Acting) agent implementation based on the paper ReAct: Synergizing Reasoning and Acting in Language Models.
ReAct frames an agent’s behavior as an interleaving of thought
-> action
-> observation
steps, where the model writes out its reasoning, picks a tool, sees the tool’s result, and then repeats. ReAct reduces hallucinations and makes the decision process auditable: the agent can form hypotheses (thought
), test them with tools (action
), and update its plan based on feedback (observation
).
A ReAct loop runs until a stop condition - i.e., when the model emits a final answer or a max-iterations limit is reached.
create_agent()
builds a graph-based agent runtime using LangGraph. A graph consists of nodes (steps) and edges (connections) that define how your agent processes information. The agent moves through this graph, executing nodes like the model node (which calls the model), the tools node (which executes tools), or pre/post model hook nodes. Learn more about the graph API.Core components
Model
The model is the reasoning engine of your agent. It can be specified in multiple ways, supporting both static and dynamic model selection.Static model
Static models are configured once when creating the agent and remain unchanged throughout execution. This is the most common and straightforward approach. To initialize a static model from a model identifier string:provider:model
(e.g. "openai:gpt-5"
) and support automatic inference (e.g. "gpt-5"
will be inferred as "openai:gpt-5"
). You may want more control over the model configuration, in which case you can initialize a model instance directly using the provider package:
Dynamic model
Dynamic models are selected at based on the current and context. This enables sophisticated routing logic and cost optimization. To use a dynamic model, you need to provide a function that receives the graph state and runtime and returns an instance ofBaseChatModel
with the tools bound to it using .bind_tools(tools)
, where tools
is a subset of the tools
parameter.
For model configuration details, see Models.
Tools
Tools give agents the ability to take actions. Agents go beyond simple model-only tool binding by facilitating:- Multiple tool calls in sequence triggered by a single prompt
- Parallel tool calls when appropriate
- Dynamic tool selection based on results
- Tool retry logic and error handling
- State persistence across tool calls
- A list of tools (LangChain
@tool
, callable, ordict
that represents a builtin provider tool) - A configured
ToolNode
Pass a list of tools
Passing a list of tools to the agent will create aToolNode
under the hood. This is the simplest way to set up a tool-calling agent:
Pass a configured ToolNode
Alternatively, you can create aToolNode
directly and pass it to the agent. This allows you to customize the tool node’s behavior, such as handling tool errors:
ToolNode
, the agent will return a ToolMessage
to the model with the custom error message:
To learn more about error handling in
ToolNode
, see ToolNode.Tool use in the ReAct loop
Agents follow the ReAct (Reasoning + Acting) pattern, alternating between brief reasoning steps with targeted tool calls and feeding the resulting observations into subsequent decisions until they can deliver a final answer.Example of ReAct loop
Example of ReAct loop
Prompt: Identify the current most popular wireless headphones and verify availability.Reasoning: “Popularity is time-sensitive, I need to use the provided search tool.”Acting: Call Reasoning: “I need to confirm availability for the top-ranked item before answering.”Acting: Call Reasoning: “I have the most popular model and its stock status. I can now answer the user’s question.”Acting: Produce final answer
search_products("wireless headphones")
check_inventory("WH-1000XM5")
To learn more about tools, see Tools.
Prompt
You can shape how your agent approaches tasks by providing a prompt. Theprompt
parameter can be provided as a string, SystemMessage, or a callable:
prompt
is provided, the agent will infer its task from the messages directly.
Dynamic prompts with middleware
For more advanced use cases where you need to modify the system prompt based on runtime context or agent state, you can use themodify_model_request
decorator to create a simple custom middleware.
Dynamic system prompt is especially useful for personalizing prompts based on user roles, conversation context, or other changing factors:
For more details on message types and formatting, see Messages. For comprehensive middleware documentation, see Middleware.
Advanced configuration
Structured output
In some situations, you may want the agent to return an output in a specific format. LangChain provides a simple, universal way to do this with theresponse_format
parameter.
To learn about structured output, see Structured output.
Memory
Agents maintain conversation history automatically through the message state. You can also configure the agent to use a custom state schema to remember additional information during the conversation. Information stored in the state can be thought of as the short-term memory of the agent:To learn more about memory, see Memory. For information on implementing long-term memory that persists across sessions, see Long-term memory.
Pre-model hook
Pre-model hook is an optional node that can process state before the model is called. Use cases include message trimming, summarization, and context injection. It must be a callable or a runnable that takes in current graph state and returns a state update in the form of:messages
must be provided and will be used as an input to the agent
node (i.e., the node that calls the LLM). The rest of the keys will be added to the graph state.If you are returning
messages
in the pre-model hook, you should OVERWRITE the messages
key by doing the following:Post-model hook
Post-model hook is an optional node that can process the model’s response before tool execution. Use cases include validation, guardrails, or other post-processing. It must be a callable or a runnable that takes in current graph state and returns a state update. Example of a post-model hook that filters out confidential information:Streaming
We’ve seen how the agent can be called with.invoke
to get a final response. If the agent executes multiple steps, this may take a while. To show intermediate progress, we can stream back messages as they occur.
For more details on streaming, see Streaming.