> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-srcomm-1772228869-09398c4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Frontend
> Build generative UIs with real-time streaming from LangChain agents, LangGraph graphs, and custom APIs
The `useStream` React hook provides seamless integration with LangGraph streaming capabilities. It handles all the complexities of streaming, state management, and branching logic, letting you focus on building great generative UI experiences.
Key features:
* **Messages streaming** — Handle a stream of message chunks to form a complete message
* **Automatic state management** — for messages, interrupts, loading states, and errors
* **Conversation branching** — Create alternate conversation paths from any point in the chat history
* **UI-agnostic design** — Bring your own components and styling
## Installation
Install the LangGraph SDK to use the `useStream` hook in your React application:
## Basic usage
The `useStream` hook connects to any LangGraph graph, whether that's running on from your own endpoint, or deployed using [LangSmith deployments](/langsmith/deployments).
```tsx theme={null}
import { useStream } from "@langchain/langgraph-sdk/react";
function Chat() {
const stream = useStream({
assistantId: "agent",
// Local development
apiUrl: "http://localhost:2024",
// Production deployment (LangSmith hosted)
// apiUrl: "https://your-deployment.us.langgraph.app"
});
const handleSubmit = (message: string) => {
stream.submit({
messages: [
{ content: message, type: "human" }
],
});
};
return (
{stream.messages.map((message, idx) => (
{message.type}: {message.content}
))}
{stream.isLoading &&
Loading...
}
{stream.error &&
Error: {stream.error.message}
}
);
}
```
Learn how to [deploy your agents to LangSmith](/oss/python/langchain/deploy) for production-ready hosting with built-in observability, authentication, and scaling.
The ID of the agent to connect to. When using LangSmith deployments, this must match the agent ID shown in your deployment dashboard. For custom API deployments or local development, this can be any string that your server uses to identify the agent.
The URL of the Agent Server. Defaults to `http://localhost:2024` for local development.
API key for authentication. Required when connecting to deployed agents on LangSmith.
Connect to an existing thread instead of creating a new one. Useful for resuming conversations.
Callback invoked when a new thread is created. Use this to persist the thread ID for later use.
Automatically resume an ongoing run when the component mounts. Set to `true` to use session storage, or provide a custom storage function.
Callback invoked when a new run is created. Useful for persisting run metadata for resumption.
Callback invoked when an error occurs during streaming.
Callback invoked when the stream completes successfully with the final state.
Handle custom events emitted from your agent using the `writer`. See [Custom streaming events](#custom-streaming-events).
Handle state update events after each graph step.
Handle metadata events with run and thread information.
The key in the graph state that contains the messages array.
Batch state updates for better rendering performance. Disable for immediate updates.
Initial state values to display while the first stream is loading. Useful for showing cached thread data immediately.
All messages in the current thread, including both human and AI messages.
The current graph state values. Type is inferred from the agent or graph type parameter.
Whether a stream is currently in progress. Use this to show loading indicators.
Any error that occurred during streaming. `null` when no error.
Current interrupt requiring user input, such as human-in-the-loop approval requests.
All tool calls across all messages, with their results and state (`pending`, `completed`, or `error`).
Submit new input to the agent. Pass `null` as input when resuming from an interrupt with a command. Options include `checkpoint` for branching, `optimisticValues` for optimistic updates, and `threadId` for optimistic thread creation.
Stop the current stream immediately.
Resume an existing stream by run ID. Use with `onCreated` for manual stream resumption.
Switch to a different branch in the conversation history.
Get all tool calls for a specific AI message.
Get metadata for a message, including streaming info like `langgraph_node` for identifying the source node, and `firstSeenState` for branching.
Tree representation of the thread for advanced branching controls in non-message based graphs.
## Thread management
Keep track of conversations with built-in thread management. You can access the current thread ID and get notified when new threads are created:
```tsx theme={null}
import { useState } from "react";
import { useStream } from "@langchain/langgraph-sdk/react";
function Chat() {
const [threadId, setThreadId] = useState(null);
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
threadId: threadId,
onThreadId: setThreadId,
});
// threadId is updated when a new thread is created
// Store it in URL params or localStorage for persistence
}
```
We recommend storing the `threadId` to let users resume conversations after page refreshes.
### Resume after page refresh
The `useStream` hook can automatically resume an ongoing run upon mounting by setting `reconnectOnMount: true`. This is useful for continuing a stream after a page refresh, ensuring no messages and events generated during the downtime are lost.
```tsx theme={null}
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
reconnectOnMount: true,
});
```
By default the ID of the created run is stored in `window.sessionStorage`, which can be swapped by passing a custom storage function:
```tsx theme={null}
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
reconnectOnMount: () => window.localStorage,
});
```
For manual control over the resumption process, use the run callbacks to persist metadata and `joinStream` to resume:
```tsx theme={null}
import { useStream } from "@langchain/langgraph-sdk/react";
import { useEffect, useRef } from "react";
function Chat({ threadId }: { threadId: string | null }) {
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
threadId,
onCreated: (run) => {
// Persist run ID when stream starts
window.sessionStorage.setItem(`resume:${run.thread_id}`, run.run_id);
},
onFinish: (_, run) => {
// Clean up when stream completes
window.sessionStorage.removeItem(`resume:${run?.thread_id}`);
},
});
// Resume stream on mount if there's a stored run ID
const joinedThreadId = useRef(null);
useEffect(() => {
if (!threadId) return;
const runId = window.sessionStorage.getItem(`resume:${threadId}`);
if (runId && joinedThreadId.current !== threadId) {
stream.joinStream(runId);
joinedThreadId.current = threadId;
}
}, [threadId]);
const handleSubmit = (text: string) => {
// Use streamResumable to ensure events aren't lost
stream.submit(
{ messages: [{ type: "human", content: text }] },
{ streamResumable: true }
);
};
}
```
See a complete implementation of stream resumption with `reconnectOnMount` and thread persistence in the `session-persistence` example.
## Optimistic updates
You can optimistically update the client state before performing a network request, providing immediate feedback to the user:
```tsx theme={null}
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
});
const handleSubmit = (text: string) => {
const newMessage = { type: "human" as const, content: text };
stream.submit(
{ messages: [newMessage] },
{
optimisticValues(prev) {
const prevMessages = prev.messages ?? [];
return { ...prev, messages: [...prevMessages, newMessage] };
},
}
);
};
```
### Optimistic thread creation
Use the `threadId` option in `submit` to enable optimistic UI patterns where you need to know the thread ID before the thread is created:
```tsx theme={null}
import { useState } from "react";
import { useStream } from "@langchain/langgraph-sdk/react";
function Chat() {
const [threadId, setThreadId] = useState(null);
const [optimisticThreadId] = useState(() => crypto.randomUUID());
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
threadId,
onThreadId: setThreadId,
});
const handleSubmit = (text: string) => {
// Navigate immediately without waiting for thread creation
window.history.pushState({}, "", `/threads/${optimisticThreadId}`);
// Create thread with the predetermined ID
stream.submit(
{ messages: [{ type: "human", content: text }] },
{ threadId: optimisticThreadId }
);
};
}
```
### Cached thread display
Use the `initialValues` option to display cached thread data immediately while the history is being loaded from the server:
```tsx theme={null}
function Chat({ threadId, cachedData }) {
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
threadId,
initialValues: cachedData?.values,
});
// Shows cached messages instantly, then updates when server responds
}
```
## Branching
Create alternate conversation paths by editing previous messages or regenerating AI responses. Use `getMessagesMetadata()` to access checkpoint information for branching:
```tsx Chat.tsx theme={null}
import { useStream } from "@langchain/langgraph-sdk/react";
import { BranchSwitcher } from "./BranchSwitcher";
function Chat() {
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "agent",
});
return (
{/* Edit human messages */}
{message.type === "human" && (
)}
{/* Regenerate AI messages */}
{message.type === "ai" && (
)}
{/* Switch between branches */}
stream.setBranch(branch)}
/>
);
})}
);
}
```
```tsx BranchSwitcher.tsx theme={null}
/**
* Component for navigating between conversation branches.
* Shows the current branch position and allows switching between alternatives.
*/
export function BranchSwitcher({
branch,
branchOptions,
onSelect,
}: {
branch: string | undefined;
branchOptions: string[] | undefined;
onSelect: (branch: string) => void;
}) {
if (!branchOptions || !branch) return null;
const index = branchOptions.indexOf(branch);
return (
{index + 1} / {branchOptions.length}
);
}
```
For advanced use cases, use the `experimental_branchTree` property to get the tree representation of the thread for non-message based graphs.
See a complete implementation of conversation branching with edit, regenerate, and branch switching in the `branching-chat` example.
## Type-safe streaming
The `useStream` hook supports full type inference when used with agents created via @\[`createAgent`] or graphs created with [`StateGraph`](https://reference.langchain.com/python/langgraph/graph/state/StateGraph). Pass `typeof agent` or `typeof graph` as the type parameter to automatically infer tool call types.
### With `createAgent`
When using @\[`createAgent`], tool call types are automatically inferred from the tools you register to your agent:
```python agent.py theme={null}
from langchain import create_agent, tool
@tool
def get_weather(location: str) -> str:
"""Get weather for a location."""
return f"Weather in {location}: Sunny, 72°F"
agent = create_agent(
model="openai:gpt-4.1-mini",
tools=[get_weather],
)
```
```tsx Chat.tsx theme={null}
import { useStream } from "@langchain/langgraph-sdk/react";
import type { AgentState } from "./types";
function Chat() {
// Use the manually defined state type
const stream = useStream({
assistantId: "agent",
apiUrl: "http://localhost:2024",
});
// stream.toolCalls[0].call.name is typed as "get_weather"
// stream.toolCalls[0].call.args is typed as { location: string }
}
```
```typescript types.ts theme={null}
import type { Message } from "@langchain/langgraph-sdk";
// Define tool call types to match your Python agent
export type GetWeatherToolCall = {
name: "get_weather";
args: { location: string };
id?: string;
};
export type AgentToolCalls = GetWeatherToolCall;
export interface AgentState {
messages: Message[];
}
```
### With `StateGraph`
For custom [`StateGraph`](https://reference.langchain.com/python/langgraph/graph/state/StateGraph) applications, the state types are inferred from the graph's annotation:
```python graph.py theme={null}
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langchain_openai import ChatOpenAI
from typing import TypedDict, Annotated
class State(TypedDict):
messages: Annotated[list, add_messages]
model = ChatOpenAI(model="gpt-4.1-mini")
async def agent(state: State) -> dict:
response = await model.ainvoke(state["messages"])
return {"messages": [response]}
workflow = StateGraph(State)
workflow.add_node("agent", agent)
workflow.add_edge(START, "agent")
workflow.add_edge("agent", END)
graph = workflow.compile()
```
```tsx Chat.tsx theme={null}
import { useStream } from "@langchain/langgraph-sdk/react";
import type { GraphState } from "./types";
function Chat() {
// Use the manually defined state type
const stream = useStream({
assistantId: "my-graph",
apiUrl: "http://localhost:2024",
});
// stream.values is typed based on your defined state
}
```
```typescript types.ts theme={null}
import type { Message } from "@langchain/langgraph-sdk";
// Define state to match your Python graph's State TypedDict
export interface GraphState {
messages: Message[];
}
```
### With Annotation types
If you're using LangGraph.js, you can reuse your graph's annotation types. Make sure to only import types to avoid importing the entire LangGraph.js runtime:
### Advanced type configuration
You can specify additional type parameters for interrupts, custom events, and configurable options:
## Rendering tool calls
Use `getToolCalls` to extract and render tool calls from AI messages. Tool calls include the call details, result (if completed), and state.
```python agent.py theme={null}
from langchain import create_agent, tool
@tool
def get_weather(location: str) -> str:
"""Get the current weather for a location."""
return f'{{"status": "success", "content": "Weather in {location}: Sunny, 72°F"}}'
agent = create_agent(
model="openai:gpt-4.1-mini",
tools=[get_weather],
)
```
```tsx Chat.tsx theme={null}
import { useStream } from "@langchain/langgraph-sdk/react";
import type { AgentState, AgentToolCalls } from "./types";
import { ToolCallCard } from "./ToolCallCard";
import { MessageBubble } from "./MessageBubble";
function Chat() {
const stream = useStream({
assistantId: "agent",
apiUrl: "http://localhost:2024",
});
return (
{stream.messages.map((message, idx) => {
if (message.type === "ai") {
const toolCalls = stream.getToolCalls(message);
if (toolCalls.length > 0) {
return (
{toolCalls.map((toolCall) => (
))}
);
}
}
return ;
})}
);
}
```
```tsx ToolCallCard.tsx theme={null}
import type { ToolCallWithResult, ToolCallState } from "@langchain/langgraph-sdk/react";
import type { ToolMessage } from "@langchain/langgraph-sdk";
import type { AgentToolCalls, GetWeatherToolCall } from "./types";
import { parseToolResult } from "./utils";
import { WeatherCard } from "./WeatherCard";
import { GenericToolCallCard } from "./GenericToolCallCard";
export function ToolCallCard({
toolCall,
}: {
toolCall: ToolCallWithResult;
}) {
const { call, result, state } = toolCall;
if (call.name === "get_weather") {
return ;
}
return ;
}
```
```tsx WeatherCard.tsx theme={null}
import type { ToolCallState } from "@langchain/langgraph-sdk/react";
import type { ToolMessage } from "@langchain/langgraph-sdk";
import type { GetWeatherToolCall } from "./types";
import { parseToolResult } from "./utils";
export function WeatherCard({
call,
result,
state,
}: {
call: GetWeatherToolCall;
result?: ToolMessage;
state: ToolCallState;
}) {
const isLoading = state === "pending";
const parsedResult = parseToolResult(result);
return (
{call.args.location}
{isLoading && Loading...}
{parsedResult.status === "error" ? (
{parsedResult.content}
) : (
{parsedResult.content || "Fetching weather..."}
)}
);
}
```
```typescript types.ts theme={null}
import type { Message } from "@langchain/langgraph-sdk";
// Define tool call types to match your Python agent's tools
export type GetWeatherToolCall = {
name: "get_weather";
args: { location: string };
id?: string;
};
// Union of all tool calls in your agent
export type AgentToolCalls = GetWeatherToolCall;
// Define state type with your tool calls
export interface AgentState {
messages: Message[];
}
```
```typescript utils.ts theme={null}
import type { ToolMessage } from "@langchain/langgraph-sdk";
export function parseToolResult(result?: ToolMessage): {
status: string;
content: string;
} {
if (!result) return { status: "pending", content: "" };
try {
return JSON.parse(result.content as string);
} catch {
return { status: "success", content: result.content as string };
}
}
```
See a complete implementation of tool call rendering with weather, calculator, and note-taking tools in the `tool-calling-agent` example.
## Custom streaming events
Stream custom data from your agent using the `writer` in your tools or nodes. Handle these events in the UI with the `onCustomEvent` callback.
```python agent.py theme={null}
import asyncio
import time
from langchain import create_agent, tool
from langchain.types import ToolRuntime
@tool
async def analyze_data(data_source: str, *, config: ToolRuntime) -> str:
"""Analyze data with progress updates."""
steps = ["Connecting...", "Fetching...", "Processing...", "Done!"]
for i, step in enumerate(steps):
# Emit progress events during execution
if config.writer:
config.writer({
"type": "progress",
"id": f"analysis-{int(time.time() * 1000)}",
"message": step,
"progress": ((i + 1) / len(steps)) * 100,
})
await asyncio.sleep(0.5)
return '{"result": "Analysis complete"}'
agent = create_agent(
model="openai:gpt-4.1-mini",
tools=[analyze_data],
)
```
```tsx Chat.tsx theme={null}
import { useState, useCallback } from "react";
import { useStream } from "@langchain/langgraph-sdk/react";
import type { AgentState } from "./types";
interface ProgressData {
type: "progress";
id: string;
message: string;
progress: number;
}
function isProgressData(data: unknown): data is ProgressData {
return (
typeof data === "object" &&
data !== null &&
"type" in data &&
(data as ProgressData).type === "progress"
);
}
function CustomStreamingUI() {
const [progressData, setProgressData] = useState>(
new Map()
);
const handleCustomEvent = useCallback((data: unknown) => {
if (isProgressData(data)) {
setProgressData((prev) => {
const updated = new Map(prev);
updated.set(data.id, data);
return updated;
});
}
}, []);
const stream = useStream({
assistantId: "custom-streaming",
apiUrl: "http://localhost:2024",
onCustomEvent: handleCustomEvent,
});
return (
);
}
```
```typescript types.ts theme={null}
import type { Message } from "@langchain/langgraph-sdk";
// Define tool calls to match your Python agent
export type AnalyzeDataToolCall = {
name: "analyze_data";
args: { data_source: string };
id?: string;
};
export type AgentToolCalls = AnalyzeDataToolCall;
export interface AgentState {
messages: Message[];
}
```
See a complete implementation of custom events with progress bars, status badges, and file operation cards in the `custom-streaming` example.
## Event handling
The `useStream` hook provides callback options that give you access to different types of streaming events. You don't need to explicitly configure stream modes—just pass callbacks for the event types you want to handle:
### Available callbacks
| Callback | Description | Stream mode |
| ----------------- | ------------------------------------------------------------ | ----------- |
| `onUpdateEvent` | Called when a state update is received after each graph step | `updates` |
| `onCustomEvent` | Called when a custom event is received from your graph | `custom` |
| `onMetadataEvent` | Called with run and thread metadata | `metadata` |
| `onError` | Called when an error occurs | - |
| `onFinish` | Called when the stream completes | - |
## Multi-agent streaming
When working with multi-agent systems or graphs with multiple nodes, use message metadata to identify which node generated each message. This is particularly useful when multiple LLMs run in parallel and you want to display their outputs with distinct visual styling.
```python agent.py theme={null}
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END, Send
from langgraph.graph.state import CompiledStateGraph
from langchain.messages import BaseMessage, AIMessage
from typing import TypedDict, Annotated
import operator
# Use different model instances for variety
analytical_model = ChatOpenAI(model="gpt-4.1-mini", temperature=0.3)
creative_model = ChatOpenAI(model="gpt-4.1-mini", temperature=0.9)
practical_model = ChatOpenAI(model="gpt-4.1-mini", temperature=0.5)
class State(TypedDict):
messages: Annotated[list[BaseMessage], operator.add]
topic: str
analytical_research: str
creative_research: str
practical_research: str
def fan_out_to_researchers(state: State) -> list[Send]:
return [
Send("researcher_analytical", state),
Send("researcher_creative", state),
Send("researcher_practical", state),
]
def dispatcher(state: State) -> dict:
last_message = state["messages"][-1] if state["messages"] else None
topic = last_message.content if last_message else ""
return {"topic": topic}
async def researcher_analytical(state: State) -> dict:
response = await analytical_model.ainvoke([
{"role": "system", "content": "You are an analytical research expert."},
{"role": "user", "content": f"Research: {state['topic']}"},
])
return {
"analytical_research": response.content,
"messages": [AIMessage(content=response.content, name="researcher_analytical")],
}
# Similar nodes for creative and practical researchers...
workflow = StateGraph(State)
workflow.add_node("dispatcher", dispatcher)
workflow.add_node("researcher_analytical", researcher_analytical)
workflow.add_node("researcher_creative", researcher_creative)
workflow.add_node("researcher_practical", researcher_practical)
workflow.add_edge(START, "dispatcher")
workflow.add_conditional_edges("dispatcher", fan_out_to_researchers)
workflow.add_edge("researcher_analytical", END)
workflow.add_edge("researcher_creative", END)
workflow.add_edge("researcher_practical", END)
agent: CompiledStateGraph = workflow.compile()
```
```tsx Chat.tsx theme={null}
import { useStream } from "@langchain/langgraph-sdk/react";
import type { AgentState } from "./types";
import { MessageBubble } from "./MessageBubble";
// Node configuration for visual display
const NODE_CONFIG: Record = {
researcher_analytical: { label: "Analytical Research", color: "cyan" },
researcher_creative: { label: "Creative Research", color: "purple" },
researcher_practical: { label: "Practical Research", color: "emerald" },
};
function MultiAgentChat() {
const stream = useStream({
assistantId: "parallel-research",
apiUrl: "http://localhost:2024",
});
return (
);
}
```
```typescript types.ts theme={null}
import type { Message } from "@langchain/langgraph-sdk";
export interface AgentState {
messages: Message[];
}
```
```typescript utils.ts theme={null}
import type { Message, AIMessage } from "@langchain/langgraph-sdk";
/**
* Extracts reasoning/thinking content from an AI message.
* Supports both OpenAI reasoning and Anthropic extended thinking.
*/
export function getReasoningFromMessage(message: Message): string | undefined {
type MessageWithExtras = AIMessage & {
additional_kwargs?: {
reasoning?: {
summary?: Array<{ type: string; text: string }>;
};
};
contentBlocks?: Array<{ type: string; thinking?: string }>;
};
const msg = message as MessageWithExtras;
// Check for OpenAI reasoning in additional_kwargs
if (msg.additional_kwargs?.reasoning?.summary) {
const content = msg.additional_kwargs.reasoning.summary
.filter((item) => item.type === "summary_text")
.map((item) => item.text)
.join("");
if (content.trim()) return content;
}
// Check for Anthropic thinking in contentBlocks
if (msg.contentBlocks?.length) {
const thinking = msg.contentBlocks
.filter((b) => b.type === "thinking" && b.thinking)
.map((b) => b.thinking)
.join("\n");
if (thinking) return thinking;
}
// Check for thinking in message.content array
if (Array.isArray(msg.content)) {
const thinking = msg.content
.filter((b): b is { type: "thinking"; thinking: string } =>
typeof b === "object" && b?.type === "thinking" && "thinking" in b
)
.map((b) => b.thinking)
.join("\n");
if (thinking) return thinking;
}
return undefined;
}
/**
* Extracts text content from a message.
*/
export function getTextContent(message: Message): string {
if (typeof message.content === "string") return message.content;
if (Array.isArray(message.content)) {
return message.content
.filter((c): c is { type: "text"; text: string } => c.type === "text")
.map((c) => c.text)
.join("");
}
return "";
}
```
See a complete implementation of reasoning token display with OpenAI and Anthropic models in the `reasoning-agent` example.
## Custom state types
For custom LangGraph applications, embed your tool call types in your state's messages property.
## Custom transport
For custom API endpoints or non-standard deployments, use the `transport` option with `FetchStreamTransport` to connect to any streaming API.
## Related
* [Streaming overview](/oss/python/langchain/streaming/overview) — Server-side streaming with LangChain agents
* [useStream API Reference](https://reference.langchain.com/javascript/functions/_langchain_langgraph-sdk.react.useStream.html) — Full API documentation
* [Agent Chat UI](/oss/python/langchain/ui) — Pre-built chat interface for LangGraph agents
* [Human-in-the-loop](/oss/python/langchain/human-in-the-loop) — Configuring interrupts for human review
* [Multi-agent systems](/oss/python/langchain/multi-agent) — Building agents with multiple LLMs
***
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/streaming/frontend.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.