Agents

Reference docs

This page contains reference documentation for Agents. See the docs for conceptual guides, tutorials, and examples on using Agents.

agents ¶

Entrypoint to building Agents with LangChain.

create_agent ¶

create_agent(
    model: str | BaseChatModel,
    tools: Sequence[BaseTool | Callable[..., Any] | dict[str, Any]] | None = None,
    *,
    system_prompt: str | SystemMessage | None = None,
    middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),
    response_format: ResponseFormat[ResponseT]
    | type[ResponseT]
    | dict[str, Any]
    | None = None,
    state_schema: type[AgentState[ResponseT]] | None = None,
    context_schema: type[ContextT] | None = None,
    checkpointer: Checkpointer | None = None,
    store: BaseStore | None = None,
    interrupt_before: list[str] | None = None,
    interrupt_after: list[str] | None = None,
    debug: bool = False,
    name: str | None = None,
    cache: BaseCache[Any] | None = None,
) -> CompiledStateGraph[
    AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]
]

Creates an agent graph that calls tools in a loop until a stopping condition is met.

For more details on using create_agent, visit the Agents docs.

PARAMETER	DESCRIPTION
`model` ¶	The language model for the agent. Can be a string identifier (e.g., `"openai:gpt-4"`) or a direct chat model instance (e.g., `ChatOpenAI` or other another LangChain chat model). For a full list of supported model strings, see `init_chat_model`. See the Models docs for more information. TYPE: `str \| BaseChatModel`
`tools` ¶	A list of tools, `dict`, or `Callable`. If `None` or an empty list, the agent will consist of a model node without a tool calling loop. See the Tools docs for more information. TYPE: `Sequence[BaseTool \| Callable[..., Any] \| dict[str, Any]] \| None` DEFAULT: `None`
`system_prompt` ¶	An optional system prompt for the LLM. Can be a `str` (which will be converted to a `SystemMessage`) or a `SystemMessage` instance directly. The system message is added to the beginning of the message list when calling the model. TYPE: `str \| SystemMessage \| None` DEFAULT: `None`
`middleware` ¶	A sequence of middleware instances to apply to the agent. Middleware can intercept and modify agent behavior at various stages. See the Middleware docs for more information. TYPE: `Sequence[AgentMiddleware[StateT_co, ContextT]]` DEFAULT: `()`
`response_format` ¶	An optional configuration for structured responses. Can be a `ToolStrategy`, `ProviderStrategy`, or a Pydantic model class. If provided, the agent will handle structured output during the conversation flow. Raw schemas will be wrapped in an appropriate strategy based on model capabilities. See the Structured output docs for more information. TYPE: `ResponseFormat[ResponseT] \| type[ResponseT] \| dict[str, Any] \| None` DEFAULT: `None`
`state_schema` ¶	An optional `TypedDict` schema that extends `AgentState`. When provided, this schema is used instead of `AgentState` as the base schema for merging with middleware state schemas. This allows users to add custom state fields without needing to create custom middleware. Generally, it's recommended to use `state_schema` extensions via middleware to keep relevant extensions scoped to corresponding hooks / tools. TYPE: `type[AgentState[ResponseT]] \| None` DEFAULT: `None`
`context_schema` ¶	An optional schema for runtime context. TYPE: `type[ContextT] \| None` DEFAULT: `None`
`checkpointer` ¶	An optional checkpoint saver object. Used for persisting the state of the graph (e.g., as chat memory) for a single thread (e.g., a single conversation). TYPE: `Checkpointer \| None` DEFAULT: `None`
`store` ¶	An optional store object. Used for persisting data across multiple threads (e.g., multiple conversations / users). TYPE: `BaseStore \| None` DEFAULT: `None`
`interrupt_before` ¶	An optional list of node names to interrupt before. Useful if you want to add a user confirmation or other interrupt before taking an action. TYPE: `list[str] \| None` DEFAULT: `None`
`interrupt_after` ¶	An optional list of node names to interrupt after. Useful if you want to return directly or run additional processing on an output. TYPE: `list[str] \| None` DEFAULT: `None`
`debug` ¶	Whether to enable verbose logging for graph execution. When enabled, prints detailed information about each node execution, state updates, and transitions during agent runtime. Useful for debugging middleware behavior and understanding agent execution flow. TYPE: `bool` DEFAULT: `False`
`name` ¶	An optional name for the `CompiledStateGraph`. This name will be automatically used when adding the agent graph to another graph as a subgraph node - particularly useful for building multi-agent systems. TYPE: `str \| None` DEFAULT: `None`
`cache` ¶	An optional `BaseCache` instance to enable caching of graph execution. TYPE: `BaseCache[Any] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`CompiledStateGraph[AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]]`	A compiled `StateGraph` that can be used for chat interactions.

RAISES	DESCRIPTION
`AssertionError`	If duplicate middleware instances are provided.

The agent node calls the language model with the messages list (after applying the system prompt). If the resulting AIMessage contains tool_calls, the graph will then call the tools. The tools node executes the tools and adds the responses to the messages list as ToolMessage objects. The agent node then calls the language model again. The process repeats until no more tool_calls are present in the response. The agent then returns the full list of messages.

Example

from langchain.agents import create_agent


def check_weather(location: str) -> str:
    '''Return the weather forecast for the specified location.'''
    return f"It's always sunny in {location}"


graph = create_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    tools=[check_weather],
    system_prompt="You are a helpful assistant",
)
inputs = {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
for chunk in graph.stream(inputs, stream_mode="updates"):
    print(chunk)

AgentState ¶

Bases: TypedDict, Generic[ResponseT]

State schema for the agent.

Structured output¶

ResponseFormat `module-attribute` ¶

ResponseFormat = (
    ToolStrategy[SchemaT] | ProviderStrategy[SchemaT] | AutoStrategy[SchemaT]
)

Union type for all supported response format strategies.

ToolStrategy `dataclass` ¶

ToolStrategy(
    schema: type[SchemaT] | UnionType | dict[str, Any],
    *,
    tool_message_content: str | None = None,
    handle_errors: bool
    | str
    | type[Exception]
    | tuple[type[Exception], ...]
    | Callable[[Exception], str] = True,
)

Bases: Generic[SchemaT]

Use a tool calling strategy for model responses.

Initialize ToolStrategy.

Initialize ToolStrategy with schemas, tool message content, and error handling strategy.

tool_message_content `instance-attribute` ¶

tool_message_content: str | None = tool_message_content

The content of the tool message to be returned when the model calls an artificial structured output tool.

handle_errors `instance-attribute` ¶

handle_errors: (
    bool
    | str
    | type[Exception]
    | tuple[type[Exception], ...]
    | Callable[[Exception], str]
) = handle_errors

Error handling strategy for structured output via ToolStrategy.

True: Catch all errors with default error template
str: Catch all errors with this custom message
type[Exception]: Only catch this exception type with default message
tuple[type[Exception], ...]: Only catch these exception types with default message
Callable[[Exception], str]: Custom function that returns error message
False: No retry, let exceptions propagate

ProviderStrategy `dataclass` ¶

ProviderStrategy(schema: type[SchemaT] | dict[str, Any], *, strict: bool | None = None)

Bases: Generic[SchemaT]

Use the model provider's native structured output method.

Initialize ProviderStrategy with schema.

PARAMETER	DESCRIPTION
`schema`	Schema to enforce via the provider's native structured output. TYPE: `type[SchemaT] \| dict[str, Any]`
`strict`	Whether to request strict provider-side schema enforcement. TYPE: `bool \| None` DEFAULT: `None`

METHOD	DESCRIPTION
`to_model_kwargs`	Convert to kwargs to bind to a model to force structured output.

to_model_kwargs ¶

to_model_kwargs() -> dict[str, Any]

Convert to kwargs to bind to a model to force structured output.

RETURNS	DESCRIPTION
`dict[str, Any]`	The kwargs to bind to a model.

AutoStrategy ¶

AutoStrategy(schema: type[SchemaT] | dict[str, Any])

Bases: Generic[SchemaT]

Automatically select the best strategy for structured output.

Initialize AutoStrategy with schema.

Agents

agents ¶

create_agent ¶

`model` ¶

`tools` ¶

`system_prompt` ¶

`middleware` ¶

`response_format` ¶

`state_schema` ¶

`context_schema` ¶

`checkpointer` ¶

`store` ¶

`interrupt_before` ¶

`interrupt_after` ¶

`debug` ¶

`name` ¶

`cache` ¶

AgentState ¶

Structured output¶

ResponseFormat `module-attribute` ¶

ToolStrategy `dataclass` ¶

tool_message_content `instance-attribute` ¶

handle_errors `instance-attribute` ¶

ProviderStrategy `dataclass` ¶

to_model_kwargs ¶

AutoStrategy ¶

Agents

agents ¶

create_agent ¶

model ¶

tools ¶

system_prompt ¶

middleware ¶

response_format ¶

state_schema ¶

context_schema ¶

checkpointer ¶

store ¶

interrupt_before ¶

interrupt_after ¶

debug ¶

name ¶

cache ¶

AgentState ¶

Structured output¶

ResponseFormat module-attribute ¶

ToolStrategy dataclass ¶

tool_message_content instance-attribute ¶

handle_errors instance-attribute ¶

ProviderStrategy dataclass ¶

to_model_kwargs ¶

AutoStrategy ¶

`model` ¶

`tools` ¶

`system_prompt` ¶

`middleware` ¶

`response_format` ¶

`state_schema` ¶

`context_schema` ¶

`checkpointer` ¶

`store` ¶

`interrupt_before` ¶

`interrupt_after` ¶

`debug` ¶

`name` ¶

`cache` ¶

ResponseFormat `module-attribute` ¶

ToolStrategy `dataclass` ¶

tool_message_content `instance-attribute` ¶

handle_errors `instance-attribute` ¶

ProviderStrategy `dataclass` ¶