You are viewing the v1 docs for LangChain, which is currently under active development. Learn more. Overview
Agents combine language models with tools to create systems that can reason about tasks, decide which tools to use, and iteratively work towards solutions.
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.
Under the hood, 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:
from langchain.agents import create_agent
agent = create_agent(
"openai:gpt-5",
tools=tools
)
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:
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
model = ChatOpenAI(
model="gpt-5",
temperature=0.1,
max_tokens=1000,
timeout=30
)
agent = create_agent(model, tools=tools)
Dynamic model
runtime: The execution environment of your agent, containing immutable configuration and contextual data that persists throughout the agent’s execution (e.g., user IDs, session details, or application-specific configuration).
state: The data that flows through your agent’s execution, including messages, custom fields, and any information that needs to be tracked and potentially modified during processing (e.g. user preferences or tool usage stats).
BaseChatModel with the tools bound to it using .bind_tools(tools), where tools is a subset of the tools parameter.
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent, AgentState
from langgraph.runtime import Runtime
def select_model(state: AgentState, runtime: Runtime) -> ChatOpenAI:
"""Choose model based on conversation complexity."""
messages = state["messages"]
message_count = len(messages)
if message_count < 10:
return ChatOpenAI(model="gpt-4.1-mini").bind_tools(tools)
else:
return ChatOpenAI(model="gpt-5").bind_tools(tools) # Better model for longer conversations
agent = create_agent(select_model, tools=tools)
For model configuration details, see Models.
- 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
Tools can be provided to the agent as either:
- A list of tools (LangChain
@tool, callable, or dict that represents a builtin provider tool)
- A configured
ToolNode
Passing a list of tools to the agent will create a ToolNode under the hood. This is the simplest way to set up a tool-calling agent:
from langchain_core.tools import tool
from langchain.agents import create_agent
@tool
def search(query: str) -> str:
"""Search for information."""
return f"Results for: {query}"
@tool
def calculate(expression: str) -> str:
"""Perform calculations."""
return str(eval(expression))
agent = create_agent(model, tools=[search, calculate])
ToolNode directly and pass it to the agent. This allows you to customize the tool node’s behavior, such as handling tool errors:
tool_node = ToolNode(
tools=[search, calculate],
handle_tool_errors="Please check your input and try again."
)
agent = create_agent(model, tools=tool_node)
result = agent.invoke({"messages": [...]})
ToolNode, the agent will return a ToolMessage to the model with the custom error message:
# result["messages"]
[
...
ToolMessage(content="Please check your input and try again.", tool_call_id="..."),
...
]
To learn more about error handling in ToolNode, see ToolNode. Prompt: Identify the current most popular wireless headphones and verify availability.
================================ Human Message =================================
Find the most popular wireless headphones right now and check if they're in stock
search_products("wireless headphones")================================== Ai Message ==================================
Tool Calls:
search_products (call_abc123)
Call ID: call_abc123
Args:
query: wireless headphones
================================= Tool Message =================================
Found 5 products matching "wireless headphones". Top 5 results: WH-1000XM5, ...
check_inventory("WH-1000XM5")================================== Ai Message ==================================
Tool Calls:
check_inventory (call_def456)
Call ID: call_def456
Args:
product_id: WH-1000XM5
================================= Tool Message =================================
Product WH-1000XM5: 10 units in stock
================================== Ai Message ==================================
I found wireless headphones (model WH-1000XM5) with 10 units in stock...
To learn more about tools, see Tools. Prompt
You can shape how your agent approaches tasks by providing a prompt. The prompt parameter can be provided in several forms.
String
agent = create_agent(
model,
tools,
prompt="You are a helpful assistant. Be concise and accurate."
)
SystemMessage
agent = create_agent(
model,
tools,
prompt=SystemMessage(content="You are a research assistant. Cite your sources.")
)
Callable
def dynamic_prompt(state):
user_type = state.get("user_type", "standard")
system_msg = SystemMessage(
content="Provide detailed technical responses."
if user_type == "expert"
else "Provide simple, clear explanations."
)
return [system_msg] + state["messages"]
agent = create_agent(model, tools, prompt=dynamic_prompt)
prompt is provided, the agent will infer its task from the messages directly.
For more details on message types and formatting, see Messages. 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 the response_format parameter.
from pydantic import BaseModel
from langchain.agents import create_agent
class ContactInfo(BaseModel):
name: str
email: str
phone: str
agent = create_agent(
model,
tools=[search_tool],
response_format=ContactInfo
)
result = agent.invoke({
"messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})
result["structured_response"]
# ContactInfo(name='John Doe', email='john@example.com', phone='(555) 123-4567')
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:
from typing import TypedDict
from typing_extensions import Annotated
from langgraph.graph.message import add_messages
from langchain.agents import create_agent
from langchain.agents import AgentState
class CustomAgentState(AgentState):
messages: Annotated[list, add_messages]
user_preferences: dict
agent = create_agent(
model,
tools=tools,
state_schema=CustomAgentState
)
# The agent can now track additional state beyond messages. This custom state can be accessed and updated throughout the conversation.
result = agent.invoke({
"messages": [{"role": "user", "content": "I prefer technical explanations"}],
"user_preferences": {"style": "technical", "verbosity": "detailed"},
})
To learn more about memory, including how to implement long-term memory that persists across sessions, see 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:
{
# Will UPDATE the `messages` in the state
"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), ...],
# Any other state keys that need to be propagated
...
}
from langchain_core.messages import RemoveMessage
from langgraph.graph.message import REMOVE_ALL_MESSAGES
from langchain.agents import create_agent
def trim_messages(state):
"""Keep only the last few messages to fit context window."""
messages = state["messages"]
if len(messages) <= 3:
return {"messages": messages}
first_msg = messages[0]
recent_messages = messages[-3:] if len(messages) % 2 == 0 else messages[-4:]
new_messages = [first_msg] + recent_messages
return {
"messages": [
RemoveMessage(id=REMOVE_ALL_MESSAGES),
*new_messages
]
}
agent = create_agent(
model,
tools=tools,
pre_model_hook=trim_messages
)
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:{
"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), *new_messages]
...
}
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:
from langchain_core.messages import AIMessage, RemoveMessage
from langgraph.graph.message import REMOVE_ALL_MESSAGES
def validate_response(state):
"""Check model response for policy violations."""
messages = state["messages"]
last_message = messages[-1]
if "confidential" in last_message.content.lower():
return {
"messages": [
RemoveMessage(id=REMOVE_ALL_MESSAGES),
*messages[:-1],
AIMessage(content="I cannot share confidential information.")
]
}
return {}
agent = create_agent(
model,
tools=tools,
post_model_hook=validate_response
)
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 chunk in agent.stream({
"messages": [{"role": "user", "content": "Search for AI news and summarize the findings"}]
}, stream_mode="values"):
# Each chunk contains the full state at that point
latest_message = chunk["messages"][-1]
if latest_message.content:
print(f"Agent: {latest_message.content}")
elif latest_message.tool_calls:
print(f"Calling tools: {[tc['name'] for tc in latest_message.tool_calls]}")
For more details on streaming, see Streaming. 
